@ardennguyen/zalo-agent-cli 2.5.6 → 2.5.8

package/package.json

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

package/src/commands/mcp.js

@@ -99,6 +99,9 @@ export function normalizeMessage(msg, info = null) {
     const cls = info || classifyLiveMessage(data);
     const media = cls.attachments.find((a) => a.url || a.thumbUrl) || null;
     return {
+        // `msgId` is the name every tool takes and every other reply uses; `id` is the same value, kept for clients
+        // that already read it (the webhook and /events/wait payloads carry both).
+        msgId: data.msgId,
         id: data.msgId,
         threadId: msg.threadId,
         threadType: msg.type === 0 ? "dm" : "group",

package/src/commands/msg.js

@@ -35,6 +35,7 @@ import { applySelfThreadAlias } from "../utils/my-documents.js";
 import { buildQuote, resolveQuoteSender } from "../utils/quote.js";
 import { urgencyLevel } from "../utils/urgency.js";
 import { markdownToZalo, resolveSendFormat } from "../utils/markdown.js";
+import { splitMessage, sendParts } from "../utils/split-message.js";
 
 /**
  * Open the active account's SQLite cache.
@@ -678,19 +679,38 @@ export function registerMsgCommands(program) {
                 // Build message content. `urgency` is 1 (important) or 2
                 // (urgent); zca-js turns it into the `metaData: {urgency}`
                 // object Zalo Web sends, on every text endpoint.
+                //
+                // Zalo refuses one oversized message (114 plain, 112 styled), so
+                // a long text goes out as Web sends it: split at 3000 bytes of
+                // text plus styles, in order, 300 ms apart. The quote and the
+                // urgency belong to the first part only.
                 const urgency = opts.urgency;
-                const hasExtras = mentions.length > 0 || styles.length > 0 || Boolean(quote) || Boolean(urgency);
-                const msgContent = hasExtras
-                    ? {
-                          msg: finalMsg,
-                          ...(mentions.length > 0 && { mentions }),
-                          ...(styles.length > 0 && { styles }),
-                          ...(quote && { quote }),
-                          ...(urgency && { urgency }),
-                      }
-                    : finalMsg;
-
-                const result = await getApi().sendMessage(msgContent, threadId, Number(opts.type));
+                const parts = splitMessage({ text: finalMsg, styles, mentions });
+                const contentOf = (part, index) => {
+                    const first = index === 0;
+                    const extras = part.mentions.length > 0 || part.styles.length > 0 || (first && (quote || urgency));
+                    return extras
+                        ? {
+                              msg: part.text,
+                              ...(part.mentions.length > 0 && { mentions: part.mentions }),
+                              ...(part.styles.length > 0 && { styles: part.styles }),
+                              ...(first && quote && { quote }),
+                              ...(first && urgency && { urgency }),
+                          }
+                        : part.text;
+                };
+
+                const answers = await sendParts(parts, (part, index) =>
+                    getApi().sendMessage(contentOf(part, index), threadId, Number(opts.type)),
+                );
+                const result = answers[0];
+                if (parts.length > 1) {
+                    result.splitInto = parts.length;
+                    result.parts = answers.map((r) => ({
+                        msgId: r.message?.msgId ? String(r.message.msgId) : null,
+                        cliMsgId: r.message?.cliMsgId ? String(r.message.cliMsgId) : null,
+                    }));
+                }
 
                 // The cliMsgId comes back from zca-js, which hands over the
                 // clientId it actually put on the wire (patches/zca-js+2.2.0.patch
@@ -709,7 +729,11 @@ export function registerMsgCommands(program) {
                 // so — a fabricated one is worse than an absent one.
                 const cliMsgId = result.message?.cliMsgId ? String(result.message.cliMsgId) : null;
                 if (cliMsgId) result.cliMsgId = cliMsgId;
-                output(result, program.opts().json, () => success("Message sent"));
+                output(result, program.opts().json, () =>
+                    success(
+                        parts.length > 1 ? `Message sent in ${parts.length} parts (too long for one)` : "Message sent",
+                    ),
+                );
 
                 if (result.message && !cliMsgId) {
                     warning(

package/src/commands/sync.js

@@ -1259,7 +1259,18 @@ function reportRestore(res, win, ctx = {}) {
         return { status: "ok", reason: "phone confirmed: nothing missed in this window" };
     }
     if (res.reason === "partial" || res.reason === "socket-lost") {
-        const how = res.reason === "socket-lost" ? "the connection dropped" : "the run was cut short";
+        const how =
+            res.reason === "socket-lost"
+                ? "the connection dropped"
+                : res.rowErrors
+                  ? "some messages could not be written"
+                  : "the run was cut short";
+        if (res.rowErrors) {
+            warning(
+                `${res.rowErrors} message(s) could not be written to the local cache (${res.firstRowError ?? "unknown error"}). ` +
+                    "Re-run with --force once the cause is gone.",
+            );
+        }
         warning(
             `Partial restore: ${res.messagesSaved} message(s) from ${res.conversations} conversation(s) before ${how}.`,
         );

package/src/core/sync-v2/index.js

@@ -384,6 +384,7 @@ export function createShardSchedule(shardCount, opts = {}) {
  * @param {number} st.total - shards requested
  * @param {number} [st.resumes=0] - reconnects used
  * @param {number} [st.waitMs] - the budget, for the timeout wording
+ * @param {number} [st.rowErrors] - rows that could not be written to the cache
  * @returns {{reason: string, error: string|null}}
  */
 export function describeRestoreOutcome(st) {
@@ -410,6 +411,8 @@ export function describeRestoreOutcome(st) {
         };
     }
     if (st.finished < st.total) return { reason: st.socketDied ? "socket-lost" : "partial", error: null };
+    // Every shard came back, but a row did not reach the cache: a hole is not complete.
+    if (st.rowErrors > 0) return { reason: "partial", error: null };
     return { reason: "complete", error: null };
 }
 
@@ -874,7 +877,10 @@ export class SyncV2 {
         const ik = zproto.generateKeyPair();
         let conversations = 0,
             messagesSaved = 0,
-            attachmentsSaved = 0;
+            attachmentsSaved = 0,
+            rowErrors = 0;
+        /** The first reason a row could not be written, for the report. */
+        let firstRowError = null;
         const mappedThreads = new Set(),
             unmappedThreads = new Set();
         /** type name -> count, for the command's summary line. */
@@ -892,6 +898,8 @@ export class SyncV2 {
                 confirmed,
                 ...resumeInfo,
                 attachmentsSaved,
+                rowErrors,
+                firstRowError,
                 typeCounts: { ...typeCounts },
                 // Every threadId the conversation round accounted for. Anything
                 // cached outside this list is orphaned.
@@ -1253,8 +1261,12 @@ export class SyncV2 {
                                         messagesSaved++;
                                         if (info.hasAttachment) attachmentsSaved++;
                                         typeCounts[info.type] = (typeCounts[info.type] || 0) + 1;
-                                    } catch {
-                                        /* dedupe/constraint — keep going */
+                                    } catch (e) {
+                                        // Keep going with the rest of the chunk, but never silently: a row that cannot
+                                        // be written (a full disk, a locked file) leaves a hole, so the run does not
+                                        // call itself complete.
+                                        rowErrors++;
+                                        firstRowError ??= e?.message ?? String(e);
                                     }
                                 }
                             }
@@ -1314,6 +1326,7 @@ export class SyncV2 {
                 timedOut,
                 confirmed,
                 messagesSaved,
+                rowErrors,
                 finished,
                 total: shards.length,
                 resumes: schedule.resumes(),

package/src/core/zalo-client.js

@@ -8,7 +8,7 @@ import { basename } from "node:path";
 import { imageSizeFromFile } from "image-size/fromFile";
 import { Zalo } from "zca-js";
 import { HttpsProxyAgent } from "https-proxy-agent";
-import { ProxyAgent } from "undici";
+import { ProxyAgent, fetch as undiciFetch } from "undici";
 import { getActive } from "./accounts.js";
 import { loadCredentials } from "./credentials.js";
 import { info } from "../utils/output.js";
@@ -100,10 +100,14 @@ export function isLoggedIn() {
 /**
  * Create a proxy-aware fetch that uses undici ProxyAgent dispatcher.
  * Native Node.js fetch ignores the `agent` option — must use `dispatcher`.
+ *
+ * The fetch is undici's own, not the global one: Node bundles its own undici and the package here is another, and a
+ * dispatcher from one handed to the fetch of the other fails every request with "invalid onRequestStart method". A
+ * proxied account could not log in at all.
  */
-function createProxyFetch(proxyUrl) {
+export function createProxyFetch(proxyUrl) {
     const dispatcher = new ProxyAgent(proxyUrl);
-    return (url, init = {}) => fetch(url, { ...init, dispatcher });
+    return (url, init = {}) => undiciFetch(url, { ...init, dispatcher });
 }
 
 /**

package/src/mcp/instructions.js

@@ -0,0 +1,32 @@
+/**
+ * What every agent connecting to this MCP server is told once, on connect (the MCP `instructions` field), before it
+ * reads a single tool. The tool descriptions say what each tool does; this says what they share: the ids, the way to
+ * read and to send, and the few rules a model gets wrong without being told. Keep it short: clients put it in the
+ * model's context on every session.
+ */
+export const SERVER_INSTRUCTIONS = [
+    "Zalo MCP server: read and send messages on one Zalo account.",
+    "",
+    "IDS",
+    "- threadId is the conversation: the other person's user id for a DM, the group id for a group. Find one by name with zalo_search_threads, among recent ones with zalo_list_conversations, or from a phone number or username with zalo_lookup_user. `me` is the owner's My Documents.",
+    "- msgId is one message, and it is called `msgId` in every input and reply. Live messages also carry it as `id`, and a send reply as `messageId`: the same value, kept for older clients.",
+    "- userId is a Zalo user. A message's author is its `senderId` (a userId); group members have a `userId`. `@[userId]` mentions someone.",
+    "- cliMsgId is the sender's own id for a message. zalo_send_message returns it, and zalo_react and zalo_undo need it (they read it from the cache when you leave it out).",
+    '- threadType, as an input, is the number 0 (DM) or 1 (group); leave it out and the type stored for the thread is used. Messages show `threadType` as the text "dm" or "group": never pass that text back.',
+    "",
+    "READING",
+    "- To receive messages, wait with zalo_wait_for_message or poll with zalo_get_messages, then call zalo_mark_read with the returned `cursor`. If several bots share the server, each passes its own `consumer` name.",
+    "- For older messages use zalo_get_history (one conversation) or zalo_search_messages (text, across all conversations).",
+    "",
+    "SENDING TEXT",
+    "- Put real line breaks in `text`. Never type the two characters backslash and n: Zalo shows them as typed.",
+    '- Markdown is converted to Zalo formatting by default; `format: "plain"` sends the text as written.',
+    "- Mention someone in a group with `@[uid]` (`@[-1]` is everyone). Reply to a message with `quoteMsgId`.",
+    "- A text over 3000 bytes goes out as several messages; the reply lists each part.",
+    "- A sent message cannot be edited. To correct one, recall it with zalo_undo (msgId and cliMsgId from the send reply) and send it again.",
+    "",
+    "RULES",
+    "- Call zalo_sync only when the owner asked: it makes the owner's phone ask for a confirmation.",
+    "- zalo_group `leave` and `remove_member` need `confirm: true`.",
+    "- A refused call says why in its error text. Fix the argument it names; do not repeat the same call.",
+].join("\n");

package/src/mcp/mcp-http-transport.js

@@ -12,7 +12,7 @@ import { createHash, createHmac, randomBytes, timingSafeEqual } from "crypto";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { newMcpServer } from "./new-server.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -539,7 +539,7 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
     // MCP endpoint — stateless, fresh server+transport per request (POST, GET, DELETE per Streamable HTTP spec)
     app.all("/mcp", async (req, res) => {
         try {
-            const server = new McpServer({ name: "zalo-agent", version: pkg.version });
+            const server = newMcpServer(pkg.version);
             registerToolsFn(
                 server,
                 deps.api,

package/src/mcp/mcp-server.js

@@ -6,9 +6,9 @@
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerTools } from "./mcp-tools.js";
+import { newMcpServer } from "./new-server.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf8"));
@@ -24,13 +24,10 @@ const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf8
  * @param {string} [accountDir] - account data dir, for cache reads and media paths
  * @param {object} [stageLock] - the daemon's one-stage-at-a-time lock (daemon-channel.js)
  * @param {object} [syncJobs] - account-local sync tracker shared by all MCP requests
- * @returns {Promise<McpServer>}
+ * @returns {Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>}
  */
 export async function createMCPServer(api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs) {
-    const server = new McpServer({
-        name: "zalo-agent",
-        version: pkg.version,
-    });
+    const server = newMcpServer(pkg.version);
 
     registerTools(server, api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs);