zalo-agent-cli 1.1.0 → 1.3.0

package/src/mcp/mcp-tools.js

@@ -0,0 +1,171 @@
+/**
+ * MCP tool registrations for Zalo message access and sending.
+ * Registers 4 tools: zalo_get_messages, zalo_send_message, zalo_list_threads, zalo_mark_read.
+ */
+
+import { z } from "zod";
+
+/** Thread type constants matching zca-js ThreadType enum */
+const THREAD_USER = 0;
+const THREAD_GROUP = 1;
+
+/**
+ * Wrap a result object into MCP tool content format.
+ * @param {object} result
+ * @returns {{ content: Array }}
+ */
+function ok(result) {
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+}
+
+/**
+ * Wrap an error message into MCP tool error content format.
+ * @param {string} message
+ * @returns {{ content: Array, isError: true }}
+ */
+function err(message) {
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+
+/**
+ * Register all Zalo MCP tools on the server.
+ * @param {import("@modelcontextprotocol/sdk/server/mcp.js").McpServer} server
+ * @param {object} api - zca-js API instance
+ * @param {import("./message-buffer.js").MessageBuffer} buffer
+ * @param {import("./thread-filter.js").ThreadFilter} filter
+ * @param {object} config - MCP config
+ */
+export function registerTools(server, api, buffer, filter, config) {
+    const maxPerPoll = config.limits?.maxMessagesPerPoll ?? 20;
+
+    // --- zalo_get_messages ---
+    server.registerTool(
+        "zalo_get_messages",
+        {
+            title: "Get Zalo Messages",
+            description:
+                "Get messages from Zalo threads (DMs and groups). Returns buffered messages since last read. Use 'since' cursor from previous response for incremental polling.",
+            inputSchema: z.object({
+                threadId: z
+                    .string()
+                    .optional()
+                    .describe("Thread ID to read from. Omit for all watched threads."),
+                since: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .default(0)
+                    .describe("Cursor from previous read for incremental polling"),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(100)
+                    .default(maxPerPoll)
+                    .describe("Max messages to return"),
+            }),
+        },
+        async ({ threadId, since, limit }) => {
+            try {
+                const result = buffer.read(threadId, since, limit);
+                return ok(result);
+            } catch (e) {
+                console.error("[mcp-tools] zalo_get_messages error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
+    // --- zalo_send_message ---
+    server.registerTool(
+        "zalo_send_message",
+        {
+            title: "Send Zalo Message",
+            description:
+                "Send a text message to a Zalo thread (DM or group). threadType: 0=DM(User), 1=Group.",
+            inputSchema: z.object({
+                threadId: z.string().describe("Thread ID to send message to"),
+                text: z.string().min(1).describe("Message text to send"),
+                threadType: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .max(1)
+                    .default(THREAD_USER)
+                    .describe("Thread type: 0=DM(User), 1=Group"),
+            }),
+        },
+        async ({ threadId, text, threadType }) => {
+            try {
+                const result = await api.sendMessage(text, threadId, Number(threadType));
+                const messageId = result?.message?.msgId ?? result?.msgId ?? null;
+                return ok({ success: true, messageId });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_send_message error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
+    // --- zalo_list_threads ---
+    server.registerTool(
+        "zalo_list_threads",
+        {
+            title: "List Zalo Threads",
+            description:
+                "List all Zalo threads currently buffered with unread message counts. Useful for discovering active conversations.",
+            inputSchema: z.object({
+                type: z
+                    .enum(["group", "dm", "all"])
+                    .default("all")
+                    .describe("Filter by thread type: 'dm', 'group', or 'all'"),
+            }),
+        },
+        async ({ type }) => {
+            try {
+                const stats = buffer.getStats(0);
+                // Enrich each stat entry with threadType by peeking at the first buffered message.
+                // buffer._threads is a Map<threadId, { messages: Array, lastActivity: number }>
+                const enriched = stats.map((t) => {
+                    const thread = buffer._threads.get(t.threadId);
+                    const threadType = thread?.messages?.[0]?.threadType ?? "unknown";
+                    return { ...t, threadType };
+                });
+                const filtered =
+                    type === "all"
+                        ? enriched
+                        : enriched.filter((t) => t.threadType === type);
+                return ok({ threads: filtered, total: filtered.length });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_list_threads error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
+    // --- zalo_mark_read ---
+    server.registerTool(
+        "zalo_mark_read",
+        {
+            title: "Mark Zalo Messages Read",
+            description:
+                "Discard buffered messages up to and including the given cursor. Use the cursor returned by zalo_get_messages.",
+            inputSchema: z.object({
+                cursor: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .describe("Cursor value returned from a previous zalo_get_messages call"),
+            }),
+        },
+        async ({ cursor }) => {
+            try {
+                const discarded = buffer.markRead(cursor);
+                return ok({ success: true, discarded });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_mark_read error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+}

package/src/mcp/message-buffer.js

@@ -0,0 +1,119 @@
+/**
+ * Ring buffer storing messages per thread with cursor-based incremental reads.
+ * Shared by both stdio and HTTP MCP transports.
+ */
+
+export class MessageBuffer {
+    /**
+     * @param {number} maxSize - Max messages per thread before eviction
+     * @param {number} maxAge - Max message age in ms before eviction (default 2h)
+     */
+    constructor(maxSize = 500, maxAge = 2 * 60 * 60 * 1000) {
+        /** @type {Map<string, { messages: Array, lastActivity: number }>} */
+        this._threads = new Map();
+        this._maxSize = maxSize;
+        this._maxAge = maxAge;
+        this._globalCursor = 0;
+    }
+
+    /**
+     * Add message to thread buffer. Auto-evicts stale messages.
+     * @param {string} threadId
+     * @param {object} message - Normalized message object
+     */
+    push(threadId, message) {
+        if (!this._threads.has(threadId)) {
+            this._threads.set(threadId, { messages: [], lastActivity: Date.now() });
+        }
+        const thread = this._threads.get(threadId);
+        // Assign global cursor for incremental reads
+        message._cursor = ++this._globalCursor;
+        thread.messages.push(message);
+        thread.lastActivity = Date.now();
+        this._evict(threadId);
+    }
+
+    /**
+     * Read messages from a thread, optionally since a cursor.
+     * @param {string} [threadId] - If omitted, reads from all threads
+     * @param {number} [since=0] - Cursor to read from (exclusive)
+     * @param {number} [maxCount=20] - Max messages to return
+     * @returns {{ messages: Array, cursor: number, hasMore: boolean }}
+     */
+    read(threadId, since = 0, maxCount = 20) {
+        const sources = threadId
+            ? [this._threads.get(threadId)].filter(Boolean)
+            : Array.from(this._threads.values());
+
+        // Collect all messages after cursor, sorted by cursor
+        let all = [];
+        for (const thread of sources) {
+            for (const msg of thread.messages) {
+                if (msg._cursor > since) all.push(msg);
+            }
+        }
+        all.sort((a, b) => a._cursor - b._cursor);
+
+        const hasMore = all.length > maxCount;
+        const messages = all.slice(0, maxCount);
+        const cursor = messages.length > 0 ? messages[messages.length - 1]._cursor : since;
+
+        return { messages, cursor, hasMore };
+    }
+
+    /**
+     * Advance read cursor — discard messages at or before given cursor.
+     * @param {number} cursor
+     * @returns {number} Count of discarded messages
+     */
+    markRead(cursor) {
+        let discarded = 0;
+        for (const [, thread] of this._threads) {
+            const before = thread.messages.length;
+            thread.messages = thread.messages.filter((m) => m._cursor > cursor);
+            discarded += before - thread.messages.length;
+        }
+        return discarded;
+    }
+
+    /**
+     * Get stats for all threads with buffered messages.
+     * @param {number} [readCursor=0] - Messages after this cursor are "unread"
+     * @returns {Array<{ threadId: string, unread: number, total: number, lastActivity: number }>}
+     */
+    getStats(readCursor = 0) {
+        const stats = [];
+        for (const [threadId, thread] of this._threads) {
+            if (thread.messages.length === 0) continue;
+            const unread = thread.messages.filter((m) => m._cursor > readCursor).length;
+            stats.push({
+                threadId,
+                unread,
+                total: thread.messages.length,
+                lastActivity: thread.lastActivity,
+            });
+        }
+        return stats;
+    }
+
+    /**
+     * Evict messages that exceed maxSize or maxAge for a given thread.
+     * @param {string} threadId
+     */
+    _evict(threadId) {
+        const thread = this._threads.get(threadId);
+        if (!thread) return;
+
+        const now = Date.now();
+        // Remove messages older than maxAge
+        thread.messages = thread.messages.filter((m) => now - m.timestamp < this._maxAge);
+        // Trim to maxSize (keep newest)
+        if (thread.messages.length > this._maxSize) {
+            thread.messages = thread.messages.slice(thread.messages.length - this._maxSize);
+        }
+        // Clean up empty threads
+        if (thread.messages.length === 0) {
+            this._threads.delete(threadId);
+        }
+    }
+}

package/src/mcp/message-buffer.test.js

@@ -0,0 +1,282 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { MessageBuffer } from "./message-buffer.js";
+
+/** Helper: create a message with a timestamp (default = now) */
+function msg(text, timestamp = Date.now()) {
+    return { text, timestamp };
+}
+
+describe("MessageBuffer constructor", () => {
+    it("uses default maxSize=500 and maxAge=2h", () => {
+        const buf = new MessageBuffer();
+        assert.equal(buf._maxSize, 500);
+        assert.equal(buf._maxAge, 2 * 60 * 60 * 1000);
+    });
+
+    it("accepts custom maxSize and maxAge", () => {
+        const buf = new MessageBuffer(10, 5000);
+        assert.equal(buf._maxSize, 10);
+        assert.equal(buf._maxAge, 5000);
+    });
+
+    it("starts with empty threads and cursor at 0", () => {
+        const buf = new MessageBuffer();
+        assert.equal(buf._threads.size, 0);
+        assert.equal(buf._globalCursor, 0);
+    });
+});
+
+describe("MessageBuffer push + read", () => {
+    it("push stores message and read returns it", () => {
+        const buf = new MessageBuffer();
+        buf.push("thread-1", msg("hello"));
+        const { messages, cursor } = buf.read("thread-1");
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "hello");
+        assert.equal(cursor, 1);
+    });
+
+    it("multiple pushes to same thread are all returned", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        buf.push("t1", msg("c"));
+        const { messages } = buf.read("t1");
+        assert.equal(messages.length, 3);
+    });
+
+    it("assigns monotonically increasing cursors", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("x"));
+        buf.push("t1", msg("y"));
+        const { messages } = buf.read("t1");
+        assert.ok(messages[0]._cursor < messages[1]._cursor);
+    });
+
+    it("read without threadId returns messages from all threads", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t2", msg("b"));
+        const { messages } = buf.read();
+        assert.equal(messages.length, 2);
+    });
+
+    it("read from non-existent thread returns empty array", () => {
+        const buf = new MessageBuffer();
+        const { messages, cursor } = buf.read("no-such-thread");
+        assert.deepEqual(messages, []);
+        assert.equal(cursor, 0);
+    });
+});
+
+describe("MessageBuffer cursor-based incremental reads", () => {
+    it("since parameter excludes already-seen messages", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("first"));
+        const { cursor: c1 } = buf.read("t1");
+
+        buf.push("t1", msg("second"));
+        const { messages } = buf.read("t1", c1);
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "second");
+    });
+
+    it("since=cursor of last message returns empty array", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("only"));
+        const { cursor } = buf.read("t1");
+        const { messages } = buf.read("t1", cursor);
+        assert.deepEqual(messages, []);
+    });
+
+    it("respects maxCount limit and sets hasMore=true", () => {
+        const buf = new MessageBuffer();
+        for (let i = 0; i < 5; i++) buf.push("t1", msg(`m${i}`));
+        const { messages, hasMore } = buf.read("t1", 0, 3);
+        assert.equal(messages.length, 3);
+        assert.equal(hasMore, true);
+    });
+
+    it("hasMore=false when all messages fit", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        const { hasMore } = buf.read("t1", 0, 20);
+        assert.equal(hasMore, false);
+    });
+});
+
+describe("MessageBuffer markRead", () => {
+    it("discards messages at or before cursor and returns count", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        const { cursor } = buf.read("t1");
+        const discarded = buf.markRead(cursor);
+        assert.equal(discarded, 2);
+    });
+
+    it("messages after cursor are kept", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        const { cursor: c1 } = buf.read("t1");
+        buf.push("t1", msg("b"));
+
+        buf.markRead(c1);
+        const { messages } = buf.read("t1");
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "b");
+    });
+
+    it("double markRead at same cursor returns 0 on second call", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        const { cursor } = buf.read("t1");
+        buf.markRead(cursor);
+        const second = buf.markRead(cursor);
+        assert.equal(second, 0);
+    });
+
+    it("markRead across multiple threads discards from all", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t2", msg("b"));
+        const { cursor } = buf.read(); // reads all
+        const discarded = buf.markRead(cursor);
+        assert.equal(discarded, 2);
+    });
+});
+
+describe("MessageBuffer eviction by maxSize", () => {
+    it("oldest messages are evicted when maxSize exceeded", () => {
+        const buf = new MessageBuffer(3, 99999999);
+        for (let i = 1; i <= 5; i++) buf.push("t1", msg(`m${i}`));
+        const { messages } = buf.read("t1");
+        assert.equal(messages.length, 3);
+        // Newest 3 kept
+        assert.equal(messages[0].text, "m3");
+        assert.equal(messages[2].text, "m5");
+    });
+});
+
+describe("MessageBuffer eviction by maxAge", () => {
+    it("stale messages are removed after maxAge expires", async () => {
+        const buf = new MessageBuffer(500, 50); // 50ms maxAge
+        buf.push("t1", { text: "old", timestamp: Date.now() });
+
+        await new Promise((r) => setTimeout(r, 80)); // wait for expiry
+
+        // Trigger eviction by pushing another message
+        buf.push("t1", { text: "new", timestamp: Date.now() });
+
+        const { messages } = buf.read("t1");
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "new");
+    });
+
+    it("thread is removed when all messages evicted by age", async () => {
+        const buf = new MessageBuffer(500, 30); // 30ms maxAge
+        buf.push("t1", { text: "gone", timestamp: Date.now() });
+
+        await new Promise((r) => setTimeout(r, 60));
+
+        // Push to a different thread to avoid triggering eviction on t1
+        buf.push("t2", { text: "trigger", timestamp: Date.now() });
+
+        // t1 still has stale message but won't be cleaned unless _evict("t1") runs
+        // Push to t1 to trigger cleanup
+        buf.push("t1", { text: "trigger-clean", timestamp: Date.now() });
+
+        const { messages } = buf.read("t1");
+        // Only new message should remain
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "trigger-clean");
+    });
+});
+
+describe("MessageBuffer multi-thread isolation", () => {
+    it("messages in different threads are independent", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("from-t1"));
+        buf.push("t2", msg("from-t2"));
+
+        const r1 = buf.read("t1");
+        const r2 = buf.read("t2");
+
+        assert.equal(r1.messages.length, 1);
+        assert.equal(r1.messages[0].text, "from-t1");
+        assert.equal(r2.messages.length, 1);
+        assert.equal(r2.messages[0].text, "from-t2");
+    });
+
+    it("markRead on shared cursor only keeps messages after it in each thread", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("t1-a"));
+        const { cursor: midCursor } = buf.read();
+        buf.push("t2", msg("t2-b")); // cursor after midCursor
+
+        buf.markRead(midCursor);
+
+        const r1 = buf.read("t1");
+        const r2 = buf.read("t2");
+        assert.equal(r1.messages.length, 0);
+        assert.equal(r2.messages.length, 1);
+    });
+});
+
+describe("MessageBuffer getStats", () => {
+    it("returns unread/total/lastActivity per thread", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        buf.push("t2", msg("c"));
+
+        const stats = buf.getStats(0);
+        assert.equal(stats.length, 2);
+
+        const t1 = stats.find((s) => s.threadId === "t1");
+        assert.ok(t1);
+        assert.equal(t1.total, 2);
+        assert.equal(t1.unread, 2);
+        assert.ok(typeof t1.lastActivity === "number");
+    });
+
+    it("respects readCursor when computing unread count", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        const { cursor } = buf.read("t1");
+        buf.push("t1", msg("b")); // unread
+
+        const stats = buf.getStats(cursor);
+        const t1 = stats.find((s) => s.threadId === "t1");
+        assert.equal(t1.unread, 1);
+        assert.equal(t1.total, 2);
+    });
+
+    it("excludes threads with no messages", () => {
+        const buf = new MessageBuffer(500, 999999);
+        buf.push("t1", msg("a"));
+        const { cursor } = buf.read("t1");
+        buf.markRead(cursor); // discards all messages
+
+        const stats = buf.getStats(0);
+        assert.equal(stats.length, 0);
+    });
+});
+
+describe("MessageBuffer edge cases", () => {
+    it("empty read on fresh buffer returns empty array and cursor 0", () => {
+        const buf = new MessageBuffer();
+        const { messages, cursor } = buf.read("nowhere");
+        assert.deepEqual(messages, []);
+        assert.equal(cursor, 0);
+    });
+
+    it("global cursor increments across different threads", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("x"));
+        buf.push("t2", msg("y"));
+        assert.equal(buf._globalCursor, 2);
+    });
+});

