@ardennguyen/zalo-agent-cli 1.0.7 → 2.1.0

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 = /[&^%`!|<>"]/;

package/src/utils/output.js

@@ -1,9 +1,37 @@
 /**
  * Output formatting utilities — JSON mode and colored human-readable output.
+ *
+ * ## The stdout contract
+ *
+ * In `--json` mode (and in MCP mode), **stdout carries nothing but one JSON
+ * value.** Human-facing chatter — the disclaimer, auto-login notices,
+ * progress lines, success confirmations — goes to stderr, and failures are
+ * emitted as JSON too, so `zalo-agent --json … | jq` works whether the
+ * command succeeded or not.
+ *
+ * This used to be false in two ways, both of which broke piping:
+ *
+ *   · `error()` printed `  ✗ <msg>` to stdout regardless of mode, so a
+ *     failure produced output that was not JSON at all.
+ *   · Commands that call `success()` after `output()` — `msg send --react`
+ *     is the one that bit us — appended a human line *after* the JSON.
+ *
+ * MCP mode gets the same treatment for a different reason: there, stdout is
+ * the JSON-RPC transport, so anything else on it corrupts the protocol.
+ * `src/commands/mcp.js` also reassigns console.log to console.error as a
+ * second layer of defense.
  */
 
 import chalk from "chalk";
 
+/**
+ * True when stdout is reserved for machine-readable output.
+ * Set by the preAction hook in src/index.js for `--json` and for `mcp`.
+ */
+function machineMode() {
+    return Boolean(process.env.ZALO_JSON_MODE);
+}
+
 /** Emit JSON or call human formatter based on --json flag. */
 export function output(data, jsonMode, humanFormatter) {
     if (jsonMode) {
@@ -15,7 +43,50 @@ export function output(data, jsonMode, humanFormatter) {
     }
 }
 
-export const success = (msg) => console.log(chalk.green("  ✓ " + msg));
-export const error = (msg) => console.log(chalk.red("  ✗ " + msg));
-export const info = (msg) => console.log(chalk.cyan("  ● " + msg));
-export const warning = (msg) => console.log(chalk.yellow("  ⚠ " + msg));
+/**
+ * Report a failure.
+ *
+ * Human mode: `  ✗ <msg>` on stdout, as before.
+ * Machine mode: `{"error": "<msg>"}` on stdout — a caller can test `.error`
+ * with jq instead of pattern-matching a ✗ out of mixed output.
+ *
+ * Only the FIRST error is emitted as JSON. A command that reports several
+ * failures would otherwise put several JSON values on stdout, which is just
+ * as unparseable as the old ✗ line; subsequent ones go to stderr.
+ */
+let jsonErrorEmitted = false;
+export const error = (msg) => {
+    if (!machineMode()) {
+        console.log(chalk.red("  ✗ " + msg));
+        return;
+    }
+    if (jsonErrorEmitted) {
+        console.error("  ✗ " + msg);
+        return;
+    }
+    jsonErrorEmitted = true;
+    console.log(JSON.stringify({ error: String(msg) }, null, 2));
+};
+
+/** Confirm success. Suppressed from stdout in machine mode. */
+export const success = (msg) => {
+    if (machineMode()) console.error("  ✓ " + msg);
+    else console.log(chalk.green("  ✓ " + msg));
+};
+
+/** Progress / context line. Suppressed from stdout in machine mode. */
+export const info = (msg) => {
+    if (machineMode()) console.error("  ● " + msg);
+    else console.log(chalk.cyan("  ● " + msg));
+};
+
+/** Caveat or risk line. Suppressed from stdout in machine mode. */
+export const warning = (msg) => {
+    if (machineMode()) console.error("  ⚠ " + msg);
+    else console.log(chalk.yellow("  ⚠ " + msg));
+};
+
+/** Test seam: reset the once-only JSON error latch. */
+export function _resetErrorLatch() {
+    jsonErrorEmitted = false;
+}

package/src/utils/parse-options.js

@@ -0,0 +1,56 @@
+/**
+ * Safe coercions for Commander option values.
+ *
+ * ## Why this exists
+ *
+ * `.option("-c, --count <n>", "Page size", parseInt, 100)` looks obviously
+ * correct and is silently wrong. Commander invokes a coercion as
+ * `fn(value, previousValue)`, and `previousValue` is the option's **default**.
+ * JavaScript's `parseInt(string, radix)` takes a *radix* second — so the
+ * default becomes the radix:
+ *
+ * ```
+ * friend alias-list -c 100   ->  parseInt("100", 100)  ->  NaN
+ * profile avatars   -c 50    ->  parseInt("50",  50)   ->  NaN
+ * catalog list      -l 20    ->  parseInt("20",  20)   ->  40   ← silently wrong
+ * ```
+ *
+ * The NaN cases reach Zalo as `NaN` and come back as
+ * "Tham số không hợp lệ" — which looks exactly like a server-side rejection
+ * and was in fact misfiled as an upstream defect for a while. The radix-40
+ * case is worse: no error at all, just the wrong page size.
+ *
+ * `parseIntOption` ignores the second argument entirely and always parses
+ * base 10, rejecting anything that is not a clean integer rather than
+ * silently substituting a default.
+ */
+
+/**
+ * Parse a Commander option value as a base-10 integer.
+ *
+ * @param {string} value - raw value from the command line
+ * @returns {number}
+ * @throws {Error} when the value is not a base-10 integer
+ */
+export function parseIntOption(value) {
+    const n = Number.parseInt(String(value).trim(), 10);
+    if (!Number.isFinite(n) || String(n) !== String(value).trim()) {
+        throw new Error(`Expected a whole number, got "${value}"`);
+    }
+    return n;
+}
+
+/**
+ * Same, but rejects values below `min` — for counts, pages and durations
+ * where a negative or zero would silently produce nonsense downstream.
+ *
+ * @param {number} min
+ * @returns {(value: string) => number}
+ */
+export function parseIntAtLeast(min) {
+    return (value) => {
+        const n = parseIntOption(value);
+        if (n < min) throw new Error(`Expected a whole number >= ${min}, got ${n}`);
+        return n;
+    };
+}

package/src/utils/qr-http-server.js

@@ -5,7 +5,7 @@
  */
 
 import http from "http";
-import { readFileSync, existsSync } from "fs";
+import { readFileSync, existsSync, statSync } from "fs";
 import nodefetch from "node-fetch";
 import { info } from "./output.js";
 
@@ -13,9 +13,36 @@ import { info } from "./output.js";
  * Start a temporary HTTP server that serves the QR image.
  * @param {string} qrImagePath - path to QR PNG file
  * @param {number} port - default 18927
+ * @param {number[]} tryPorts - ports to try in order
+ * @param {boolean} exposeOnLan - bind 0.0.0.0 instead of 127.0.0.1
+ *
+ *   The QR is a **login token**: anyone who can fetch and scan it before it
+ *   expires signs in as this account. Binding 0.0.0.0 therefore offers the
+ *   account to the whole network, so it is opt-in (`--qr-url`) rather than
+ *   the default. Loopback still covers the ordinary desktop case, where the
+ *   browser is on the same machine.
+ *
  * @returns {{ url: string, close: () => void }}
  */
-export function startQrServer(qrImagePath, port = 18927, tryPorts = [18927, 8080, 3000, 9000]) {
+/**
+ * Which QR image is current: its modification time, or null before the first.
+ * The login loop regenerates the QR roughly every 100 s; the page polls this
+ * so it never shows an expired code (measured 2026-09-30: a page opened on
+ * the first QR kept showing it after two regenerations, and a scan failed).
+ *
+ * @param {string} qrImagePath
+ * @returns {number|null}
+ */
+export function qrVersion(qrImagePath) {
+    try {
+        return statSync(qrImagePath).mtimeMs;
+    } catch {
+        return null;
+    }
+}
+
+export function startQrServer(qrImagePath, port = 18927, tryPorts = [18927, 8080, 3000, 9000], exposeOnLan = false) {
+    const bindHost = exposeOnLan ? "0.0.0.0" : "127.0.0.1";
     const server = http.createServer(async (req, res) => {
         if (req.url === "/qr" || req.url === "/") {
             if (!existsSync(qrImagePath)) {
@@ -74,7 +101,7 @@ h1{color:#e2e8f0;font-size:1.1rem;font-weight:600;margin:0.5rem 0}
 ${mascotImg}
 <h1>Zalo Agent CLI</h1>
 <p class="brand">QR Code Login</p>
-<img src="data:image/png;base64,${b64}" class="qr-img" alt="QR Code"/>
+<img src="data:image/png;base64,${b64}" class="qr-img" id="qr-img" alt="QR Code"/>
 <p class="hint">Open <strong>Zalo app</strong> > <strong>QR Scanner</strong> to scan</p>
 <p class="footer">Powered by <a href="https://github.com/ardennguyen/zalo-agent-cli">zalo-agent-cli</a></p>
 </div>
@@ -86,7 +113,8 @@ ${mascotImg}
 </div>
 </div>
 <script>
-// Poll /status to detect login success
+// Poll /status to detect login success, and swap in each regenerated QR
+let qrV=${JSON.stringify(qrVersion(qrImagePath))};
 setInterval(async()=>{
   try{
     const r=await fetch('/status');
@@ -94,6 +122,9 @@ setInterval(async()=>{
     if(d.loggedIn){
       document.getElementById('qr-view').classList.add('hidden');
       document.getElementById('success-view').classList.remove('hidden');
+    }else if(d.qrVersion&&d.qrVersion!==qrV){
+      qrV=d.qrVersion;
+      document.getElementById('qr-img').src='/qr.png?v='+qrV;
     }
   }catch{}
 },2000);
@@ -121,7 +152,7 @@ setInterval(async()=>{
                 loggedIn = isLoggedIn();
             } catch {}
             res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ loggedIn }));
+            res.end(JSON.stringify({ loggedIn, qrVersion: qrVersion(qrImagePath) }));
         } else {
             res.writeHead(404);
             res.end("Not found");
@@ -133,7 +164,13 @@ setInterval(async()=>{
 
     function tryListen() {
         const p = tryPorts[currentPortIdx];
-        server.listen(p, "0.0.0.0");
+        server.listen(p, bindHost);
+        // Never let the QR server be the reason the process stays alive. It
+        // is a convenience view onto a file, not work in its own right — and
+        // an orphaned one holds its port long after login finished, so the
+        // NEXT login silently falls through to 8080. (Observed: a login's
+        // server still serving HTTP 200 on 18927 hours later.)
+        server.unref();
     }
 
     server.on("listening", async () => {
@@ -163,7 +200,7 @@ setInterval(async()=>{
             if (publicIp) info(`On VPS, open: http://${publicIp}:${actualPort}/qr`);
             else info(`On VPS, open: http://<your-server-ip>:${actualPort}/qr`);
             info(`If firewall blocks, run: sudo ufw allow ${actualPort}/tcp`);
-            info(`Or copy QR file: scp user@vps:~/.zalo-agent/qr.png ./qr.png`);
+            info(`Or copy QR file: scp user@vps:~/.zalo-agent-cli/qr.png ./qr.png`);
         }
     });
 

