@manybot/manybot 5.7.0 → 5.9.0

package/dist/logger/logger.js

@@ -3,14 +3,34 @@ const c = {
     green: "\x1b[32m", yellow: "\x1b[33m", cyan: "\x1b[36m",
     red: "\x1b[31m", blue: "\x1b[34m",
 };
+let debugEnabled = process.argv.includes("--debug");
+let logLevel = "normal";
+export function setLogLevel(level) { logLevel = level; }
+export function getLogLevel() { return logLevel; }
 /**
  * ManyBot central logger.
  * Each method only handles output — no business logic or external I/O.
+ *
+ * `debug` is silent by default to keep production logs clean. Pass
+ * `--debug` on the command line to enable it. The check is a single
+ * `Array.includes` on argv, cheap enough to do per call and avoids
+ * requiring logger consumers to know about a global toggle.
  */
 export const logger = {
-    info: (...a) => console.log(`${c.cyan}INFO  ${c.reset}`, ...a),
-    success: (...a) => console.log(`${c.green}OK    ${c.reset}`, ...a),
+    info: (...a) => {
+        if (logLevel === "normal")
+            console.log(`${c.cyan}INFO  ${c.reset}`, ...a);
+    },
+    success: (...a) => {
+        if (logLevel !== "minimal")
+            console.log(`${c.green}OK    ${c.reset}`, ...a);
+    },
     warn: (...a) => console.log(`${c.yellow}WARN  ${c.reset}`, ...a),
     error: (...a) => console.log(`${c.red}ERROR ${c.reset}`, ...a),
-    debug: (...a) => console.log(`${c.blue}DEBUG ${c.reset}`, ...a),
+    debug: (...a) => {
+        if (debugEnabled)
+            console.log(`${c.blue}DEBUG ${c.reset}`, ...a);
+    },
 };
+export function enableDebug() { debugEnabled = true; }
+export function isDebugEnabled() { return debugEnabled; }

package/dist/logger/logger.test.js

