@ardennguyen/zalo-agent-cli 1.0.7 → 2.0.0

package/src/mcp/message-buffer.js

@@ -1,8 +1,20 @@
 /**
  * Ring buffer storing messages per thread with cursor-based incremental reads.
  * Shared by both stdio and HTTP MCP transports.
+ *
+ * Several bots can share one listener, so "read" is per consumer: each named
+ * consumer has its own read cursor, and marking messages read moves only that
+ * 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.
  */
 
+/** The consumer a caller that names none reads as. */
+export const DEFAULT_CONSUMER = "default";
+
+/** Consumers remembered at most; the least recently active is forgotten first. */
+const MAX_CONSUMERS = 256;
+
 export class MessageBuffer {
     /**
      * @param {number} maxSize - Max messages per thread before eviction
@@ -14,6 +26,17 @@ export class MessageBuffer {
         this._maxSize = maxSize;
         this._maxAge = maxAge;
         this._globalCursor = 0;
+        /** @type {Map<string, { cursor: number, at: number }>} */
+        this._readCursors = new Map();
+    }
+
+    /**
+     * The read cursor of one consumer: messages after it are unread for them.
+     * @param {string} [consumer="default"]
+     * @returns {number}
+     */
+    readCursor(consumer = DEFAULT_CONSUMER) {
+        return this._readCursors.get(consumer)?.cursor ?? 0;
     }
 
     /**
@@ -60,18 +83,25 @@ export class MessageBuffer {
     }
 
     /**
-     * Advance read cursor — discard messages at or before given cursor.
+     * Advance one consumer's read cursor to `cursor`. Nothing is deleted, and no
+     * other consumer's cursor moves; a cursor never moves backwards.
      * @param {number} cursor
-     * @returns {number} Count of discarded messages
+     * @param {string} [consumer="default"]
+     * @returns {number} how many buffered messages this newly marked read for that consumer
      */
