@ardennguyen/zalo-agent-cli 2.5.4 → 2.5.6

package/src/commands/listen.js

@@ -3,18 +3,20 @@
  * Production-ready with auto-reconnect and re-login.
  */
 
-import { createHmac } from "crypto";
-import { appendFileSync, mkdirSync, existsSync } from "fs";
+import { appendFileSync, mkdirSync, existsSync, readFileSync } from "fs";
 import { resolve, join } from "path";
 import { getApi, clearSession } from "../core/zalo-client.js";
 import { success, error, info, warning, output } from "../utils/output.js";
 import { resolveWebhookSecret } from "../utils/secrets.js";
 import { parseAccountId, selectDaemonAccount, loginDaemonAccount } from "../core/daemon-account.js";
 import { updateAccountName } from "../core/accounts.js";
-import { getAccountDir } from "../core/credentials.js";
+import { CONFIG_DIR, getAccountDir } from "../core/credentials.js";
+import { createStartupGate, resolveStartupSettings } from "../core/startup-gate.js";
 import { acquireLock, releaseLock } from "../core/lock.js";
 import {
     createStageLock,
+    statusViaDaemon,
+    configureLogging,
     startDaemonChannel,
     getDaemonStatus,
     stopDaemon,
@@ -43,7 +45,12 @@ import { downloadSyncedMedia } from "../core/sync-v2/media.js";
 import { SyncManager } from "../core/sync.js";
 import { describeGap } from "../core/sync-v2/gap-advice.js";
 import { createDeliveredReceipts } from "../core/receipts.js";
-import { envForAccount } from "../mcp/mcp-config.js";
+import { envForAccount, resolveWebhookDelivery } from "../mcp/mcp-config.js";
+import { startWebhookDelivery } from "../core/webhook-outbox.js";
+import { createDaemonHealth, describeHealth } from "../core/daemon-health.js";
+import { DEBUG_MARK, LOG_LEVELS } from "../core/log-sink.js";
+
+const PKG_VERSION = JSON.parse(readFileSync(join(import.meta.dirname, "..", "..", "package.json"), "utf8")).version;
 
 /** Thread types matching zca-js ThreadType enum */
 const THREAD_USER = 0;
@@ -98,11 +105,19 @@ export function registerListenCommand(program) {
             "--no-self-heal",
             "Do not pull what a dropped socket missed from Zalo's offline queue on reconnect (the default does, as Zalo Web does, on this socket and with no phone tap)",
         )
+        .option(
+            "--log-level <level>",
+            "Log level of daemon.log (and of stderr in the foreground): error, warn, info (default) or debug, which adds a line per HTTP request and per message. Env: ZALO_LOG_LEVEL[_<ownId>]; also ZALO_LOG_FORMAT=json, ZALO_LOG_MAX_SIZE (default 50m) and ZALO_LOG_KEEP (default 3) for rotation",
+        )
         .option("-d, --daemon", "Run in the background (logs to <accountDir>/daemon.log)")
         .option("--stop", "Stop the running background daemon for this account")
         .option("--status", "Show background daemon status for this account")
         .action(async (opts) => {
             const jsonMode = program.opts().json;
+            if (opts.logLevel !== undefined && !LOG_LEVELS.includes(String(opts.logLevel).trim().toLowerCase())) {
+                error(`Invalid --log-level "${opts.logLevel}": use one of ${LOG_LEVELS.join(", ")}.`);
+                process.exit(1);
+            }
             // An empty secret is refused before anything else: see resolveWebhookSecret().
             let cliWebhookSecret;
             try {
@@ -125,12 +140,18 @@ export function registerListenCommand(program) {
 
             if (opts.status) {
                 const status = getDaemonStatus(accountDir);
-                output({ accountId: activeAcc.ownId, ...status }, jsonMode, () => {
+                // What the daemon says about itself; an older daemon has the channel but not the route.
+                const reported = status.running ? await statusViaDaemon(accountDir) : null;
+                const health = reported?.ok ? reported.health : null;
+                output({ accountId: activeAcc.ownId, ...status, health }, jsonMode, () => {
                     if (status.running) {
                         success(
                             `Daemon running for account ${activeAcc.ownId} (PID ${status.pid}${status.channelPort ? `, channel 127.0.0.1:${status.channelPort}` : ""})`,
                         );
                         info(`Log file: ${status.logPath}`);
+                        if (health) for (const line of describeHealth(health)) info(line);
+                        else
+                            info("Health: not reported (this daemon predates the health route; restart it to see it).");
                     } else {
                         info(`No daemon running for account ${activeAcc.ownId}`);
                         info(`Log file: ${status.logPath}`);
@@ -153,6 +174,16 @@ export function registerListenCommand(program) {
                 return;
             }
 
+            // Levels and rotation of the log, now that the account is known (src/core/log-sink.js).
+            const logging = configureLogging({
+                ownId: activeAcc.ownId,
+                levelFlag: opts.logLevel?.trim().toLowerCase() || null,
+                // The process that launches a background daemon talks to the user; only the daemon's own output is a log.
+                filterStderr: !(opts.daemon && !process.env.ZALO_DAEMON_CHILD),
+            });
+            if (!process.env.ZALO_DAEMON_CHILD)
+                for (const w of logging.warnings) console.error(`[listen] [logging] ${w}`);
+
             if (opts.daemon && !process.env.ZALO_DAEMON_CHILD) {
                 const spawned = await spawnDaemonProcess({ accountDir, args: process.argv.slice(1) });
                 if (!spawned.ok) {
@@ -205,9 +236,21 @@ export function registerListenCommand(program) {
                     console.error(`[listen] Failed to release lock: ${e.message}`);
                 }
             };
+            // Spread a fleet's start-up: a random delay and a cap on daemons logging in at once
+            // (ZALO_START_JITTER, ZALO_LOGIN_SLOTS; src/core/startup-gate.js). Both off by default.
+            const startup = resolveStartupSettings({ env: process.env, ownId: activeAcc.ownId });
+            for (const w of startup.warnings) console.error(`[listen] ${w}`);
+            const gate = createStartupGate({
+                configDir: CONFIG_DIR,
+                ownId: activeAcc.ownId,
+                settings: startup,
+                log: (m) => console.error(`[listen] ${m}`),
+            });
+            await gate.enter();
             try {
                 await loginDaemonAccount(activeAcc);
             } catch (e) {
+                gate.leave();
                 releaseLock(accountDir);
                 error(`Pinned account login failed: ${e.message}`);
                 process.exit(1);
@@ -215,7 +258,10 @@ export function registerListenCommand(program) {
             try {
                 initDb(join(accountDir, "zalo.db"));
                 info(`Local database initialized at ${accountDir}/zalo.db`);
+                // Logged in and the cache open: the heavy part of start-up is over.
+                gate.leave();
             } catch (err) {
+                gate.leave();
                 releaseLock(accountDir);
                 error(`Failed to initialize local DB: ${err.message}`);
                 process.exit(1);
@@ -408,27 +454,32 @@ export function registerListenCommand(program) {
                 warning("A webhook secret is set but no webhook URL: nothing will be signed or sent. Pass -w <url>.");
             }
 
-            /** Fire-and-forget webhook POST — never blocks event processing */
-            function postWebhook(data) {
-                if (!webhookUrl) return;
-                const payload = { accountId: activeAcc.ownId, ...data };
-                const body = JSON.stringify(payload);
-                const headers = { "Content-Type": "application/json" };
-                if (webhookSecret) {
-                    headers["Authorization"] = `Bearer ${webhookSecret}`;
-                    headers["X-Zalo-Signature"] =
-                        `sha256=${createHmac("sha256", webhookSecret).update(body).digest("hex")}`;
-                }
-                fetch(webhookUrl, {
-                    method: "POST",
-                    headers,
-                    body,
-                    signal: AbortSignal.timeout(5000),
-                }).catch((e) => {
-                    console.error(`[listen] Webhook failed: ${e.message}`);
+            // The same durable outbox `mcp start` uses (src/core/webhook-outbox.js): an event is
+            // written to disk first and delivered from there, so a receiver that is down costs a
+            // backlog (zalo-agent mcp webhook status), not events.
+            let webhookDelivery = null;
+            if (webhookUrl) {
+                const delivery = resolveWebhookDelivery(activeAcc.ownId);
+                for (const w of delivery.warnings) warning(w);
+                webhookDelivery = startWebhookDelivery({
+                    accountDir,
+                    accountId: activeAcc.ownId,
+                    url: webhookUrl,
+                    secret: webhookSecret,
+                    batchSize: delivery.batchSize,
+                    maxAgeMs: delivery.maxAgeMs,
+                    log: (line) => console.error(`[listen] ${line}`),
                 });
             }
 
+            /** Queue an event for the webhook — never blocks event processing */
+            function postWebhook(data) {
+                // Only a message has an id that stays the same on a repeat (live, then catch-up);
+                // two reactions to one message must both be delivered.
+                const key = data.event === "message" && data.msgId ? `message:${data.msgId}` : null;
+                webhookDelivery?.enqueue(key, { accountId: activeAcc.ownId, ...data });
+            }
+
             // Setup save directory if --save flag provided
             let saveDir = null;
             if (opts.save) {
@@ -453,7 +504,10 @@ export function registerListenCommand(program) {
             /** Output event as JSON or human-readable, save locally, then post to webhook */
             function emitEvent(data, humanMsg) {
                 eventCount++;
-                if (jsonMode) {
+                if (process.env.ZALO_DAEMON_CHILD === "1") {
+                    // In daemon.log an event line is a per-message line: debug (it carries the message text).
+                    console.error(`${DEBUG_MARK}${jsonMode ? JSON.stringify(data) : humanMsg}`);
+                } else if (jsonMode) {
                     console.log(JSON.stringify(data));
                 } else {
                     info(humanMsg);
@@ -534,6 +588,11 @@ export function registerListenCommand(program) {
             });
             const socketContext = createSocketContext({ lock: stageLock, monitor: loopMonitor });
             setUserInfoLogger(daemonLog);
+            // Same health object `mcp start` builds (src/core/daemon-health.js): `listen --status` prints it.
+            const health = createDaemonHealth({ kind: "listen", accountId: activeAcc.ownId, version: PKG_VERSION });
+            health.setSource("gaps", () => getPendingSyncGaps().length);
+            health.setSource("stage", () => stageLock.current());
+            health.setSource("webhook", () => webhookDelivery?.status() ?? null);
             const socketTap = createSocketTap({ log: (line) => console.error(`[listen] ${line}`) });
             // Read state other devices report -- a conversation read on the
             // phone, an unread mark set or cleared there -- which zca-js
@@ -567,6 +626,7 @@ export function registerListenCommand(program) {
 
             /** Attach ALL handlers (data + lifecycle) to current API listener */
             function attachAllHandlers(api) {
+                health.attach(api.listener);
                 // --- Message events ---
                 // Registered unconditionally. --events, --filter and --no-self
                 // decide what is PRINTED, forwarded and saved as JSONL -- never
@@ -952,7 +1012,9 @@ export function registerListenCommand(program) {
             const shutdown = () => {
                 // First, before anything can emit a close event.
                 stopping = true;
+                health.noteStopping();
                 channel?.stop();
+                webhookDelivery?.stop();
                 deliveredReceipts.stop();
                 try {
                     getApi().listener.stop();
@@ -998,6 +1060,7 @@ export function registerListenCommand(program) {
                     // The self-heal's lock: a stage and a catch-up never share the socket.
                     lock: stageLock,
                     onStop: shutdown,
+                    onStatus: () => health.snapshot(),
                 });
                 info(`Sync & upload channel ready on 127.0.0.1:${channel.port} — this socket is reused for both.`);
                 info("`zalo-agent sync` will run its socket stages here; it still needs your phone tap.");

package/src/commands/mcp-webhook.js

@@ -0,0 +1,197 @@
+/**
+ * `zalo-agent mcp webhook ...` — look at, and act on, the durable webhook outbox
+ * (src/core/webhook-outbox.js) of an account: how many events wait for the receiver, which were
+ * dead-lettered and why. These read and write `accounts/<ownId>/webhook-outbox.db` directly; SQLite
+ * lets them run beside the daemon that is delivering from it.
+ */
+
+import { existsSync } from "node:fs";
+import { parseAccountId, selectDaemonAccount } from "../core/daemon-account.js";
+import { getAccountDir } from "../core/credentials.js";
+import { getDaemonStatus } from "../core/daemon-channel.js";
+import { openOutbox, outboxPath } from "../core/webhook-outbox.js";
+import { error, info, output, success } from "../utils/output.js";
+
+const iso = (ms) => (ms ? new Date(ms).toISOString() : null);
+
+/** @param {number} ms */
+function age(ms) {
+    const s = Math.round(ms / 1000);
+    if (s < 90) return `${s}s`;
+    if (s < 5400) return `${Math.round(s / 60)}m`;
+    return `${(s / 3600).toFixed(1)}h`;
+}
+
+/**
+ * @param {object} program - Commander root
+ * @param {object} opts - The subcommand's options
+ * @returns {{ ownId: string, accountDir: string }}
+ */
+function pickAccount(program, opts) {
+    try {
+        const requested = opts.account ?? program.opts().account ?? (process.env.ZALO_ACCOUNT?.trim() || undefined);
+        const acc = selectDaemonAccount(requested);
+        return { ownId: acc.ownId, accountDir: getAccountDir(acc.ownId) };
+    } catch (e) {
+        error(`Account selection failed: ${e.message}`);
+        process.exit(1);
+    }
+}
+
+/**
+ * Open the outbox, or say plainly that this account has none yet.
+ * @param {string} accountDir
+ * @param {boolean} readonly
+ * @returns {object|null}
+ */
+function openOrNone(accountDir, readonly) {
+    if (!existsSync(outboxPath(accountDir))) return null;
+    try {
+        return openOutbox(accountDir, { readonly });
+    } catch (e) {
+        error(`Could not open the webhook outbox: ${e.message}`);
+        process.exit(1);
+    }
+}
+
+const NO_OUTBOX =
+    "This account has no webhook outbox: no event has been queued for a webhook yet (-w / ZALO_WEBHOOK_URL).";
+
+/**
+ * @param {object} mcp - The `mcp` Commander command
+ * @param {object} program - Commander root, for the global --json / --account
+ */
+export function registerMCPWebhookCommands(mcp, program) {
+    const webhook = mcp
+        .command("webhook")
+        .description("Inspect and manage the durable webhook outbox: events waiting for the receiver and dead letters");
+
+    webhook
+        .command("status")
+        .description("Backlog of the webhook outbox: queued, dead-lettered, oldest wait, last success and error")
+        .option("--account <id>", "Target a specific registered account ID (default: active account)", parseAccountId)
+        .action((opts) => {
+            const { ownId, accountDir } = pickAccount(program, opts);
+            const daemon = getDaemonStatus(accountDir);
+            const outbox = openOrNone(accountDir, true);
+            const stats = outbox?.stats() ?? null;
+            outbox?.close();
+            const result = {
+                accountId: ownId,
+                daemon: { running: daemon.running, pid: daemon.pid },
+                outbox: stats && {
+                    path: outboxPath(accountDir),
+                    pending: stats.pending,
+                    dead: stats.dead,
+                    oldestPendingAt: iso(stats.oldestPendingAt),
+                    oldestPendingAgeMs: stats.oldestPendingAt ? Math.max(0, Date.now() - stats.oldestPendingAt) : 0,
+                    deliveredTotal: stats.deliveredTotal,
+                    lastSuccessAt: iso(stats.lastSuccessAt),
+                    lastError: stats.lastError,
+                    lastErrorAt: iso(stats.lastErrorAt),
+                    lastStatus: stats.lastStatus,
+                },
+            };
+            output(result, program.opts().json, () => {
+                if (!stats) return info(NO_OUTBOX);
+                const o = result.outbox;
+                info(`Account ${ownId}  daemon: ${daemon.running ? `running (pid ${daemon.pid})` : "not running"}`);
+                info(`Queued: ${o.pending}${o.pending ? `  (oldest waiting ${age(o.oldestPendingAgeMs)})` : ""}`);
+                info(`Dead-lettered: ${o.dead}${o.dead ? "  (zalo-agent mcp webhook list --dead)" : ""}`);
+                info(`Delivered since the outbox was created: ${o.deliveredTotal}`);
+                info(`Last delivery: ${o.lastSuccessAt ?? "never"}`);
+                if (o.lastError) info(`Last error: ${o.lastError}${o.lastErrorAt ? `  at ${o.lastErrorAt}` : ""}`);
+                if (o.pending && !daemon.running)
+                    info("Queued events are sent when `mcp start` / `listen` runs again.");
+            });
+        });
+
+    webhook
+        .command("list")
+        .description("List queued events, or the dead letters, oldest first")
+        .option("--account <id>", "Target a specific registered account ID (default: active account)", parseAccountId)
+        .option("--dead", "Only dead-lettered events")
+        .option("--pending", "Only events still queued")
+        .option("-n, --limit <n>", "Maximum rows (default: 50)", "50")
+        .action((opts) => {
+            const limit = Number(opts.limit);
+            if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+                error(`Invalid --limit "${opts.limit}": must be an integer between 1 and 1000.`);
+                process.exit(1);
+            }
+            if (opts.dead && opts.pending) {
+                error("Pass --dead or --pending, not both.");
+                process.exit(1);
+            }
+            const { ownId, accountDir } = pickAccount(program, opts);
+            const outbox = openOrNone(accountDir, true);
+            const rows = (
+                outbox?.list({ status: opts.dead ? "dead" : opts.pending ? "pending" : undefined, limit }) ?? []
+            ).map((r) => {
+                let event = {};
+                try {
+                    event = JSON.parse(r.body);
+                } catch {
+                    /* a row the receiver gets as-is; shown without fields */
+                }
+                return {
+                    seq: r.seq,
+                    status: r.status,
+                    attempts: r.attempts,
+                    queuedAt: iso(r.created_at),
+                    lastAttemptAt: iso(r.last_attempt_at),
+                    lastError: r.last_error,
+                    event: event.event ?? null,
+                    id: event.id ?? event.msgId ?? null,
+                    threadId: event.threadId ?? null,
+                };
+            });
+            outbox?.close();
+            output({ accountId: ownId, count: rows.length, events: rows }, program.opts().json, () => {
+                if (!outbox) return info(NO_OUTBOX);
+                if (!rows.length) return info("Nothing queued.");
+                for (const r of rows) {
+                    info(
+                        `#${r.seq} ${r.status} attempts=${r.attempts} ${r.event ?? "?"} id=${r.id ?? "-"} thread=${r.threadId ?? "-"} queued ${r.queuedAt}${r.lastError ? `  — ${r.lastError}` : ""}`,
+                    );
+                }
+            });
+        });
+
+    for (const [name, verb, description] of [
+        [
+            "retry",
+            "requeued",
+            "Put dead-lettered events back in the queue (all, or one by number); the daemon sends them within 30 seconds",
+        ],
+        ["purge", "deleted", "Delete dead-lettered events for good (all, or one by number)"],
+    ]) {
+        webhook
+            .command(`${name} [seq]`)
+            .description(description)
+            .option(
+                "--account <id>",
+                "Target a specific registered account ID (default: active account)",
+                parseAccountId,
+            )
+            .action((seqArg, opts) => {
+                let seq;
+                if (seqArg !== undefined) {
+                    seq = Number(seqArg);
+                    if (!Number.isInteger(seq) || seq < 1) {
+                        error(`Invalid event number "${seqArg}": use the # from \`mcp webhook list --dead\`.`);
+                        process.exit(1);
+                    }
+                }
+                const { ownId, accountDir } = pickAccount(program, opts);
+                const outbox = openOrNone(accountDir, false);
+                const n = !outbox ? 0 : name === "retry" ? outbox.retryDead({ seq }) : outbox.purgeDead({ seq });
+                outbox?.close();
+                output({ accountId: ownId, [verb]: n }, program.opts().json, () => {
+                    if (!outbox) info(NO_OUTBOX);
+                    else if (n) success(`${n} dead-lettered event(s) ${verb}.`);
+                    else info(seq ? `No dead-lettered event #${seq}.` : "No dead-lettered events.");
+                });
+            });
+    }
+}