@@ -0,0 +1,45 @@
+import test, { describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { logger, setLogLevel, getLogLevel } from "./logger.js";
+describe("logger levels", () => {
+    const originalLog = console.log;
+    let lines;
+    beforeEach(() => {
+        lines = [];
+        console.log = (...a) => { lines.push(a.join(" ")); };
+    });
+    afterEach(() => {
+        console.log = originalLog;
+        setLogLevel("normal");
+    });
+    test("defaults to normal", () => {
+        assert.equal(getLogLevel(), "normal");
+    });
+    test("normal shows info, success, warn, error", () => {
+        setLogLevel("normal");
+        logger.info("a");
+        logger.success("b");
+        logger.warn("c");
+        logger.error("d");
+        assert.equal(lines.length, 4);
+    });
+    test("clean hides info but keeps success, warn, error", () => {
+        setLogLevel("clean");
+        logger.info("a");
+        logger.success("b");
+        logger.warn("c");
+        logger.error("d");
+        assert.equal(lines.length, 3);
+        assert.ok(!lines.some(l => l.includes("a")));
+    });
+    test("minimal hides info and success, keeps warn and error", () => {
+        setLogLevel("minimal");
+        logger.info("a");
+        logger.success("b");
+        logger.warn("c");
+        logger.error("d");
+        assert.equal(lines.length, 2);
+        assert.ok(lines.some(l => l.includes("c")));
+        assert.ok(lines.some(l => l.includes("d")));
+    });
+});

package/dist/main.js

@@ -10,49 +10,20 @@ import path from "path";
 process.env.NODE_PATH = path.resolve(process.cwd(), "node_modules");
 Module._initPaths();
 import { baileysContract } from "#drivers/baileys/index.js";
-import { whatsmeowContract, startWhatsmeowSupervisor, wrapWithSupervisor } from "#drivers/whatsmeow/index.js";
-import { promptWhatsmeowInstall } from "#drivers/whatsmeow/installer.js";
 import { cleanupPlugins } from "#kernel/pluginLoader.js";
 import { stopAll as stopScheduler } from "#kernel/scheduler.js";
 import { sendAlert } from "#kernel/alerts.js";
 import { startStatusServer } from "#kernel/statusServer.js";
 import { getDriverManager } from "#kernel/driverManager.js";
-import { CONFIG, STATUS_ENABLED, STATUS_PORT } from "#config";
-import { logger } from "#logger";
+import { STATUS_ENABLED, STATUS_PORT, LOG_LEVEL } from "#config";
+import { logger, setLogLevel } from "#logger";
 import { t } from "#i18n";
+setLogLevel(LOG_LEVEL);
 let shuttingDown = false;
-// DriverManager registration: only register drivers that are enabled in
-// the config. whatsmeow.enabled = false means no gRPC
-// subprocess, no Go binary lookup, no extra work at boot — the manager
-// simply doesn't know about it and sendFallbackGuard sees a missing
-// secondary and fires send_failed_no_fallback if needed.
+// DriverManager registration: only Baileys driver now
 const driverManager = getDriverManager();
-driverManager.register(baileysContract, { isPrimary: CONFIG.drivers.primary === "baileys" });
-// Whatsmeow supervisor: spawns the Go subprocess when enabled=true,
-// owns the restart/backoff/circuit-breaker logic, and gates the
-// driver's connect()/isReady() until HealthCheck{ready:true}. When
-// enabled=false or the binary can't be located, `supervisor` is null
-// and the whatsmeow driver is simply not registered — ManyBot keeps
-// running on Baileys alone, no fallback.
-let supervisor = null;
-if (CONFIG.drivers.whatsmeow.enabled) {
-    logger.info("[driverManager] whatsmeow enabled — spawning supervisor");
-    supervisor = await startWhatsmeowSupervisor();
-    if (supervisor) {
-        const wrapped = wrapWithSupervisor(whatsmeowContract, supervisor);
-        driverManager.register(wrapped, { isPrimary: CONFIG.drivers.primary === "whatsmeow" });
-        logger.info(`[driverManager] whatsmeow registered (primary=${CONFIG.drivers.primary === "whatsmeow"})`);
-    }
-    else {
-        logger.warn("[driverManager] whatsmeow supervisor failed to start — fallback disabled");
-    }
-}
-else {
-    logger.info("[driverManager] whatsmeow disabled by config — no fallback");
-}
+driverManager.register(baileysContract, { isPrimary: true });
 const activeDriver = driverManager.active();
-const secondaryName = (activeDriver.name === "baileys" ? "whatsmeow" : "baileys");
-const secondaryDriver = driverManager.get(secondaryName);
 async function shutdown(reason, isError = false) {
     if (shuttingDown)
         return;
@@ -87,16 +58,6 @@ async function shutdown(reason, isError = false) {
     catch (err) {
         logger.error(`Error disconnecting driver: ${err.message}`);
     }
-    // Belt-and-suspenders: driverManager.shutdown() should already have
-    // disconnected the wrapped contract, which in turn calls
-    // supervisor.shutdown(). This catches the case where the supervisor
-    // was started but the driver wasn't registered (binary missing).
-    if (supervisor) {
-        try {
-            await supervisor.shutdown();
-        }
-        catch { }
-    }
     process.exit(isError ? 1 : 0);
 }
 // Global error listeners
@@ -116,11 +77,6 @@ process.on("SIGINT", () => shutdown("SIGINT"));
 // the JID to the console, to paste into CHATS in manybot.toml.
 // Does not enter the normal bot flow (plugins are not loaded).
 if (process.argv.includes("--getid")) {
-    // getId? is a Baileys-only diagnostic method. Look it
-    // up on the registered Baileys driver regardless of which one is
-    // active — --getid always uses Baileys, even in a whatsmeow-primary
-    // configuration, because it needs the diagnostic session, not the
-    // bot's normal one.
     const baileys = driverManager.get("baileys");
     const getIdFn = baileys?.getId;
     if (!getIdFn) {
@@ -134,16 +90,6 @@ if (process.argv.includes("--getid")) {
         process.exit(1);
     });
 }
-else if (process.argv.includes("--install-whatsmeow")) {
-    // Re-run the whatsmeow installer outside the normal setup flow.
-    // Useful when the initial install failed or the binary was moved.
-    promptWhatsmeowInstall()
-        .then(() => process.exit(0))
-        .catch((err) => {
-        logger.error(`--install-whatsmeow failed: ${err.message}`);
-        process.exit(1);
-    });
-}
 else {
     // Start bot
     logger.info(t("bot.initialized"));
@@ -153,23 +99,6 @@ else {
     activeDriver.connect()
         .then(() => {
         logger.success(t("bot.ready"));
-        // The secondary driver is connected and paired in the
-        // background so sendFallbackGuard can reach for it without first
-        // having to wait through a connect() round-trip when the primary
-        // fails. The secondary does NOT register `messages.upsert` handlers
-        // (no kernel code subscribes on it — only the primary path does),
-        // so connecting it does not duplicate inbound processing. A failure
-        // here is non-fatal: the primary keeps running, fallback just stays
-        // unavailable (sendFallbackGuard's `isReady()` check covers that).
-        if (secondaryDriver) {
-            logger.info(`[driverManager] connecting secondary "${secondaryName}" in background…`);
-            secondaryDriver.connect()
-                .then(() => logger.info(`[driverManager] secondary "${secondaryName}" connected — fallback available`))
-                .catch((err) => logger.warn(`[driverManager] secondary "${secondaryName}" connect failed: ${err.message} — fallback unavailable`));
-        }
-        else {
-            logger.info(`[driverManager] no secondary driver registered — running on ${activeDriver.name} only`);
-        }
     })
         .catch((err) => {
         shutdown(`Failed to connect driver: ${err.message}`, true);

package/dist/plugins/__manybot_integration__/index.js

@@ -0,0 +1,184 @@
+/**
+ * plugins/__manybot_integration__/index.ts
+ *
+ * Internal integration plugin for the WhatsApp test suite. NOT a
+ * user-facing plugin — only the test harness loads it, and only when
+ * integration mode is enabled (see `kernel/integrationMode.ts`).
+ *
+ * Responsibilities:
+ *   - Refuse to act on any chat other than the configured TEST_CHAT.
+ *     Anything arriving in another chat is dropped with a warning,
+ *     never replied to.
+ *   - Expose a small public API the test harness drives:
+ *       - `testChat`        — the JID we will respond in.
+ *       - `isTestChat(jid)` — true iff `jid` matches the test chat.
+ *       - `waitForMarker(marker, timeoutMs)`
+ *                            — resolves with the message id of the
+ *                              first inbound message in the test chat
+ *                              whose body starts with `marker`. Used
+ *                              by tests to observe real round-trips
+ *                              (e.g. "send a message, wait until the
+ *                              contact echoes it back").
+ *   - Keep a bounded ring buffer of recent message bodies in the
+ *     test chat so tests can also assert on what was sent earlier
+ *     in the same run.
+ *
+ * This plugin is intentionally minimal — it does NOT register user
+ * commands, does NOT participate in the `commands.yaml` registry,
+ * and shuts down cleanly via the normal plugin cleanup path
+ * (cleanupPluginEvents is driven by the kernel, not by us).
+ *
+ * Imports are restricted to types and the `events` module from the
+ * kernel — never a driver package, never the raw socket. The
+ * `ctx.wa.contract` neutral access is the only driver surface used
+ * (and only for `me()` and any helper the test harness invokes).
+ */
+import { EventEmitter } from "node:events";
+import { logger } from "#logger";
+import { INTEGRATION_PLUGIN_NAME } from "#kernel/integrationMode.js";
+const RING_BUFFER_LIMIT = 50;
+const DEFAULT_TIMEOUT_MS = 30_000;
+let configuredTestChat = null;
+const recent = new Map();
+let recentSeq = 0;
+const waiter = new EventEmitter();
+function pushRecent(body, from) {
+    const id = ++recentSeq;
+    recent.set(id, { body, from, ts: Date.now() });
+    // Cap the ring buffer; eviction keeps insertion order.
+    while (recent.size > RING_BUFFER_LIMIT) {
+        const firstKey = recent.keys().next().value;
+        if (firstKey === undefined)
+            break;
+        recent.delete(firstKey);
+    }
+}
+function findByMarker(marker) {
+    for (const entry of recent.values()) {
+        if (entry.body.startsWith(marker))
+            return entry;
+    }
+    return null;
+}
+export const api = {
+    testChat: "", // populated in setup()
+    isTestChat(jid) {
+        if (!jid)
+            return false;
+        if (!configuredTestChat)
+            return false;
+        return jid === configuredTestChat;
+    },
+    async waitForMarker(marker, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const existing = findByMarker(marker);
+        if (existing) {
+            // Return a synthetic id; tests that need the real id should
+            // observe the `messages.upsert` payload directly.
+            return `recent:${existing.ts}`;
+        }
+        return new Promise((resolve, reject) => {
+            const onHit = (entry) => {
+                if (!entry.body.startsWith(marker))
+                    return;
+                waiter.off("hit", onHit);
+                clearTimeout(timer);
+                resolve(`recent:${entry.ts}`);
+            };
+            const timer = setTimeout(() => {
+                waiter.off("hit", onHit);
+                reject(new Error(`[${INTEGRATION_PLUGIN_NAME}] waitForMarker("${marker}") timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            waiter.on("hit", onHit);
+        });
+    },
+    recentBodies() {
+        return [...recent.values()].map((e) => e.body);
+    },
+};
+/**
+ * setup() runs once after the bot connects. We capture the test
+ * chat here so the runtime API can refuse any other chat.
+ */
+export async function setup(ctx) {
+    // The integration chat is decided by the harness BEFORE
+    // setupPlugins() is called. Historically the harness set
+    // MANYBOT_TEST_CHAT, but users often set TEST_CHAT (per docs) —
+    // either as an env var or as a `TEST_CHAT` key in manybot.toml.
+    //
+    // `kernel/integrationMode.ts`'s own gate (`getIntegrationModeStatus`,
+    // which is what decided integration mode was "ready" and logged as
+    // much before this plugin's setup() ever ran) resolves TEST_CHAT via
+    // `getTestConfig()` — env var first, then manybot.toml. Reading
+    // straight off `process.env.TEST_CHAT` here (as this used to)
+    // silently diverged from that: the gate would report ready off a
+    // toml-only value while this threw "no TEST_CHAT set", because it
+    // never looked at the toml. Importing normalizeTestChat/getTestConfig
+    // here (rather than at module top) keeps the module load cheap when
+    // the plugin isn't used in production code paths.
+    //
+    // MANYBOT_TEST_CHAT remains a preferred override on top of that, for
+    // callers that want to point this specific plugin at a different
+    // chat than the gate's own resolution.
+    const { getTestConfig, normalizeTestChat } = await import("#kernel/testConfig.js");
+    let normalized;
+    const overrideEnv = process.env.MANYBOT_TEST_CHAT;
+    if (overrideEnv) {
+        try {
+            normalized = normalizeTestChat(overrideEnv);
+        }
+        catch (e) {
+            throw new Error(`[${INTEGRATION_PLUGIN_NAME}] invalid MANYBOT_TEST_CHAT provided: ${e.message}`);
+        }
+    }
+    else {
+        const cfg = await getTestConfig();
+        if (!cfg.chat) {
+            throw new Error(`[${INTEGRATION_PLUGIN_NAME}] setup() called without MANYBOT_TEST_CHAT or TEST_CHAT — ` +
+                `set MANYBOT_TEST_CHAT (preferred), or TEST_CHAT (env var or manybot.toml), before setupPlugins().`);
+        }
+        normalized = cfg.chat;
+    }
+    configuredTestChat = normalized;
+    api.testChat = normalized;
+    // Subscribe to the relevant events so waitForMarker works
+    // without requiring a polling loop. `messages.upsert` is the
+    // single source of truth for any new incoming message; `on()`
+    // returns an unsubscribe handle, but cleanupPluginEvents takes
+    // care of it for us.
+    ctx.events.on("messages.upsert", (payload) => {
+        const p = payload;
+        const messages = p.messages ?? [];
+        for (const m of messages) {
+            if (!m.chatId || m.chatId !== configuredTestChat)
+                continue;
+            const body = m.body ?? "";
+            const from = m.from ?? "";
+            pushRecent(body, from);
+            waiter.emit("hit", { body, from, ts: Date.now() });
+        }
+    });
+    logger.info(`[${INTEGRATION_PLUGIN_NAME}] loaded — locked to test chat ${configuredTestChat}`);
+    // ctx reserved for future use (e.g. registering a scheduler)
+    return void ctx;
+}
+/**
+ * default(ctx) runs on every inbound message. We are deliberately
+ * quiet outside the test chat so a stray message in a production
+ * chat never gets a reply from the test plugin; we never throw,
+ * because throwing would propagate up to messageHandler and
+ * potentially break unrelated plugins.
+ */
+export default async function handle(ctx) {
+    if (!configuredTestChat) {
+        logger.warn(`[${INTEGRATION_PLUGIN_NAME}] default() called before setup() — ignoring`);
+        return;
+    }
+    if (ctx.chat.id !== configuredTestChat) {
+        logger.warn(`[${INTEGRATION_PLUGIN_NAME}] ignoring message from non-test chat ${ctx.chat.id}`);
+        return;
+    }
+    // No automatic reply: the test harness drives every send through
+    // `ctx.send.*` or `contract.send*` and waits on `waitForMarker`
+    // for the round-trip. Keeping the plugin passive here is what
+    // makes the suite easy to reason about.
+}

package/dist/plugins/__manybot_integration__/index.test.js

@@ -0,0 +1,218 @@
+import assert from "node:assert/strict";
+import { after, beforeEach, describe, test } from "node:test";
+import { _resetTestConfigForTests } from "#kernel/testConfig.js";
+const integrationPluginUrl = new URL("../../plugins/__manybot_integration__/index.ts", import.meta.url).href;
+describe("plugins/__manybot_integration__", () => {
+    let mod;
+    beforeEach(async () => {
+        // Use a cache-busting query so each test gets a fresh module
+        // (and therefore a fresh ring buffer + EventEmitter).
+        mod = await import(`${integrationPluginUrl}?t=${Date.now()}-${Math.random()}`);
+        // setup() now falls back to kernel/testConfig.js's getTestConfig()
+        // for the TEST_CHAT-only case (see setup()'s comment), and that
+        // module caches its result in-process after the first read. Tests
+        // in this file mutate TEST_CHAT/MANYBOT_TEST_CHAT freely between
+        // cases, so the cache must be dropped before every test or a
+        // stale resolution from an earlier test leaks in.
+        _resetTestConfigForTests();
+    });
+    after(async () => {
+        // Best-effort cleanup; nothing in the plugin subscribes to
+        // process-level resources, but we re-clear the configured
+        // chat (and the testConfig cache it now feeds through) so a
+        // subsequent suite (e.g. loadIntegrationPlugin.test.ts) starts
+        // blank.
+        process.env.MANYBOT_TEST_CHAT = "";
+        delete process.env.TEST_CHAT;
+        _resetTestConfigForTests();
+    });
+    test("exports default, setup, and api", () => {
+        assert.equal(typeof mod.default, "function");
+        assert.equal(typeof mod.setup, "function");
+        assert.ok(mod.api);
+    });
+    test("api.isTestChat is false before setup() is called", () => {
+        assert.equal(mod.api.isTestChat("5516999999999@s.whatsapp.net"), false);
+        assert.equal(mod.api.isTestChat(null), false);
+    });
+    test("api.recentBodies() starts empty", () => {
+        assert.deepEqual(mod.api.recentBodies(), []);
+    });
+    // Note: the previous "setup() throws when MANYBOT_TEST_CHAT is unset" test
+    // was removed when the resolution path was widened to env-or-toml (see the
+    // `setup() agrees with integrationMode's own gate` regression test below).
+    // With toml resolution in scope, "unset" can only be asserted by also
+    // clearing the toml — that's testConfig.test.ts's territory, not this
+    // plugin's. The plugin-specific throw cases (invalid format, missing
+    // MANYBOT_TEST_CHAT override while TEST_CHAT is empty, etc.) are covered
+    // by the remaining tests below.
+    test("setup() captures the test chat and isTestChat accepts it", async () => {
+        process.env.MANYBOT_TEST_CHAT = "5516999999999@s.whatsapp.net";
+        const { ctx } = makeSetupCtx();
+        await mod.setup(ctx);
+        assert.equal(mod.api.testChat, "5516999999999@s.whatsapp.net");
+        assert.equal(mod.api.isTestChat("5516999999999@s.whatsapp.net"), true);
+        assert.equal(mod.api.isTestChat("5516000000000@s.whatsapp.net"), false);
+    });
+    test("default() refuses to act on a non-test chat", async () => {
+        process.env.MANYBOT_TEST_CHAT = "5516999999999@s.whatsapp.net";
+        const { ctx: setupCtx } = makeSetupCtx();
+        await mod.setup(setupCtx);
+        const { ctx, replyCalls } = makeMessageCtx("120363012345678@g.us");
+        // Should not throw and should not produce a reply.
+        await mod.default(ctx);
+        assert.equal(replyCalls.length, 0);
+    });
+    test("default() does not act even in the test chat (plugin is passive)", async () => {
+        process.env.MANYBOT_TEST_CHAT = "5516999999999@s.whatsapp.net";
+        const { ctx: setupCtx } = makeSetupCtx();
+        await mod.setup(setupCtx);
+        const { ctx, replyCalls } = makeMessageCtx("5516999999999@s.whatsapp.net");
+        await mod.default(ctx);
+        assert.equal(replyCalls.length, 0);
+    });
+    test("default() before setup() is a no-op, not a crash", async () => {
+        delete process.env.MANYBOT_TEST_CHAT;
+        const { ctx, replyCalls } = makeMessageCtx("5516999999999@s.whatsapp.net");
+        await mod.default(ctx); // must not throw
+        assert.equal(replyCalls.length, 0);
+    });
+    test("waitForMarker resolves when a matching messages.upsert is delivered via setup()", async () => {
+        process.env.MANYBOT_TEST_CHAT = "5516999999999@s.whatsapp.net";
+        const { ctx, handlers } = makeSetupCtx();
+        await mod.setup(ctx);
+        // Fire the wait first, then deliver the event.
+        const pending = mod.api.waitForMarker("PING:", 1000);
+        const handlerList = handlers.get("messages.upsert");
+        assert.ok(handlerList && handlerList.length > 0, "setup() must register a messages.upsert handler");
+        handlerList[0]({
+            messages: [{ chatId: "5516999999999@s.whatsapp.net", body: "PING:hello", from: "5516000000000@s.whatsapp.net" }],
+        });
+        const id = await pending;
+        assert.match(id, /^recent:\d+$/);
+        assert.ok(mod.api.recentBodies().some((b) => b === "PING:hello"));
+    });
+    test("waitForMarker ignores messages from a different chat", async () => {
+        process.env.MANYBOT_TEST_CHAT = "5516999999999@s.whatsapp.net";
+        const { ctx, handlers } = makeSetupCtx();
+        await mod.setup(ctx);
+        const pending = mod.api.waitForMarker("PING:", 200);
+        const handlerList = handlers.get("messages.upsert");
+        assert.ok(handlerList);
+        // Send from a different chat — must not resolve the wait.
+        handlerList[0]({
+            messages: [{ chatId: "120363012345678@g.us", body: "PING:should-not-match", from: "120363012345678@g.us" }],
+        });
+        await assert.rejects(pending, /timed out/);
+    });
+    test("waitForMarker resolves immediately when a matching message is already in the buffer", async () => {
+        process.env.MANYBOT_TEST_CHAT = "5516999999999@s.whatsapp.net";
+        const { ctx, handlers } = makeSetupCtx();
+        await mod.setup(ctx);
+        const handlerList = handlers.get("messages.upsert");
+        assert.ok(handlerList);
+        handlerList[0]({
+            messages: [{ chatId: "5516999999999@s.whatsapp.net", body: "PING:already-here", from: "5516000000000@s.whatsapp.net" }],
+        });
+        const id = await mod.api.waitForMarker("PING:", 200);
+        assert.match(id, /^recent:\d+$/);
+    });
+    test("waitForMarker does not match a body that does not start with the marker", async () => {
+        process.env.MANYBOT_TEST_CHAT = "5516999999999@s.whatsapp.net";
+        const { ctx, handlers } = makeSetupCtx();
+        await mod.setup(ctx);
+        const handlerList = handlers.get("messages.upsert");
+        assert.ok(handlerList);
+        handlerList[0]({
+            messages: [{ chatId: "5516999999999@s.whatsapp.net", body: "PONG:no-match", from: "5516000000000@s.whatsapp.net" }],
+        });
+        await assert.rejects(mod.api.waitForMarker("PING:", 150), /timed out/);
+    });
+    test("setup() respects TEST_CHAT env var when MANYBOT_TEST_CHAT is unset", async () => {
+        delete process.env.MANYBOT_TEST_CHAT;
+        process.env.TEST_CHAT = "5516999998888@s.whatsapp.net";
+        const { ctx } = makeSetupCtx();
+        await mod.setup(ctx);
+        assert.equal(mod.api.testChat, "5516999998888@s.whatsapp.net");
+        assert.equal(mod.api.isTestChat("5516999998888@s.whatsapp.net"), true);
+    });
+    test("setup() agrees with integrationMode's own gate (both resolve TEST_CHAT via getTestConfig)", async () => {
+        // Regression test: setup() used to read process.env.TEST_CHAT
+        // directly, which diverged from kernel/integrationMode.ts's gate
+        // (getIntegrationModeStatus -> getTestConfig, env-or-toml). That
+        // let the gate report "ready" off a value setup() couldn't see —
+        // this pins the two to the same resolution instead.
+        delete process.env.MANYBOT_TEST_CHAT;
+        process.env.TEST_CHAT = "5516999997777@s.whatsapp.net";
+        const { getTestConfig } = await import("#kernel/testConfig.js");
+        const { getIntegrationModeStatus } = await import("#kernel/integrationMode.js");
+        _resetTestConfigForTests();
+        const gateStatus = await getIntegrationModeStatus();
+        const { ctx } = makeSetupCtx();
+        await mod.setup(ctx);
+        assert.equal(gateStatus.chat, mod.api.testChat, "gate and setup() must resolve the same chat");
+        assert.equal(mod.api.testChat, "5516999997777@s.whatsapp.net");
+        // Sanity: both are backed by the same cached getTestConfig() call.
+        const cfg = await getTestConfig();
+        assert.equal(cfg.chat, mod.api.testChat);
+    });
+    test("setup() throws when given an invalid test chat format", async () => {
+        process.env.MANYBOT_TEST_CHAT = "not_a_valid_jid";
+        const { ctx } = makeSetupCtx();
+        await assert.rejects(mod.setup(ctx), /invalid MANYBOT_TEST_CHAT provided/);
+    });
+    test("ring buffer caps at 50 messages and evicts oldest", async () => {
+        process.env.MANYBOT_TEST_CHAT = "5516999999999@s.whatsapp.net";
+        const { ctx, handlers } = makeSetupCtx();
+        await mod.setup(ctx);
+        const handlerList = handlers.get("messages.upsert");
+        assert.ok(handlerList);
+        // Push 55 messages
+        const messages = Array.from({ length: 55 }, (_, i) => ({
+            chatId: "5516999999999@s.whatsapp.net",
+            body: `MSG_${i}`,
+            from: "5516000000000@s.whatsapp.net",
+        }));
+        handlerList[0]({ messages });
+        const recent = mod.api.recentBodies();
+        assert.equal(recent.length, 50);
+        // Oldest 5 (MSG_0 to MSG_4) should have been evicted
+        assert.equal(recent[0], "MSG_5");
+        assert.equal(recent.at(-1), "MSG_54");
+    });
+});
+function makeSetupCtx() {
+    const handlers = new Map();
+    const mock = {
+        handlers,
+        events: {
+            on(event, handler) {
+                const list = handlers.get(event) ?? [];
+                list.push(handler);
+                handlers.set(event, list);
+                return () => {
+                    const arr = handlers.get(event) ?? [];
+                    const idx = arr.indexOf(handler);
+                    if (idx >= 0)
+                        arr.splice(idx, 1);
+                };
+            },
+        },
+    };
+    // The plugin only touches `events` in setup(); the rest of the
+    // SetupContext surface is unused, so we type-cast through `unknown`
+    // rather than build a full fake.
+    return { ctx: mock, handlers };
+}
+function makeMessageCtx(chatId) {
+    const mock = {
+        chat: {
+            id: chatId,
+            name: "test",
+            isGroup: chatId.endsWith("@g.us"),
+        },
+        msg: { id: "msg-1", body: "hello" },
+        replyCalls: [],
+    };
+    return { ctx: mock, replyCalls: mock.replyCalls };
+}