-    markRead(cursor) {
-        let discarded = 0;
+    markRead(cursor, consumer = DEFAULT_CONSUMER) {
+        const from = this.readCursor(consumer);
+        const to = Math.max(from, Number(cursor) || 0);
+        let marked = 0;
         for (const [, thread] of this._threads) {
-            const before = thread.messages.length;
-            thread.messages = thread.messages.filter((m) => m._cursor > cursor);
-            discarded += before - thread.messages.length;
+            for (const m of thread.messages) if (m._cursor > from && m._cursor <= to) marked++;
+        }
+        this._readCursors.delete(consumer); // re-insert: Map order is recency
+        this._readCursors.set(consumer, { cursor: to, at: Date.now() });
+        while (this._readCursors.size > MAX_CONSUMERS) {
+            this._readCursors.delete(this._readCursors.keys().next().value);
         }
-        return discarded;
+        return marked;
     }
 
     /**

package/src/mcp/message-buffer.test.js

@@ -108,23 +108,22 @@ describe("MessageBuffer cursor-based incremental reads", () => {
 });
 
 describe("MessageBuffer markRead", () => {
-    it("discards messages at or before cursor and returns count", () => {
+    it("marks messages at or before cursor read and returns how many", () => {
         const buf = new MessageBuffer();
         buf.push("t1", msg("a"));
         buf.push("t1", msg("b"));
         const { cursor } = buf.read("t1");
-        const discarded = buf.markRead(cursor);
-        assert.equal(discarded, 2);
+        assert.equal(buf.markRead(cursor), 2);
     });
 
-    it("messages after cursor are kept", () => {
+    it("messages after the cursor stay unread for that consumer", () => {
         const buf = new MessageBuffer();
         buf.push("t1", msg("a"));
         const { cursor: c1 } = buf.read("t1");
         buf.push("t1", msg("b"));
 
         buf.markRead(c1);
-        const { messages } = buf.read("t1");
+        const { messages } = buf.read("t1", buf.readCursor());
         assert.equal(messages.length, 1);
         assert.equal(messages[0].text, "b");
     });
@@ -138,13 +137,56 @@ describe("MessageBuffer markRead", () => {
         assert.equal(second, 0);
     });
 
-    it("markRead across multiple threads discards from all", () => {
+    it("markRead covers every thread", () => {
         const buf = new MessageBuffer();
         buf.push("t1", msg("a"));
         buf.push("t2", msg("b"));
         const { cursor } = buf.read(); // reads all
-        const discarded = buf.markRead(cursor);
-        assert.equal(discarded, 2);
+        assert.equal(buf.markRead(cursor), 2);
+    });
+});
+
+// Triage M7: several bots share one listener. markRead used to delete, so one
+// bot marking read emptied every other bot's inbox.
+describe("MessageBuffer read cursors, per consumer", () => {
+    it("markRead deletes nothing: another consumer still sees every message", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        const { cursor } = buf.read("t1");
+        buf.markRead(cursor, "bot-1");
+
+        assert.equal(buf.read("t1", buf.readCursor("bot-1")).messages.length, 0);
+        // Red if markRead goes back to deleting for everyone.
+        assert.equal(buf.read("t1", buf.readCursor("bot-2")).messages.length, 2);
+    });
+
+    it("each consumer's cursor is its own, and never moves backwards", () => {
+        const buf = new MessageBuffer();
+        for (const t of ["a", "b", "c"]) buf.push("t1", msg(t));
+        buf.markRead(2, "bot-1");
+        buf.markRead(1, "bot-1");
+        assert.equal(buf.readCursor("bot-1"), 2);
+        assert.equal(buf.readCursor("bot-2"), 0);
+        assert.equal(buf.readCursor(), 0, "the default consumer is untouched");
+    });
+
+    it("unread counts follow the consumer's cursor", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        buf.markRead(1, "bot-1");
+        assert.equal(buf.getStats(buf.readCursor("bot-1"))[0].unread, 1);
+        assert.equal(buf.getStats(buf.readCursor("bot-2"))[0].unread, 2);
+    });
+
+    it("remembers a bounded number of consumers, forgetting the least recent", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        for (let i = 0; i < 300; i++) buf.markRead(1, `bot-${i}`);
+        assert.ok(buf._readCursors.size <= 256);
+        assert.equal(buf.readCursor("bot-299"), 1, "the most recent is kept");
+        assert.equal(buf.readCursor("bot-0"), 0, "the oldest is forgotten");
     });
 });
 
@@ -210,7 +252,7 @@ describe("MessageBuffer multi-thread isolation", () => {
         assert.equal(r2.messages[0].text, "from-t2");
     });
 
-    it("markRead on shared cursor only keeps messages after it in each thread", () => {
+    it("markRead on the global cursor leaves unread only what came after it, in each thread", () => {
         const buf = new MessageBuffer();
         buf.push("t1", msg("t1-a"));
         const { cursor: midCursor } = buf.read();
@@ -218,8 +260,8 @@ describe("MessageBuffer multi-thread isolation", () => {
 
         buf.markRead(midCursor);
 
-        const r1 = buf.read("t1");
-        const r2 = buf.read("t2");
+        const r1 = buf.read("t1", buf.readCursor());
+        const r2 = buf.read("t2", buf.readCursor());
         assert.equal(r1.messages.length, 0);
         assert.equal(r2.messages.length, 1);
     });
@@ -255,14 +297,24 @@ describe("MessageBuffer getStats", () => {
     });
 
     it("excludes threads with no messages", () => {
-        const buf = new MessageBuffer(500, 999999);
-        buf.push("t1", msg("a"));
-        const { cursor } = buf.read("t1");
-        buf.markRead(cursor); // discards all messages
+        // markRead no longer empties a thread (it moves a consumer's cursor);
+        // eviction is what leaves one with no messages.
+        const buf = new MessageBuffer(500, 1000);
+        buf.push("t1", msg("a", Date.now() - 5000)); // already past maxAge
 
         const stats = buf.getStats(0);
         assert.equal(stats.length, 0);
     });
+
+    it("keeps listing a thread whose messages were all marked read, with 0 unread", () => {
+        const buf = new MessageBuffer(500, 999999);
+        buf.push("t1", msg("a"));
+        const { cursor } = buf.read("t1");
+        buf.markRead(cursor);
+        const [t1] = buf.getStats(buf.readCursor());
+        assert.equal(t1.unread, 0);
+        assert.equal(t1.total, 1);
+    });
 });
 
 describe("MessageBuffer getThreadType", () => {

package/src/mcp/notifier.js

@@ -5,10 +5,21 @@
 
 import { parseDuration } from "./mcp-config.js";
 
-/** Emoji prefix per message type for notification previews */
+/**
+ * Emoji prefix per message type for notification previews.
+ *
+ * Keyed on the shared type vocabulary (`photo`, not `image`) that
+ * `classifyLiveMessage` produces for every capture path; `image` stays as an
+ * alias so a message buffered by an older build still renders.
+ */
 const TYPE_EMOJI = {
     text: "💬",
+    photo: "📷",
     image: "📷",
+    sticker: "😀",
+    card: "🪪",
+    location: "📍",
+    doodle: "🖌️",
     file: "📎",
     link: "🔗",
     video: "🎬",
@@ -20,7 +31,12 @@ const TYPE_EMOJI = {
 /** Vietnamese label per message type for notification breakdown */
 const TYPE_LABEL = {
     text: "text",
+    photo: "ảnh",
     image: "ảnh",
+    sticker: "sticker",
+    card: "thẻ",
+    location: "vị trí",
+    doodle: "hình vẽ",
     file: "file",
     link: "link",
     video: "video",

package/src/mcp/notifier.test.js

@@ -1,3 +1,9 @@
+// sandbox.js FIRST: it redirects HOME/USERPROFILE before
+// credentials.js freezes CONFIG_DIR at module-eval time. This file
+// reaches that module transitively, so without the redirect it binds
+// to the real ~/.zalo-agent-cli/. Enforced by
+// tests/cli/sandbox-discipline.test.js.
+import "../../tests/helpers/sandbox.js";
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { ZaloNotifier } from "./notifier.js";

package/src/utils/bank-helpers.js

@@ -5,7 +5,9 @@
 import { mkdtempSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
-import nodefetch from "node-fetch";
+// Node >=22 (see engines in package.json) has a native, global `fetch` —
+// no need for the `node-fetch` package, which drags in a deprecated
+// node-domexception polyfill via formdata-polyfill/fetch-blob.
 
 /** Bank name aliases (lowercase, no spaces) → BIN codes. */
 export const BANK_NAME_TO_BIN = {
@@ -219,9 +221,12 @@ export async function generateQrTransferImage(bin, accountNumber, amount = null,
     const outPath = join(tmpDir, "qr.png");
 
     try {
-        const resp = await nodefetch(url, {
+        // node-fetch's `timeout` option isn't a thing on native fetch —
+        // use AbortSignal.timeout() instead (same pattern already used for
+        // the webhook POST in commands/listen.js).
+        const resp = await fetch(url, {
             headers: { "User-Agent": "Mozilla/5.0" },
-            timeout: 15000,
+            signal: AbortSignal.timeout(15000),
         });
         if (!resp.ok) return null;
         const buffer = Buffer.from(await resp.arrayBuffer());

package/src/utils/device-fingerprint.js

@@ -0,0 +1,72 @@
+/**
+ * Generates a randomized-but-internally-consistent browser fingerprint
+ * (User-Agent + matching Client Hints) for the one-time QR login handshake.
+ *
+ * Why this exists: zca-js's default QR-login fingerprint is broken and
+ * identical across every install on earth — it sends a literal
+ * "...Firefox/133.0" User-Agent header while our zca-js patch's
+ * secChUaHeaders() fallback (and, before this patch, every hardcoded call
+ * site in loginQR.js) separately claims Chromium/Chrome v130 Client Hints
+ * on every QR-flow request to id.zalo.me. Real browsers never produce that
+ * combination — Firefox doesn't send sec-ch-ua headers at all — and Zalo's
+ * server appears to read the Client Hints for the "Thiết bị" device label
+ * shown on the phone's QR-confirm screen, which is why every zca-js login
+ * shows "Chrome - Windows 10" regardless of what's actually running the
+ * CLI. Beyond being cosmetically wrong, a fingerprint that's byte-identical
+ * across every zca-js user is itself a correlatable signal.
+ *
+ * Scope: this only matters for the INITIAL QR-login handshake. Once logged
+ * in, the chosen userAgent is persisted in that account's credentials file
+ * (see extractCredentials()/loginWithCredentials() in zalo-client.js) and
+ * reused consistently for every subsequent API call — so a fresh, plausible,
+ * internally-consistent choice made once here, at first login, is enough;
+ * it doesn't need to be regenerated per-command. Re-scanning to log into the
+ * same account again later (after a full logout, not just a session resume)
+ * gets a freshly randomized fingerprint, same as a real user occasionally
+ * updating their browser — that's expected, not a bug.
+ */
+
+const CHROME_VERSIONS = ["131.0.0.0", "130.0.0.0", "129.0.0.0", "128.0.0.0"];
+
+/**
+ * Windows-first, Chrome-only presets. Deliberately not branching into
+ * Firefox/Safari: those browsers don't send sec-ch-ua headers at all, and
+ * Zalo's own device-label rendering already appears tuned for Chrome/Chromium
+ * (see the hardcoded literals this patch replaces) — straying from Chrome
+ * would trade one kind of oddity for another. Varying version + OS build is
+ * enough to avoid every install presenting an identical fingerprint.
+ */
+const PRESETS = [
+    ...CHROME_VERSIONS.map((v) => ({
+        userAgent: `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${v} Safari/537.36`,
+        secChUaPlatform: '"Windows"',
+    })),
+    ...CHROME_VERSIONS.map((v) => ({
+        userAgent: `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${v} Safari/537.36`,
+        secChUaPlatform: '"macOS"',
+    })),
+];
+
+function buildSecChUa(chromeVersion) {
+    const major = chromeVersion.split(".")[0];
+    // Matches the brand-list shape real Chrome sends (order, quoting, the
+    // "Not?A_Brand" filler entry — all part of Chrome's actual GREASE
+    // pattern for this header, not something we're inventing).
+    return `"Chromium";v="${major}", "Google Chrome";v="${major}", "Not?A_Brand";v="99"`;
+}
+
+/**
+ * Pick a random, internally-consistent fingerprint for a fresh QR login.
+ * @returns {{userAgent: string, secChUa: string, secChUaPlatform: string, secChUaMobile: string}}
+ */
+export function generateDeviceFingerprint() {
+    const preset = PRESETS[Math.floor(Math.random() * PRESETS.length)];
+    const versionMatch = preset.userAgent.match(/Chrome\/([\d.]+)/);
+    const chromeVersion = versionMatch ? versionMatch[1] : CHROME_VERSIONS[0];
+    return {
+        userAgent: preset.userAgent,
+        secChUa: buildSecChUa(chromeVersion),
+        secChUaPlatform: preset.secChUaPlatform,
+        secChUaMobile: "?0",
+    };
+}

package/src/utils/mentions.js

@@ -0,0 +1,140 @@
+/**
+ * Zalo @-mention offsets.
+ *
+ * A mention is `{ pos, uid, len }`, where `pos` and `len` are **UTF-16
+ * code-unit offsets into the message string** — not byte offsets, and not
+ * grapheme counts. Zalo renders the tag over exactly `text.slice(pos, pos +
+ * len)`, so an offset that is off by one paints the highlight over the wrong
+ * span and the tagged person may not be notified at all.
+ *
+ * Measured against real mentions in a local cache (name changed):
+ *
+ *     text  "Em ko biết mở ch ạ @Trần Bích Ngọc"   { pos: 19, len: 15 }
+ *     text.slice(19, 34)              === "@Trần Bích Ngọc"       correct
+ *     Buffer.from(text).slice(19, 34) -> "h ạ @Trần Bí…"          wrong
+ *
+ * Accented Vietnamese is exactly where hand-counted offsets break, and it is
+ * most of what this CLI sends. So `--mention <pos:uid:len>` stays for
+ * back-compat, but the `@[uid]` token form below computes the offsets from
+ * the string it just built and is the one to reach for.
+ */
+
+/** The uid Zalo reserves for @All. zca-js turns it into `type: 1`. */
+export const ALL_MENTION_UID = "-1";
+
+/**
+ * Label used for `@[-1]` when no name is supplied.
+ *
+ * Zalo's own clients write the literal "@All" (confirmed on real @All rows
+ * in the cache: `{ uid: "-1", pos: 0, len: 4, type: 1 }`), including in
+ * Vietnamese groups. Do not localize this.
+ */
+export const ALL_MENTION_LABEL = "All";
+
+/**
+ * `@[uid]` — the token expanded by {@link expandMentions}.
+ *
+ * Deliberately restricted to decimal ids (plus `-1` for @All), which is every
+ * uid Zalo accepts in a mention. Anything else in brackets — `@[see below]`,
+ * `@[TODO]` — is left in the text verbatim rather than turned into a mention
+ * of a uid that does not exist.
+ */
+const MENTION_TOKEN = /@\[(-?\d+)\]/g;
+
+/**
+ * Parse the legacy `--mention pos:uid:len` specs.
+ *
+ * Kept because scripts pass it; `@[uid]` tokens are the safe way in. Specs
+ * that are not three colon-separated parts, or whose pos/len are not numbers,
+ * are dropped rather than sent as NaN — zca-js's own filter would discard
+ * them anyway, silently and later.
+ *
+ * @param {string[]} [specs] - raw `pos:uid:len` strings
+ * @returns {{pos: number, uid: string, len: number}[]}
+ */
+export function parseMentionSpecs(specs) {
+    return (specs || [])
+        .map((spec) => {
+            const [pos, uid, len] = String(spec).split(":");
+            if (!uid) return null;
+            const parsed = { pos: Number(pos), uid, len: Number(len) };
+            if (!Number.isFinite(parsed.pos) || !Number.isFinite(parsed.len)) return null;
+            return parsed;
+        })
+        .filter(Boolean);
+}
+
+/**
+ * Expand `@[uid]` tokens into `@Display Name`, recording each mention's
+ * offsets in the string that comes out.
+ *
+ * Because the offsets are measured on the built string rather than counted by
+ * hand, they are correct whatever the surrounding text contains — accents,
+ * emoji, earlier mentions of different lengths.
+ *
+ * `edits` reports each substitution in *input* coordinates so that text
+ * styles counted against the pre-expansion message can be moved with
+ * {@link shiftStyles}.
+ *
+ * @param {string} text - message body, possibly containing `@[uid]` tokens
+ * @param {(uid: string) => (string|null|undefined)} [resolveName] - uid → display
+ *   name; anything falsy falls back to "All" for `@[-1]` and to the uid itself
+ *   otherwise, so an unknown user still gets a syntactically valid mention
+ * @returns {{text: string, mentions: {pos: number, uid: string, len: number}[],
+ *            edits: {start: number, oldLen: number, newLen: number}[]}}
+ */
+export function expandMentions(text, resolveName) {
+    const src = String(text ?? "");
+    const mentions = [];
+    const edits = [];
+    let out = "";
+    let cursor = 0;
+
+    // lastIndex is shared state on a module-level regex, so iterate a fresh copy.
+    const token = new RegExp(MENTION_TOKEN.source, "g");
+    let match;
+    while ((match = token.exec(src)) !== null) {
+        const uid = match[1];
+        const resolved = typeof resolveName === "function" ? resolveName(uid) : null;
+        const name = resolved || (uid === ALL_MENTION_UID ? ALL_MENTION_LABEL : uid);
+        const label = `@${name}`;
+
+        out += src.slice(cursor, match.index);
+        mentions.push({ pos: out.length, uid, len: label.length });
+        edits.push({ start: match.index, oldLen: match[0].length, newLen: label.length });
+        out += label;
+        cursor = match.index + match[0].length;
+    }
+    out += src.slice(cursor);
+
+    return { text: out, mentions, edits };
+}
+
+/**
+ * Move text styles across the edits {@link expandMentions} made.
+ *
+ * `--style start:len:style` and `--md` both produce offsets against the
+ * message *before* mentions expand, and a `@[uid]` token is almost always
+ * shorter than the name it becomes. Without this, `--md` plus a mention
+ * silently paints bold over the wrong words.
+ *
+ * A style that starts after an edit moves by the edit's delta; a style that
+ * spans one grows by it (`**hi @[123]**` keeps the whole run bold).
+ *
+ * @param {{start: number, len: number, st: string}[]} styles
+ * @param {{start: number, oldLen: number, newLen: number}[]} edits
+ * @returns {{start: number, len: number, st: string}[]}
+ */
+export function shiftStyles(styles, edits) {
+    if (!edits || edits.length === 0) return styles;
+    return styles.map((style) => {
+        let start = style.start;
+        let len = style.len;
+        for (const edit of edits) {
+            const delta = edit.newLen - edit.oldLen;
+            if (edit.start < style.start) start += delta;
+            else if (edit.start < style.start + style.len) len += delta;
+        }
+        return { ...style, start, len };
+    });
+}

package/src/utils/my-documents.js

@@ -0,0 +1,95 @@
+/**
+ * `me` in a `msg` command's thread argument means My Documents.
+ *
+ * Zalo's self-chat ("My Documents", "Cloud của tôi") is not the account's own
+ * uid. It is a conversation of its own, and sending there is an ordinary 1-1
+ * send to its id -- measured against Zalo Web on 2026-09-29, and the replay of
+ * `sendMessage(text, <that id>, 0)` is byte-identical to the web's request.
+ * The web learns the id from the login config (`send2me_id`), and zca-js
+ * already keeps that config at `ctx.loginInfo`. Sending to the own uid instead
+ * is rejected with "Tham số không hợp lệ".
+ *
+ * So both `me` and the own uid resolve to `send2me_id`, as a 1-1:
+ *
+ *   - `me` is the documented alias.
+ *   - The own uid is mapped too, with a notice, because it can never name a
+ *     conversation Zalo accepts -- the only thing someone can mean by it is
+ *     the self-chat, and refusing would just turn the obvious guess into an
+ *     error. Nothing that worked before changes meaning.
+ *
+ * When the session carries no `send2me_id`, both fail with a clear message
+ * rather than send to an id Zalo rejects.
+ */
+
+/** The alias, compared case-insensitively. */
+export const SELF_ALIAS = "me";
+
+/**
+ * Resolve a thread argument that names the self-chat.
+ *
+ * @param {string} threadId - the argument as typed
+ * @param {object} session
+ * @param {string|null} session.ownId - this account's uid, when logged in
+ * @param {() => (string|null|undefined)} session.send2meId - reads `loginInfo.send2me_id`
+ * @param {boolean} [session.groupRequested] - the caller asked for `-t 1`
+ * @returns {null|{threadId: string, notice: string}|{error: string}} null when it is not a self reference
+ */
+export function resolveSelfThread(threadId, { ownId, send2meId, groupRequested = false }) {
+    const typed = String(threadId ?? "").trim();
+    const alias = typed.toLowerCase() === SELF_ALIAS;
+    const own = Boolean(ownId) && typed === String(ownId);
+    if (!alias && !own) return null;
+
+    const label = alias ? "`me`" : "Your own uid";
+    if (groupRequested) {
+        return { error: `${label} means My Documents, which is a 1-1 conversation, not a group. Drop -t 1.` };
+    }
+
+    let id = null;
+    try {
+        id = send2meId();
+    } catch (e) {
+        return { error: `${label} means My Documents, which needs a logged-in session to resolve: ${e.message}` };
+    }
+    if (id === undefined || id === null || String(id).trim() === "") {
+        return {
+            error:
+                `${label} means My Documents, but this session did not report its id ` +
+                `(loginInfo.send2me_id is empty), so there is nothing to send to.`,
+        };
+    }
+    id = String(id);
+    return {
+        threadId: id,
+        notice: alias
+            ? `\`me\` = My Documents (${id}).`
+            : `Your own uid is not a conversation Zalo accepts; using My Documents (${id}) instead.`,
+    };
+}
+
+/**
+ * Commander preAction hook body: rewrite a `threadId` argument that names the
+ * self-chat, in place, before the action sees it.
+ *
+ * Works on any command with a positional named `threadId`, and leaves every
+ * other command untouched.
+ *
+ * @param {import("commander").Command} cmd - the command about to run
+ * @param {object} session - see {@link resolveSelfThread}; `groupRequested` is derived here
+ * @returns {null|{notice: string}|{error: string}}
+ */
+export function applySelfThreadAlias(cmd, session) {
+    const names = (cmd?.registeredArguments || []).map((a) => a.name());
+    const idx = names.indexOf("threadId");
+    if (idx < 0) return null;
+    const value = cmd.processedArgs?.[idx];
+    if (typeof value !== "string") return null;
+
+    const groupRequested = Number(cmd.opts?.().type) === 1;
+    const resolved = resolveSelfThread(value, { ...session, groupRequested });
+    if (!resolved || resolved.error) return resolved;
+
+    cmd.processedArgs[idx] = resolved.threadId;
+    if (Array.isArray(cmd.args) && idx < cmd.args.length) cmd.args[idx] = resolved.threadId;
+    return { notice: resolved.notice };
+}

package/src/utils/open-file.js

@@ -0,0 +1,49 @@
+/**
+ * Open a file with the operating system's default application.
+ *
+ * Lives in utils rather than next to a downloader because opening a file has
+ * nothing to do with fetching one, and both the MCP server and the CLI want it.
+ */
+
+import { platform } from "os";
+import { execFile } from "child_process";
+
+/**
+ * Open a local file with the system viewer. Fire-and-forget: a missing viewer
+ * is reported, never thrown, because failing to preview a file must not fail
+ * the command that produced it.
+ *
+ * @param {string} filePath
+ */
+export function openFile(filePath) {
+    const isWin = platform() === "win32";
+
+    // The Windows branch runs through a SHELL, and the path it is handed is
+    // built from a Zalo-supplied filename. cmd.exe treats & ^ % and ` as
+    // syntax, and sanitize() in sync-v2/media.js only strips the characters
+    // Windows forbids in a filename — not the ones cmd.exe acts on. So an
+    // attachment named `holiday&calc.exe.jpg` produced
+    //     start "" C:\…\holiday&calc.exe.jpg
+    // which cmd.exe splits at the &, running the second half as a command.
+    // media.js now strips these too; this is the second line of defence,
+    // because openFile() is also reachable from the MCP zalo_view_media tool
+    // with a path this module did not build.
+    if (isWin && SHELL_METACHARACTERS.test(filePath)) {
+        console.error(`[open-file] Refusing to open a path containing shell metacharacters: ${filePath}`);
+        return;
+    }
+
+    const cmds = { darwin: "open", win32: "start", linux: "xdg-open" };
+    const cmd = cmds[platform()] || "xdg-open";
+    // Windows "start" is a cmd.exe builtin, so it needs a shell; its first
+    // argument is the window title, hence the empty string.
+    execFile(cmd, isWin ? ["", filePath] : [filePath], { shell: isWin }, (err) => {
+        if (err) console.error(`[open-file] Failed to open viewer: ${err.message}`);
+    });
+}
+
+/**
+ * Characters cmd.exe interprets rather than passes through. Exported so the
+ * test can assert the exact set rather than restating it.
+ */
+export const SHELL_METACHARACTERS = /[&^%`!|<>"]/;