@ardennguyen/zalo-agent-cli 2.1.1 → 2.2.1

package/.env.example

@@ -21,10 +21,15 @@
 # ZALO_OA_DIR=
 
 # ----------------------------------------------------------------------------
-# Runtime & Protocol Options (Optional)
+# Runtime & Account Options (Optional)
 # ----------------------------------------------------------------------------
+# Pin a default registered account ID for this environment without changing
+# the global active entry in accounts.json (equivalent to --account <ID>):
+# ZALO_ACCOUNT=
+
 # Set to any value (e.g. 1) to disable the background npm update check:
 # ZALO_AGENT_NO_UPDATE_CHECK=1
 
 # Protocol version announced to Zalo (default: 691; set 685 to roll back):
 # ZALO_API_VERSION=691
+

package/README.md

@@ -47,12 +47,13 @@ Xây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).
 > **MCP Server (AI Agent Integration)** — Model Context Protocol cho Claude Code và các MCP client:
 > ```bash
 > zalo-agent mcp start                                  # stdio (local Claude Code)
+> zalo-agent mcp start --account <ID>                   # Ghim tài khoản (chạy nhiều tài khoản live cùng lúc)
 > zalo-agent mcp start --http 3847 --auth your-secret   # HTTP (VPS)
 > ```
-> 14 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage` · `zalo_sync` · `zalo_sync_status`
+> 21 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage` · `zalo_sync` · `zalo_sync_status` · `zalo_search_messages` · `zalo_lookup_user` · `zalo_forward_message` · `zalo_delete_message` · `zalo_reminder` · `zalo_note` · `zalo_poll`
 
-[Sync qua MCP và điều kiện phát hành](docs/mcp-sync.vi.md).
-> Auto-reconnect · thread filter · noise reduction · tự tải media · thông báo qua nhóm Zalo
+[Sync qua MCP](docs/mcp-sync.vi.md) · [Ghim đa tài khoản live](docs/account-pinning.vi.md).
+> Auto-reconnect · thread filter · noise reduction · tự tải media · thông báo qua nhóm Zalo · chạy song song nhiều tài khoản (`--account <ID>`)
 > Xem [MCP Guide](skill/references/mcp-guide.md) · [INSTALLATION.md](INSTALLATION.md)
 
 ---