package/src/utils/quote.js

@@ -0,0 +1,203 @@
+/**
+ * Rebuild the quote payload `sendMessage({ msg, quote })` needs from a cached
+ * message row.
+ *
+ * Quoting is the one send that cannot be driven from a msgId alone. zca-js
+ * puts five fields on the wire — `qmsgOwner`, `qmsgId`, `qmsgCliId`,
+ * `qmsgTs`, `qmsg` (and `qmsgAttach` for groups) — and two of them,
+ * `cliMsgId` and the `property` blob, appear in no CLI output at all. They
+ * live only in `messages.raw_data` in the local SQLite cache, which is why
+ * `--quote` is a cache lookup rather than a pure argument transform.
+ *
+ * Only **text** messages can be quoted natively. zca-js raises
+ * `This kind of 'webchat' quote type is not available` when a `webchat`
+ * quote's content is not a string, and the sync path stores a *placeholder*
+ * string ("[Hình ảnh]", "[Sticker]", "[File] …") for attachments — which
+ * would slip past that check and send a quote whose visible text is the
+ * placeholder. So the guard here is the row's classified `type`, not the
+ * shape of its content.
+ */
+
+/**
+ * `raw_data` as an object, whatever shape the writer used.
+ *
+ * The live path stores the message payload directly; some rows nest it under
+ * `data`. An older writer stored the bare content string, so a parse that
+ * yields a non-object is treated as "no metadata" rather than throwing.
+ *
+ * @param {string|null|undefined} rawData
+ * @returns {object}
+ */
+function parseRaw(rawData) {
+    try {
+        const parsed = JSON.parse(rawData || "{}");
+        if (!parsed || typeof parsed !== "object") return {};
+        return parsed.data && typeof parsed.data === "object" ? parsed.data : parsed;
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Turn a cached `messages` row into the `quote` object zca-js expects.
+ *
+ * Returns `{ error }` rather than throwing so the caller can report a
+ * reason the user can act on — "nothing has cached this message yet" is a
+ * very different problem from "stickers can't be quoted".
+ *
+ * @param {object|null} row - a row from the `messages` table, or null when the
+ *   msgId is not cached
+ * @param {object} [opts]
+ * @param {string} [opts.msgId] - the requested id, used in messages when `row` is null
+ * @param {string} [opts.threadId] - when given, the quote must belong to this thread
+ * @returns {{quote: object}|{error: string}}
+ */
+export function buildQuote(row, { msgId = row?.msgId, threadId = null } = {}) {
+    const id = msgId === undefined || msgId === null ? "(unknown)" : String(msgId);
+
+    if (!row) {
+        return {
+            error:
+                `Message ${id} is not in the local cache, so its quote cannot be rebuilt. ` +
+                `A running \`listen\`/\`mcp\` daemon is what caches messages as they arrive; ` +
+                `\`msg history <threadId> -t <0|1>\` backfills older ones. Neither can seed a ` +
+                `message just sent from this CLI — \`msg send\` does not write to the cache.`,
+        };
+    }
+
+    // msgIds are account-wide, so a mistyped or pasted-from-elsewhere id finds
+    // a real row in the wrong conversation. Zalo would render that quote
+    // against a message the recipients cannot see.
+    if (threadId && row.threadId && String(row.threadId) !== String(threadId)) {
+        return {
+            error: `Cannot quote message ${id}: it belongs to thread ${row.threadId}, not ${threadId}.`,
+        };
+    }
+
+    const data = parseRaw(row.raw_data);
+
+    // The classifier's own vocabulary ("text", "photo", "sticker", "file", …).
+    // Rows old enough to predate it fall back to the content shape.
+    const kind = row.type || (typeof data.content === "string" ? "text" : null);
+    if (kind !== "text") {
+        return {
+            error:
+                `Cannot quote message ${id}: Zalo only supports quote-replies to text messages ` +
+                `(this one is ${kind ? `a ${kind}` : "not text"}). Send a plain reply instead.`,
+        };
+    }
+
+    const content = typeof data.content === "string" ? data.content : row.text;
+    if (typeof content !== "string" || content.length === 0) {
+        return { error: `Cannot quote message ${id}: no text was cached for it.` };
+    }
+
+    // Client-generated and only ever known to the sender — nothing can derive it.
+    const cliMsgId = data.cliMsgId;
+    if (cliMsgId === undefined || cliMsgId === null || cliMsgId === "") {
+        return {
+            error:
+                `Cannot quote message ${id}: its cliMsgId was never cached. ` +
+                `Re-fetch the thread with \`msg history <threadId> -t <0|1>\`.`,
+        };
+    }
+
+    const uidFrom = row.senderId ?? data.uidFrom;
+    if (!uidFrom) return { error: `Cannot quote message ${id}: its sender is unknown.` };
+
+    const ts = row.timestamp ?? data.ts;
+    if (!ts) return { error: `Cannot quote message ${id}: its timestamp is unknown.` };
+
+    // transfer-sync-v2 restores rows with a NOISED sender id
+    // ("VNOISED0000000000000000000000081") rather than the numeric uid the live
+    // listener records. This is not a cosmetic attribution problem: Zalo puts
+    // it on the wire as `qmsgOwner` and REJECTS the send with code 114.
+    // Measured 2026-09-28 — the same quote with a real numeric uid substituted
+    // in went through immediately.
+    //
+    // It is recoverable, so the caller should resolve rather than refuse: these
+    // ids decode through the same /api/gid/decrypt the sync path already uses
+    // for conversation ids (3/3 resolved, with display names). `buildQuote`
+    // stays synchronous and pure, so it reports the need and
+    // `resolveQuoteSender` below does the call.
+    const opaqueSender = !/^-?\d+$/.test(String(uidFrom));
+
+    return {
+        opaqueSender,
+        ...(opaqueSender && {
+            warning:
+                `Message ${id} was restored by sync and carries a noised sender id, which Zalo rejects ` +
+                `(code 114). Resolving it; if that fails, run \`msg history <threadId> -t <0|1>\` to ` +
+                `re-fetch the message with a real uid.`,
+        }),
+        quote: {
+            content,
+            // Normalized rather than echoed: the live path records "webchat"
+            // and the sync path records the numeric 0 for the same text
+            // message. zca-js maps both to client type 1, so say it once.
+            msgType: "webchat",
+            // Group quotes go out as `qmsgAttach: JSON.stringify(propertyExt)`.
+            // undefined is tolerated (removeUndefinedKeys drops it) but the
+            // quoted block renders with the sender's attribution when it's there.
+            propertyExt: data.property ?? undefined,
+            uidFrom: String(uidFrom),
+            msgId: String(row.msgId ?? id),
+            cliMsgId: String(cliMsgId),
+            ts: String(ts),
+            ttl: 0,
+        },
+    };
+}
+
+/**
+ * Turn a quote's noised `uidFrom` into the real numeric uid.
+ *
+ * Only needed when `buildQuote` reported `opaqueSender`. A sync-restored row's
+ * sender is a noised id and Zalo rejects it as `qmsgOwner` with code 114, so
+ * without this a restored message simply cannot be quoted — which is half the
+ * point of restoring it.
+ *
+ * The decode is the same `/api/gid/decrypt` (cmd 12054) the sync path already
+ * uses for conversation ids; `resolveNonFriendDms` accepts message sender ids
+ * unchanged. Imported lazily so the pure module keeps no network dependency and
+ * stays cheap to test.
+ *
+ * Mutates and returns `quote` on success. On failure it leaves `quote`
+ * untouched and returns an `error` describing what to do instead, rather than
+ * sending something the server will reject.
+ *
+ * @param {object} quote - the `quote` from buildQuote()
+ * @param {object} api - a logged-in zca-js api
+ * @returns {Promise<{quote?: object, error?: string, resolved?: string}>}
+ */
+export async function resolveQuoteSender(quote, api) {
+    const noised = String(quote?.uidFrom ?? "");
+    if (!noised) return { error: "Cannot resolve a quote with no sender." };
+    if (/^-?\d+$/.test(noised)) return { quote }; // already real; nothing to do
+
+    let resolveNonFriendDms;
+    try {
+        ({ resolveNonFriendDms } = await import("../core/sync-v2/gid.js"));
+    } catch (e) {
+        return { error: `Cannot resolve the quoted message's sender (${e.message}).` };
+    }
+
+    let hit;
+    try {
+        const map = await resolveNonFriendDms(api, [noised]);
+        hit = map.get(noised);
+    } catch (e) {
+        return { error: `Resolving the quoted message's sender failed (${e.message}).` };
+    }
+
+    if (!hit?.id) {
+        return {
+            error:
+                `Could not resolve the quoted message's sender. Zalo rejects a noised id with code 114, ` +
+                `so run \`msg history <threadId> -t <0|1>\` to re-fetch that message with a real uid.`,
+        };
+    }
+
+    quote.uidFrom = String(hit.id);
+    return { quote, resolved: hit.name || String(hit.id) };
+}

package/src/utils/thread-type.js

@@ -0,0 +1,72 @@
+/**
+ * Fill in `--type` from the local cache when the caller did not say.
+ *
+ * Twenty-two commands take `-t, --type <n>` (0=User, 1=Group) and every one of
+ * them defaults it to 0, because a thread id alone does not say which it is.
+ * That default is wrong for every group, and wrong in a way that is easy to
+ * miss: Zalo routes the send by thread id regardless, so the message arrives
+ * and the command reports success. What the declared type actually decides is
+ * which socket channel the server echoes the sender's own copy back on — cmd
+ * 501 (1-1) or cmd 521 (group) — and the listener types the conversation from
+ * that channel. A group send left at the default therefore came back looking
+ * like a DM and rewrote the conversation's stored type. Two threads in a real
+ * cache were found already mislabelled this way.
+ *
+ * The cache knows the answer, so nobody should have to remember `-t 1`. This
+ * runs as one preAction hook rather than in twenty-two action handlers, and
+ * only ever fires when the option is still at its default — passing `-t 0`
+ * explicitly still means 0.
+ *
+ * `upsertThread` refuses to downgrade a group regardless, so this is the
+ * ergonomic half of the fix, not the safety half.
+ */
+import { join } from "node:path";
+import { getActive } from "../core/accounts.js";
+import { CONFIG_DIR } from "../core/credentials.js";
+import { initDb, getThreadType } from "../core/db.js";
+
+/**
+ * The cached kind of one conversation, opening the active account's db first.
+ *
+ * @param {string} threadId
+ * @returns {"dm"|"group"|null}
+ */
+function lookupCachedType(threadId) {
+    const acc = getActive();
+    if (!acc) return null;
+    initDb(join(CONFIG_DIR, "accounts", acc.ownId, "zalo.db"));
+    return getThreadType(threadId);
+}
+
+/**
+ * Rewrite `cmd`'s `--type` to 1 when its threadId argument names a known group.
+ *
+ * Silent and best-effort by design: this sits in front of every command, so a
+ * missing account, an absent cache or an unknown thread must leave the command
+ * exactly as it was rather than fail it.
+ *
+ * @param {import("commander").Command} cmd - the command about to run
+ * @param {(threadId: string) => ("dm"|"group"|null)} [lookup] - seam for tests
+ * @returns {void}
+ */
+export function applyCachedThreadType(cmd, lookup = lookupCachedType) {
+    try {
+        if (typeof cmd?.getOptionValueSource !== "function") return;
+        // "default" means commander supplied it, not the user. Anything else --
+        // cli, env, config -- is a deliberate choice and is left alone.
+        if (cmd.getOptionValueSource("type") !== "default") return;
+
+        // Which positional holds the thread id differs per command: `msg send
+        // <threadId> <message>` has it first, `msg react <msgId> <threadId>
+        // <reaction>` second. Ask commander instead of assuming.
+        const args = cmd.registeredArguments || [];
+        const idx = args.findIndex((a) => a.name() === "threadId");
+        if (idx < 0) return;
+        const threadId = cmd.args?.[idx];
+        if (!threadId) return;
+
+        if (lookup(threadId) === "group") cmd.setOptionValue("type", "1");
+    } catch {
+        /* no cache, no account, or a command shaped differently -- keep the default */
+    }
+}