@ardennguyen/zalo-agent-cli 2.5.4 → 2.5.6

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

@@ -4,6 +4,9 @@
  */
 
 import express from "express";
+import { renderPrometheus } from "../core/daemon-health.js";
+import { batchParams, waitResult } from "./wait-result.js";
+import { DEBUG_MARK } from "../core/log-sink.js";
 import https from "https";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "crypto";
 import { readFileSync } from "fs";
@@ -143,7 +146,8 @@ function resolveIssuerOrigin(req, configuredIssuer, isTls) {
 /**
  * Create HTTP or HTTPS MCP server with optional bearer token and OAuth 2.0 auth.
  * @param {Function} registerToolsFn - Registers tools on a McpServer instance
- * @param {object} deps - { api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs }
+ * @param {object} deps - { api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs, health }
+ *   (`health` is the daemon's ./core/daemon-health.js object: behind /health, /ready, /status and /metrics)
  * @param {number} port
  * @param {string|null} authToken - Bearer token (null = no auth unless oauth.clientSecret or oauth.clients is set)
  * @param {string} [host="127.0.0.1"] - Bind address
@@ -192,7 +196,7 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
                 const ua = String(req.headers["user-agent"] || "-").slice(0, 80);
                 const h = String(req.headers.host || "-");
                 console.error(
-                    `[mcp-http] ${req.method} ${req.originalUrl} -> ${res.statusCode} (host=${h} ip=${remoteIp} ua="${ua}")`,
+                    `${DEBUG_MARK}[mcp-http] ${req.method} ${req.originalUrl} -> ${res.statusCode} (host=${h} ip=${remoteIp} ua="${ua}")`,
                 );
             });
         }
@@ -503,7 +507,7 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
     // ── Bearer / OAuth2 Auth Middleware — skips /health ─────────────────
     if (signingSecret) {
         app.use((req, res, next) => {
-            if (req.path === "/health") return next();
+            if (req.path === "/health" || req.path === "/ready") return next();
             const authHeader = req.headers.authorization || "";
             const token = /^bearer\s+/i.test(authHeader) ? authHeader.slice(7).trim() : "";
 
@@ -583,27 +587,19 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
         const ac = new AbortController();
         res.on("close", () => ac.abort());
 
+        const { limit, settleMs } = batchParams({ limit: req.query.limit, settleMs: req.query.settle });
+
         try {
-            const msg = await deps.buffer.waitForMessage({
+            const { messages, hasMore } = await deps.buffer.waitForMessages({
                 threadId,
                 since,
                 timeoutMs: timeoutSec * 1000,
                 signal: ac.signal,
+                limit,
+                settleMs,
             });
             if (res.writableEnded) return;
-            if (msg) {
-                res.json({
-                    status: "message",
-                    message: msg,
-                    cursor: msg._cursor,
-                });
-            } else {
-                res.json({
-                    status: "timeout",
-                    message: null,
-                    cursor: deps.buffer.readCursor(),
-                });
-            }
+            res.json(waitResult({ messages, hasMore, cursorWhenEmpty: deps.buffer.readCursor() }));
         } catch (err) {
             if (!res.headersSent) {
                 res.status(500).json({ error: err.message });
@@ -611,15 +607,38 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
         }
     });
 
-    // Health check — no auth required
+    // Liveness — no auth required, and deliberately thin: that the process answers, and whether its socket is
+    // up. Everything else is behind the token (/status, /metrics).
     app.get("/health", (req, res) => {
         res.json({
             status: "ok",
             uptime: Math.floor(process.uptime()),
             threads: deps.buffer.getStats().length,
+            ...(deps.health ? { socket: deps.health.ready().socket, ready: deps.health.ready().ready } : {}),
         });
     });
 
+    // Readiness — no auth required: 200 only while the Zalo socket is connected, so a load balancer or a
+    // supervisor can stop sending work to a daemon whose account is offline.
+    app.get("/ready", (req, res) => {
+        const r = deps.health ? deps.health.ready() : { ready: true, socket: "unknown" };
+        res.status(r.ready ? 200 : 503).json(r);
+    });
+
+    // Everything the daemon knows about itself (protected by the auth middleware above).
+    app.get("/status", (req, res) => {
+        if (!deps.health) return res.status(503).json({ error: "this server does not report health" });
+        res.json(deps.health.snapshot());
+    });
+
+    // The same, as Prometheus text (protected by the auth middleware above; Prometheus sends a bearer token).
+    app.get("/metrics", (req, res) => {
+        if (!deps.health) return res.status(503).type("text/plain").send("# this server does not report health\n");
+        res.set("Content-Type", "text/plain; version=0.0.4; charset=utf-8").send(
+            renderPrometheus(deps.health.snapshot()),
+        );
+    });
+
     if (isTls) {
         const primary = https.createServer({ cert: tls.cert, key: tls.key }, app).listen(port, host, () => {
             console.error(`MCP HTTPS server listening on ${host}:${port}`);

package/src/mcp/mcp-tools.js

@@ -43,10 +43,12 @@ import { groupMemberUids, fetchMemberNames } from "../core/group-members.js";
 import { recentConversations } from "../core/recent-conversations.js";
 import { describeReadState, readOnZalo } from "../core/read-state.js";
 import { extractMessageText } from "../utils/extract-message-text.js";
-import { expandMentions, ALL_MENTION_UID } from "../utils/mentions.js";
+import { expandMentions, shiftStyles, ALL_MENTION_UID } from "../utils/mentions.js";
 import { resolveSelfThread } 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 { MAX_BATCH, MAX_SETTLE_MS, batchParams, waitResult } from "./wait-result.js";
 import {
     describeFriendAddError,
     extractErrorCode,
@@ -542,6 +544,16 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                             "msgId of a cached TEXT message in this thread to quote-reply to. " +
                                 "Get it from zalo_get_messages or zalo_get_history.",
                         ),
+                    format: z
+                        .enum(["markdown", "plain"])
+                        .optional()
+                        .describe(
+                            "How `text` is sent. `markdown` (the default) turns Markdown into Zalo's own formatting, because Zalo " +
+                                "shows `**bold**` and `- item` as typed: **bold**, *italic*, ~~strike~~, # headings (bold), " +
+                                "- bullets (real bullets), 1. lists (numbers kept), > quotes, `code`, [text](url) (the URL stays in " +
+                                "the text), and {red:text}/{green:text}/{big:text} colors. `plain` sends the text exactly as written. " +
+                                "Text that is not Markdown (snake_case, 2 * 3 * 4) is left alone either way.",
+                        ),
                     urgency: z
                         .enum(["normal", "important", "urgent"])
                         .optional()
@@ -577,6 +589,7 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
             threadType: threadTypeIn,
             quoteMsgId,
             urgency: urgencyIn,
+            format: formatIn,
         }) => {
             // `me` (or the own uid) is My Documents, always a 1-1 -- resolved
             // before anything else reads the thread id, as `msg send me` is.
@@ -625,8 +638,17 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                     if (missing.length > 0) {
                         return err(`File not found: ${missing.join(", ")}`);
                     }
+                    // A caption is text too: Markdown in it is converted the same way.
+                    const caption =
+                        text && resolveSendFormat({ explicit: formatIn, fallback: "markdown" }) === "markdown"
+                            ? markdownToZalo(text)
+                            : { text: text || "", styles: [] };
                     const result = await api.sendMessage(
-                        { msg: text || "", attachments: absPaths },
+                        {
+                            msg: caption.text,
+                            attachments: absPaths,
+                            ...(caption.styles.length > 0 && { styles: caption.styles }),
+                        },
                         threadId,
                         Number(threadType),
                     );
@@ -667,13 +689,19 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                 // order against and nothing to move — if styles are ever added to
                 // this tool, they must be run through `shiftStyles(styles,
                 // expanded.edits)` the way `msg send` does.
+                // Markdown first, then mentions: a display name may itself contain `*` or `_`, whereas an
+                // `@[uid]` token contains no Markdown (the converter passes it through). The style ranges
+                // are counted before the names go in, so they move across the substitutions (`shiftStyles`).
+                const format = resolveSendFormat({ explicit: formatIn, fallback: "markdown" });
+                const converted = format === "markdown" ? markdownToZalo(text) : { text, styles: [] };
                 const unresolved = [];
-                const expanded = expandMentions(text, (uid) => {
+                const expanded = expandMentions(converted.text, (uid) => {
                     const name = cachedDisplayName(uid);
                     if (!name && uid !== ALL_MENTION_UID) unresolved.push(uid);
                     return name;
                 });
                 const mentions = expanded.mentions;
+                const styles = shiftStyles(converted.styles, expanded.edits);
 
                 // zca-js drops mentions outside a group, so a DM send would
                 // quietly arrive with the names as plain text and nobody tagged.
@@ -726,11 +754,12 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
 
                 // A plain send stays a plain string: the object form is only
                 // built when there is something to put in it.
-                const hasExtras = mentions.length > 0 || Boolean(quote) || Boolean(urgency);
+                const hasExtras = mentions.length > 0 || styles.length > 0 || Boolean(quote) || Boolean(urgency);
                 const content = hasExtras
                     ? {
                           msg: expanded.text,
                           ...(mentions.length > 0 && { mentions }),
+                          ...(styles.length > 0 && { styles }),
                           ...(quote && { quote }),
                           ...(urgency && { urgency }),
                       }
@@ -755,6 +784,7 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                     // Only when it differs, so the common send keeps its shape:
                     // the agent wrote `@[123]` and needs to know what was sent.
                     ...(expanded.text !== text && { text: expanded.text }),
+                    ...(styles.length > 0 && { formatted: styles.length }),
                     ...(unresolved.length > 0 && { unresolvedMentions: unresolved }),
                     ...(warnings.length > 0 && { warnings }),
                 });
@@ -2347,7 +2377,10 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
             description:
                 "Long-poll the live MCP message buffer for the next incoming watched message without manual polling. " +
                 "Returns immediately if a buffered message newer than `since` is already waiting; otherwise waits up to " +
-                "`timeoutSec` seconds (default 55, max 300) for a new message to arrive. Mirrors GET /events/wait for " +
+                "`timeoutSec` seconds (default 55, max 300) for a new message to arrive. `limit` (default 1, max 100) returns " +
+                "up to that many buffered messages in one call, in order, in `messages` (`message` is the first and `cursor` " +
+                "the last, so `since: cursor` continues where the batch ended; `hasMore` says more are already waiting); " +
+                "`settleMs` waits that long after the first for the rest of a burst. Mirrors GET /events/wait for " +
                 "remote HTTPS/OAuth2 MCP clients.",
             inputSchema: z.object({
                 threadId: z
@@ -2371,48 +2404,61 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                     .max(300)
                     .default(55)
                     .describe("Maximum seconds to wait before returning `status: 'timeout'` (default 55, max 300)"),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(MAX_BATCH)
+                    .default(1)
+                    .describe(`Most messages to return in one call (default 1, max ${MAX_BATCH})`),
+                settleMs: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .max(MAX_SETTLE_MS)
+                    .default(0)
+                    .describe(
+                        `After the first message arrives, wait this many ms for the rest of a burst (default 0, max ${MAX_SETTLE_MS})`,
+                    ),
             }),
         },
-        async ({ threadId, since, timeoutSec = 55 }) => {
+        async ({ threadId, since, timeoutSec = 55, limit = 1, settleMs = 0 }) => {
             try {
-                if (typeof buffer?.waitForMessage !== "function") {
-                    return err("Live message buffer does not support waitForMessage in this context.");
+                if (typeof buffer?.waitForMessages !== "function") {
+                    return err("Live message buffer does not support waitForMessages in this context.");
                 }
                 const cleanThreadId = typeof threadId === "string" && threadId.trim() ? threadId.trim() : null;
                 const clampedSec = Math.max(1, Math.min(300, Number(timeoutSec) || 55));
-                const msg = await buffer.waitForMessage({
+                const batch = batchParams({ limit, settleMs });
+                const { messages, hasMore } = await buffer.waitForMessages({
                     threadId: cleanThreadId,
                     since: typeof since === "number" && Number.isFinite(since) ? since : undefined,
                     timeoutMs: clampedSec * 1000,
+                    ...batch,
                 });
-                if (msg) {
-                    const tid = String(msg.threadId || "");
-                    let threadName = nameCache?.get(tid)?.name || null;
-                    if (!threadName && tid) {
-                        try {
-                            threadName = getDisplayName(tid) || null;
-                        } catch {
-                            threadName = null;
-                        }
-                    }
-                    return ok({
-                        status: "message",
-                        message: {
-                            ...msg,
-                            ...(threadName ? { threadName } : {}),
+                return ok(
+                    waitResult({
+                        messages,
+                        hasMore,
+                        cursorWhenEmpty: Math.max(
+                            typeof since === "number" && Number.isFinite(since) ? since : 0,
+                            Number(buffer._globalCursor) || 0,
+                            typeof buffer.readCursor === "function" ? buffer.readCursor() : 0,
+                        ),
+                        decorate: (msg) => {
+                            const tid = String(msg.threadId || "");
+                            let threadName = nameCache?.get(tid)?.name || null;
+                            if (!threadName && tid) {
+                                try {
+                                    threadName = getDisplayName(tid) || null;
+                                } catch {
+                                    threadName = null;
+                                }
+                            }
+                            return { ...msg, ...(threadName ? { threadName } : {}) };
                         },
-                        cursor: msg._cursor,
-                    });
-                }
-                return ok({
-                    status: "timeout",
-                    message: null,
-                    cursor: Math.max(
-                        typeof since === "number" && Number.isFinite(since) ? since : 0,
-                        Number(buffer._globalCursor) || 0,
-                        typeof buffer.readCursor === "function" ? buffer.readCursor() : 0,
-                    ),
-                });
+                    }),
+                );
             } catch (e) {
                 console.error("[mcp-tools] zalo_wait_for_message error:", e.message);
                 return err(e.message);

package/src/mcp/message-buffer.js

@@ -9,6 +9,45 @@
  * (maxSize per thread, maxAge), which bounds memory as before.
  */
 
+import { batchParams } from "./wait-result.js";
+
+/** Sleep `ms`, or less if `signal` aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) return resolve();
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+
+/** How often a settling wait looks at the buffer to see whether the batch is already full. */
+const SETTLE_POLL_MS = 20;
+
+/**
+ * Let a burst land: read, and keep reading for up to `settleMs`, but stop the moment `limit` messages
+ * are in hand (a full batch has nothing to wait for) or `signal` aborts.
+ *
+ * @param {() => { messages: object[], hasMore: boolean }} read
+ * @param {number} limit
+ * @param {number} settleMs
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<{ messages: object[], hasMore: boolean }>}
+ */
+async function settleUntilFull(read, limit, settleMs, signal) {
+    const deadline = Date.now() + settleMs;
+    let r = read();
+    while (r.messages.length < limit && Date.now() < deadline && !signal?.aborted) {
+        await sleep(Math.min(SETTLE_POLL_MS, Math.max(1, deadline - Date.now())), signal);
+        r = read();
+    }
+    return r;
+}
+
 /** The consumer a caller that names none reads as. */
 export const DEFAULT_CONSUMER = "default";
 
@@ -78,13 +117,64 @@ export class MessageBuffer {
      * @param {AbortSignal} [opts.signal] - Optional abort signal (e.g. when HTTP client disconnects)
      * @returns {Promise<object|null>} The message object, or null on timeout/abort
      */
-    waitForMessage({ threadId = null, since = undefined, timeoutMs = 60000, signal = undefined } = {}) {
+    async waitForMessage(opts = {}) {
+        const { messages } = await this.waitForMessages({ ...opts, limit: 1, settleMs: 0 });
+        return messages[0] ?? null;
+    }
+
+    /**
+     * Wait for buffered messages and return up to `limit` of them at once, in cursor order.
+     *
+     * With `since`, messages already buffered after it are returned at once; otherwise the call waits for
+     * the next message to arrive. `settleMs` then gives a burst that long to land, so the reply holds it
+     * whole instead of the first message alone. Nothing is waited for once `limit` is reached.
+     *
+     * @param {object} [opts]
+     * @param {string} [opts.threadId] - Optional thread filter
+     * @param {number} [opts.since] - Optional cursor (exclusive)
+     * @param {number} [opts.timeoutMs=60000] - Max wait for the FIRST message
+     * @param {AbortSignal} [opts.signal]
+     * @param {number} [opts.limit=1] - Most messages to return (1-100)
+     * @param {number} [opts.settleMs=0] - After the first message, wait this long for more (0-5000)
+     * @returns {Promise<{ messages: object[], hasMore: boolean }>} `messages` is empty on timeout or abort
+     */
+    async waitForMessages({
+        threadId = null,
+        since = undefined,
+        timeoutMs = 60000,
+        signal = undefined,
+        limit = 1,
+        settleMs = 0,
+    } = {}) {
+        const { limit: max, settleMs: settle } = batchParams({ limit, settleMs });
+        const from = (cursor) => this.read(threadId || undefined, cursor, max);
+
         if (since !== undefined && since !== null && Number.isFinite(Number(since))) {
-            const existing = this.read(threadId || undefined, Number(since), 1);
-            if (existing.messages.length > 0) {
-                return Promise.resolve(existing.messages[0]);
+            let r = from(Number(since));
+            if (r.messages.length > 0) {
+                if (settle > 0 && r.messages.length < max) {
+                    r = await settleUntilFull(() => from(Number(since)), max, settle, signal);
+                }
+                return { messages: r.messages, hasMore: r.hasMore };
             }
         }
+        if (signal?.aborted) return { messages: [], hasMore: false };
+
+        const first = await this._waitNext({ threadId, timeoutMs, signal });
+        if (!first) return { messages: [], hasMore: false };
+        // From the first message on: it, and whatever arrived with it or while settling.
+        const r =
+            settle > 0 && max > 1
+                ? await settleUntilFull(() => from(first._cursor - 1), max, settle, signal)
+                : from(first._cursor - 1);
+        return r.messages.length ? { messages: r.messages, hasMore: r.hasMore } : { messages: [first], hasMore: false };
+    }
+
+    /**
+     * Resolve with the next message pushed (any thread, or `threadId`), or null on timeout or abort.
+     * @private
+     */
+    _waitNext({ threadId = null, timeoutMs = 60000, signal = undefined } = {}) {
         if (signal?.aborted) {
             return Promise.resolve(null);
         }

package/src/mcp/wait-result.js

@@ -0,0 +1,52 @@
+/**
+ * What a "wait for messages" call returns, in one place: the HTTP route `GET /events/wait`, the MCP tool
+ * `zalo_wait_for_message` and `mcp wait` over the daemon channel all build it here, so they cannot drift.
+ *
+ * It used to hand back one message per call, so a bot behind a busy account made one round trip per
+ * message. `limit` (1-100, default 1) returns up to that many buffered messages at once, in cursor order,
+ * and `settleMs` waits that long after the first arrives so a burst lands in one reply.
+ *
+ * The single-message fields are unchanged and still filled (`message` is the first, `cursor` the last
+ * one returned, so `since=cursor` continues exactly where the batch ended); `messages`, `count` and
+ * `hasMore` are added. With `limit` 1 the reply is what it always was, plus those three fields.
+ */
+
+/** Most messages one call returns. */
+export const MAX_BATCH = 100;
+/** Longest a call waits for company after the first message. */
+export const MAX_SETTLE_MS = 5000;
+
+/**
+ * Clamp the caller's batch settings; anything unusable is the default (one message, no settling).
+ *
+ * @param {{ limit?: unknown, settleMs?: unknown }} [raw]
+ * @returns {{ limit: number, settleMs: number }}
+ */
+export function batchParams({ limit, settleMs } = {}) {
+    const l = Number(limit);
+    const s = Number(settleMs);
+    return {
+        limit: Number.isFinite(l) && l >= 1 ? Math.min(MAX_BATCH, Math.floor(l)) : 1,
+        settleMs: Number.isFinite(s) && s > 0 ? Math.min(MAX_SETTLE_MS, Math.floor(s)) : 0,
+    };
+}
+
+/**
+ * @param {object} args
+ * @param {object[]} args.messages - Buffered messages, in cursor order (empty on timeout)
+ * @param {boolean} [args.hasMore] - More messages are already buffered after these
+ * @param {number} args.cursorWhenEmpty - The cursor to report on a timeout, so the caller can carry on from it
+ * @param {(m: object) => object} [args.decorate] - Adds what only this daemon knows, e.g. the thread name
+ * @returns {{ status: "message"|"timeout", message: object|null, messages: object[], count: number, hasMore: boolean, cursor: number }}
+ */
+export function waitResult({ messages, hasMore = false, cursorWhenEmpty, decorate = (m) => m }) {
+    const out = messages.map(decorate);
+    return {
+        status: out.length ? "message" : "timeout",
+        message: out[0] ?? null,
+        messages: out,
+        count: out.length,
+        hasMore: Boolean(hasMore) && out.length > 0,
+        cursor: out.length ? messages[messages.length - 1]._cursor : cursorWhenEmpty,
+    };
+}