@@ -123,7 +124,7 @@ Tất cả lệnh hỗ trợ `--json`. Tài liệu đầy đủ: **[Wiki](https:
 | `label` | 2 | Nhãn hội thoại | [Nhãn](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%C3%A3n) |
 | `catalog` | 9 | zBusiness — danh mục sản phẩm | [zBusiness](https://github.com/ardennguyen/zalo-agent-cli/wiki/zBusiness) |
 | `listen` | 1 | Lắng nghe real-time, webhook, JSONL, ghi vào cache cục bộ | [Lắng nghe](https://github.com/ardennguyen/zalo-agent-cli/wiki/L%E1%BA%AFng-Nghe) |
-| `mcp` | 1 | MCP server (stdio/HTTP) — 14 tools cho AI agent | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server-(VN)) |
+| `mcp` | 1 | MCP server (stdio/HTTP) — 21 tools cho AI agent | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server-(VN)) |
 | **`oa`** | **32** | **Zalo Official Account API v3.0 — OAuth, tin nhắn, follower, tag, bài viết, cửa hàng, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account-(VN))** |
 
 Xem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-cli/wiki/%C4%90a-T%C3%A0i-Kho%E1%BA%A3n-&-Proxy) · [Cài đặt VPS](https://github.com/ardennguyen/zalo-agent-cli/wiki/C%C3%A0i-%C4%90%E1%BA%B7t-VPS) · [Thẻ chuyển khoản & QR](https://github.com/ardennguyen/zalo-agent-cli/wiki/Th%E1%BA%BB-Chuy%E1%BB%83n-Kho%E1%BA%A3n-&-QR) · [Bộ nhớ đệm & Đồng bộ](https://github.com/ardennguyen/zalo-agent-cli/wiki/B%E1%BB%99-Nh%E1%BB%9B-%C4%90%E1%BB%87m-&-%C4%90%E1%BB%93ng-B%E1%BB%99) · [Bảo mật](https://github.com/ardennguyen/zalo-agent-cli/wiki/B%E1%BA%A3o-M%E1%BA%ADt)
@@ -133,10 +134,10 @@ Xem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-
 ## Tính năng
 
 - Đăng nhập QR qua HTTP server tự động (browser + terminal), báo ngay khi bị **từ chối trên điện thoại** thay vì treo tới hết 60s
-- Đa tài khoản với proxy riêng biệt (1:1), device fingerprint riêng cho từng tài khoản
+- Đa tài khoản với proxy riêng biệt (1:1), device fingerprint riêng cho từng tài khoản; chạy **nhiều tài khoản live đồng thời** (mỗi tài khoản một tiến trình `mcp start` hoặc `listen` kèm `--account <ID>`, và truyền `--account <ID>` / `ZALO_ACCOUNT` trên mọi lệnh CLI mà không ghi đè `accounts.json`)
 - **190 lệnh** phủ hết tính năng Zalo cá nhân
 - **Zalo Official Account (OA) API v3.0** — OAuth login, gửi tin nhắn, follower, tag, bài viết, cửa hàng, webhook listener, multi-OA
-- **MCP server** (stdio + HTTP) — 14 tools cho Claude Code và các MCP client: đọc, gửi (kể cả vào My Documents, đánh dấu Quan trọng/Khẩn cấp), thả cảm xúc, thu hồi tin, xem thành viên nhóm, liệt kê hội thoại gần đây và kiểm tra độ đầy đủ của cache
+- **MCP server** (stdio + HTTP) — 21 tools cho Claude Code và các MCP client: đọc, gửi (văn bản, link preview, danh thiếp, vào My Documents, đánh dấu Quan trọng/Khẩn cấp), tìm kiếm tin nhắn trong cache, tra cứu người dùng, thả cảm xúc, thu hồi, chuyển tiếp, xóa tin, nhắc hẹn, ghi chú/ghim tin, bình chọn, xem thành viên nhóm, liệt kê hội thoại gần đây và kiểm tra độ đầy đủ của cache
 - **Bộ nhớ đệm cục bộ (SQLite)** — `listen` ghi mọi tin nhắn vào `zalo.db`, `msg history` đọc từ cache, `sync` (hoặc `sync-mobile`) khôi phục toàn bộ lịch sử từ điện thoại vào `zalo.db` (giải mã transfer-sync-v2; xác nhận một lần trên điện thoại), mặc định lấy **toàn bộ** lịch sử (không còn mốc chặn 2024-01-01); thêm `--days <n>` hoặc `--from <YYYY-MM-DD>` nếu chỉ cần một khoảng. Dọn dẹp: `sync-media --prune <days|all>` giải phóng dung lượng nhưng giữ nguyên nội dung tin nhắn, `--prune-orphans` nhắm vào hội thoại tài khoản không còn, và `conv forget` xoá hẳn bản sao cục bộ của một hội thoại — không cái nào gửi gì tới Zalo. Luồng đồng bộ chỉ mang **liên kết** media chứ không mang file, nên sau khi lưu tin nhắn, `sync-mobile` **tự động tải media về** (thêm `--messages-only` nếu chỉ muốn tin nhắn); `sync-media` chạy lại/tiếp tục bước tải này, không cần xác nhận trên điện thoại. Ghi chú, tin ghim, bình chọn và nhắc hẹn nằm ngoài luồng tin nhắn — dùng `sync-boards`
 - Tự động tải media (ảnh/audio/video) — một downloader duy nhất cho `listen`, `msg history`, `mcp start` và các lệnh sync, lưu vào `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (hoặc tách riêng credentials, database `zalo.db`, media và OA sang các ổ đĩa/mount khác nhau qua `--credentials-dir`, `--data-dir`, `--media-dir`, `--oa-dir` / biến môi trường `ZALO_*_DIR` trong `~/.zalo-agent-cli/.env`; nếu dùng kèm `zalo-mcp`, chỉ nên giữ cấu hình PORT trong `zalo-mcp/.env` và đặt toàn bộ đường dẫn lưu trữ vào `<CONFIG_DIR>/.env`)
 - Thẻ chuyển khoản (55+ ngân hàng VN) & QR VietQR
@@ -211,12 +212,13 @@ CLI tool for Zalo automation — multi-account, proxy support, bank transfers, Q
 > **MCP Server (AI Agent Integration)** — Model Context Protocol support for Claude Code and MCP clients:
 > ```bash
 > zalo-agent mcp start                                  # stdio (local Claude Code)
+> zalo-agent mcp start --account <ID>                   # Pin account (run multiple live accounts at once)
 > zalo-agent mcp start --http 3847 --auth your-secret   # HTTP (VPS)
 > ```
-> 14 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage` · `zalo_sync` · `zalo_sync_status`
+> 21 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage` · `zalo_sync` · `zalo_sync_status` · `zalo_search_messages` · `zalo_lookup_user` · `zalo_forward_message` · `zalo_delete_message` · `zalo_reminder` · `zalo_note` · `zalo_poll`
 
-[MCP sync and release prerequisites](docs/mcp-sync.md).
-> Auto-reconnect · thread filter · noise reduction · media auto-download · Zalo-group notifications
+[MCP sync](docs/mcp-sync.md) · [Multi-account pinning](docs/account-pinning.md).
+> Auto-reconnect · thread filter · noise reduction · media auto-download · Zalo-group notifications · concurrent multi-account (`--account <ID>`)
 > See [MCP Guide](skill/references/mcp-guide.md) · [INSTALLATION.md](INSTALLATION.md)
 
 ### Quick Start
@@ -253,7 +255,7 @@ Full docs: **[Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki)** · [Fu
 | `label` | 2 | Conversation labels | [Labels](https://github.com/ardennguyen/zalo-agent-cli/wiki/Labels) |
 | `catalog` | 9 | zBusiness catalogs & products | [Catalog](https://github.com/ardennguyen/zalo-agent-cli/wiki/Catalog) |
 | `listen` | 1 | Real-time listener, webhook, JSONL, local cache writes | [Listener](https://github.com/ardennguyen/zalo-agent-cli/wiki/Listener) |
-| `mcp` | 1 | MCP server (stdio/HTTP) — 14 tools for AI agents | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server) |
+| `mcp` | 1 | MCP server (stdio/HTTP) — 21 tools for AI agents | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server) |
 | **`oa`** | **32** | **Zalo Official Account API v3.0 — OAuth, messaging, followers, tags, articles, store, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account)** |
 
 See also: [Multi-Account & Proxy](https://github.com/ardennguyen/zalo-agent-cli/wiki/Multi-Account-&-Proxy) · [VPS Setup](https://github.com/ardennguyen/zalo-agent-cli/wiki/VPS-Setup) · [Bank Card & QR Payments](https://github.com/ardennguyen/zalo-agent-cli/wiki/Bank-Card-&-QR-Payments) · [Local Cache & Sync](https://github.com/ardennguyen/zalo-agent-cli/wiki/Local-Cache-&-Sync) · [Security](https://github.com/ardennguyen/zalo-agent-cli/wiki/Security)
@@ -261,10 +263,10 @@ See also: [Multi-Account & Proxy](https://github.com/ardennguyen/zalo-agent-cli/
 ### Features
 
 - QR login over an auto-started HTTP server (browser + terminal), reporting a **decline on the phone** immediately instead of hanging until the 60s timeout
-- Multi-account with a dedicated proxy (1:1) and a per-account device fingerprint
+- Multi-account with a dedicated proxy (1:1) and a per-account device fingerprint; run **multiple live accounts simultaneously** (one `mcp start` or `listen` process per account with `--account <ID>`, plus `--account <ID>` / `ZALO_ACCOUNT` on any CLI command without mutating `accounts.json`)
 - **190 commands** covering the personal-account Zalo surface
 - **Zalo Official Account (OA) API v3.0** — OAuth login, messaging, followers, tags, articles, store, webhook listener, multi-OA
-- **MCP server** (stdio + HTTP) — 14 tools for Claude Code and other MCP clients: read, send (to My Documents too, marked Important/Urgent), react, recall, list a group's members, list recent conversations, and check how complete the cache is
+- **MCP server** (stdio + HTTP) — 21 tools for Claude Code and other MCP clients: read, send (text, link previews, contact cards, to My Documents too, marked Important/Urgent), search cached messages, look up users, react, recall, forward, delete, reminders, group notes/pins, group polls, list a group's members, list recent conversations, and check how complete the cache is
 - **Local SQLite cache** — `listen` writes every message to `zalo.db`, `msg history` reads from it, and `sync` (or `sync-mobile`) restores full history from the phone into `zalo.db` (transfer-sync-v2 decrypt; one confirmation on the phone), defaulting to **all** history (the old 2024-01-01 floor is gone), with `--days <n>` or `--from <YYYY-MM-DD>` to narrow it. Housekeeping: `sync-media --prune <days|all>` reclaims disk while keeping message text, `--prune-orphans` targets conversations the account no longer has, and `conv forget` removes a conversation's local copy entirely — none of which contact Zalo. The sync stream carries media **links**, not files, so a `sync-mobile` run **downloads its attachments automatically** once the messages are stored (`--messages-only` skips it); `sync-media` re-runs or resumes that fetch on its own, with no phone confirmation. Notes, pinned messages, polls and reminders live outside the message stream — `sync-boards` fetches those
 - Automatic media download — one downloader shared by `listen`, `msg history`, `mcp start` and the sync commands, saving to `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (or separate credentials, `zalo.db`, media, and OA credentials onto independent volumes/mounts via `--credentials-dir`, `--data-dir`, `--media-dir`, `--oa-dir` / `ZALO_*_DIR` in `~/.zalo-agent-cli/.env`; when using `zalo-mcp`, keep `zalo-mcp/.env` for PORT settings only and place all storage/engine settings in `<CONFIG_DIR>/.env`)
 - Bank cards (55+ VN banks) and VietQR payment images

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ardennguyen/zalo-agent-cli",
-    "version": "2.1.1",
+    "version": "2.2.1",
     "description": "CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0",
     "type": "module",
     "bin": {
@@ -77,6 +77,6 @@
     },
     "allowScripts": {
         "better-sqlite3@13.0.3": true,
-        "@ardennguyen/zalo-agent-cli@2.1.1": true
+        "@ardennguyen/zalo-agent-cli@2.2.1": true
     }
 }