package/src/mcp/notifier.js

@@ -0,0 +1,94 @@
+/**
+ * Sends notification to a configured Zalo group when DMs arrive
+ * and no MCP agent is connected. Batches messages within a cooldown window.
+ */
+
+import { parseDuration } from "./mcp-config.js";
+
+export class ZaloNotifier {
+    /**
+     * @param {object} api - zca-js API instance
+     * @param {object} config - Full MCP config (uses config.notify section)
+     * @param {boolean} config.notify.enabled
+     * @param {string|null} config.notify.thread - Group ID to send notifications to
+     * @param {string[]} config.notify.on - Event types to notify on (e.g. ["dm"])
+     * @param {string} config.notify.cooldown - Debounce window (e.g. "5m")
+     */
+    constructor(api, config) {
+        this._api = api;
+        this._enabled = config.notify?.enabled || false;
+        this._notifyThread = config.notify?.thread || null;
+        this._onTypes = new Set(config.notify?.on || ["dm"]);
+        this._cooldownMs = parseDuration(config.notify?.cooldown || "5m");
+        this._pending = []; // Messages queued during cooldown window
+        this._timer = null;
+        this._agentConnected = false;
+    }
+
+    /** Mark agent as connected/disconnected — suppresses notifications when connected */
+    setAgentConnected(connected) {
+        this._agentConnected = connected;
+    }
+
+    /**
+     * Called when a new message arrives. Queues notification if conditions are met.
+     * @param {object} message - Normalized message object
+     */
+    onMessage(message) {
+        if (!this._shouldNotify(message)) return;
+        this._pending.push(message);
+        // Start cooldown timer only once per batch window
+        if (!this._timer) {
+            this._timer = setTimeout(() => this._flush(), this._cooldownMs);
+        }
+    }
+
+    /**
+     * Determine whether this message warrants a notification.
+     * @param {object} message
+     * @returns {boolean}
+     */
+    _shouldNotify(message) {
+        if (!this._enabled || !this._notifyThread) return false;
+        if (this._agentConnected) return false;
+        return this._onTypes.has(message.threadType);
+    }
+
+    /** Flush pending notifications as a single batched message to the notify thread */
+    async _flush() {
+        this._timer = null;
+        if (this._pending.length === 0) return;
+
+        const count = this._pending.length;
+        const preview = this._pending
+            .slice(0, 3) // Show at most 3 message previews
+            .map((m) => `- ${m.senderName || m.senderId}: ${(m.text || "").slice(0, 50)}`)
+            .join("\n");
+
+        const suffix = count > 3 ? `\n...và ${count - 3} tin nhắn khác` : "";
+        const text = `🔔 ${count} tin nhắn mới trong ${this._formatWindow()}:\n${preview}${suffix}`;
+
+        try {
+            // threadType 1 = Group conversation
+            await this._api.sendMessage(text, this._notifyThread, 1);
+        } catch (err) {
+            console.error("Notifier send failed:", err.message);
+        }
+
+        this._pending = [];
+    }
+
+    /** Format cooldown duration as human-readable string (e.g. "5 phút", "1h") */
+    _formatWindow() {
+        const mins = Math.round(this._cooldownMs / 60000);
+        return mins >= 60 ? `${Math.round(mins / 60)}h` : `${mins} phút`;
+    }
+
+    /** Clean up pending timer on shutdown and attempt final flush */
+    destroy() {
+        if (this._timer) {
+            clearTimeout(this._timer);
+            this._flush();
+        }
+    }
+}