@ardennguyen/zalo-agent-cli 2.1.1 → 2.2.0

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`
 
-[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)
 
 ---
@@ -133,7 +134,7 @@ 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
@@ -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`
 
-[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
@@ -261,7 +263,7 @@ 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

package/package.json

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

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/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.