package/src/commands/listen.js

@@ -84,7 +84,9 @@ export function registerListenCommand(program) {
         .action(async (opts) => {
             let activeAcc;
             try {
-                activeAcc = selectDaemonAccount(opts.account);
+                const requestedAccount =
+                    opts.account ?? program.opts().account ?? (process.env.ZALO_ACCOUNT?.trim() || undefined);
+                activeAcc = selectDaemonAccount(requestedAccount);
             } catch (e) {
                 error(e.message);
                 process.exit(1);

package/src/commands/mcp.js

@@ -143,7 +143,9 @@ export function registerMCPCommands(program) {
             // Select once; acquire the selected account's lock before authentication.
             let activeAcc;
             try {
-                activeAcc = selectDaemonAccount(opts.account);
+                const requestedAccount =
+                    opts.account ?? program.opts().account ?? (process.env.ZALO_ACCOUNT?.trim() || undefined);
+                activeAcc = selectDaemonAccount(requestedAccount);
             } catch (e) {
                 console.error("[mcp] Account selection failed:", e.message);
                 process.exit(1);

package/src/core/accounts.js

@@ -33,14 +33,37 @@ function save(accounts) {
     chmodSync(file, 0o600);
 }
 
+let _pinnedAccountId = null;
+
+/**
+ * Pin this process's target account ID without modifying accounts.json on disk.
+ * Used when `--account <id>` or `ZALO_ACCOUNT` is passed to a CLI command.
+ * @param {string|null|undefined} ownId
+ */
+export function setPinnedAccount(ownId) {
+    _pinnedAccountId = ownId ? String(ownId) : null;
+}
+
+/**
+ * Return the process-pinned account ID if set, or null.
+ * @returns {string|null}
+ */
+export function getPinnedAccountId() {
+    return _pinnedAccountId;
+}
+
 /** List all registered accounts. */
 export function listAccounts() {
     return load();
 }
 
-/** Get currently active account or null. */
+/** Get currently active (or process-pinned) account or null. */
 export function getActive() {
-    return load().find((a) => a.active) || null;
+    const accounts = load();
+    if (_pinnedAccountId !== null) {
+        return accounts.find((a) => a.ownId === _pinnedAccountId) || null;
+    }
+    return accounts.find((a) => a.active) || null;
 }
 
 /** Set an account as active (deactivates others). Returns false if not found. */

package/src/core/db.js

@@ -621,6 +621,50 @@ export function getMessageById(msgId) {
     return db.prepare("SELECT * FROM messages WHERE msgId = ?").get(String(msgId)) || null;
 }
 
+/**
+ * Search cached messages by text substring across one or all conversations, newest first.
+ *
+ * Purely local SQLite query — never touches the Zalo network. Excludes recalled/deleted
+ * tombstones (`type = 'deleted'`) and escapes SQLite LIKE wildcards (`%`, `_`, `\`) so literal
+ * characters in `query` match as literals.
+ *
+ * @param {object} opts
+ * @param {string} opts.query - Substring to match in message text (case-insensitive for ASCII)
+ * @param {string} [opts.threadId] - Restrict to one conversation
+ * @param {string} [opts.senderId] - Restrict to one sender UID
+ * @param {number} [opts.since] - Only messages at or after this epoch-ms timestamp
+ * @param {number} [opts.until] - Only messages at or before this epoch-ms timestamp
+ * @param {number} [opts.limit=50] - Max messages to return
+ * @returns {Array<object>}
+ */
+export function searchMessages(opts = {}) {
+    if (!db) throw new Error("Database not initialized");
+    const { query, threadId, senderId, since, until, limit = 50 } = opts;
+    const escaped = String(query ?? "").replace(/[\\%_]/g, "\\$&");
+    const where = ["COALESCE(type, '') != 'deleted'", "text IS NOT NULL", "text LIKE ? ESCAPE '\\'"];
+    const params = [`%${escaped}%`];
+    if (threadId) {
+        where.push("threadId = ?");
+        params.push(String(threadId));
+    }
+    if (senderId) {
+        where.push("senderId = ?");
+        params.push(String(senderId));
+    }
+    if (Number.isFinite(since)) {
+        where.push("timestamp >= ?");
+        params.push(Number(since));
+    }
+    if (Number.isFinite(until)) {
+        where.push("timestamp <= ?");
+        params.push(Number(until));
+    }
+    params.push(limit);
+    return db
+        .prepare(`SELECT * FROM messages WHERE ${where.join(" AND ")} ORDER BY timestamp DESC LIMIT ?`)
+        .all(...params);
+}
+
 /**
  * Most recently active threads, newest first.
  *

package/src/index.js

@@ -30,7 +30,8 @@ import { registerOACommands } from "./commands/oa.js";
 import { registerMCPCommands } from "./commands/mcp.js";
 import { registerSyncCommands } from "./commands/sync.js";
 import { autoLogin } from "./core/zalo-client.js";
-import { getActive } from "./core/accounts.js";
+import { getActive, setPinnedAccount } from "./core/accounts.js";
+import { parseAccountId, selectDaemonAccount } from "./core/daemon-account.js";
 import { configureStoragePaths } from "./core/credentials.js";
 import { logoutNeedsSession } from "./core/logout.js";
 import { checkForUpdates, selfUpdate } from "./utils/update-check.js";
@@ -47,6 +48,11 @@ program
     .description("CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments")
     .version(pkg.version)
     .option("--json", "Output results as JSON (machine-readable)")
+    .option(
+        "--account <id>",
+        "Pin this command to an exact registered account ID without changing the active account (env: ZALO_ACCOUNT)",
+        parseAccountId,
+    )
     .option("--env-file <path>", "Load environment variables from a .env file (env: ZALO_ENV_FILE)")
     .option("--config-dir <dir>", "Config directory (default: ~/.zalo-agent-cli, env: ZALO_CONFIG_DIR)")
     .option(
@@ -79,6 +85,23 @@ program
             warning(DISCLAIMER);
             console.log();
         }
+        // Pin the target account for this invocation when --account or ZALO_ACCOUNT is set,
+        // without changing the global active entry in accounts.json. Daemons (`listen`, `mcp`)
+        // perform their own selection and lock acquisition inside their command actions.
+        const envAccount = process.env.ZALO_ACCOUNT?.trim() || undefined;
+        const requestedAccount = actionCommand.opts()?.account ?? globalOpts.account ?? envAccount;
+        if (
+            requestedAccount !== undefined &&
+            !["mcp", "listen", "oa", "update", "help", "version", "login"].includes(cmdName)
+        ) {
+            try {
+                const pinned = selectDaemonAccount(requestedAccount);
+                setPinnedAccount(pinned.ownId);
+            } catch (e) {
+                error(e.message);
+                process.exit(1);
+            }
+        }
         // Auto-login before any command that needs it (skip for login/account/oa
         // commands, and for a logout that will not call Zalo at all).
         // Daemons authenticate their pinned identity after acquiring its lock.