@manybot/manybot 5.7.0 → 5.8.0

package/dist/drivers/baileysAdapter.test.js

@@ -0,0 +1,281 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import test from "node:test";
+import { createStore } from "#client/store.js";
+import { createBaileysAdapter } from "#drivers/baileys/adapter.js";
+test("Baileys sends messages with the chat's disappearing-message timer", async () => {
+    const store = createStore();
+    const jid = "chat@s.whatsapp.net";
+    store.setChatEphemeralExpiration(jid, 86400);
+    store.messages.set(jid, new Map([["quoted", {
+                key: { id: "quoted", remoteJid: jid, fromMe: false },
+                message: { conversation: "original" },
+            }]]));
+    const calls = [];
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        sendMessage: async (...args) => {
+            calls.push(args);
+            return { key: { id: `sent-${calls.length}`, remoteJid: args[0] } };
+        },
+        groupMetadata: async () => ({ subject: "Group", participants: [], ephemeralDuration: 604800 }),
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const quoted = { id: "quoted", remoteJid: jid, fromMe: false };
+    await contract.sendText(jid, "text", { quoted });
+    await contract.sendImage(jid, Buffer.from("image"));
+    await contract.sendVideo(jid, Buffer.from("video"));
+    await contract.sendAudio(jid, Buffer.from("audio"));
+    await contract.sendSticker(jid, Buffer.from("sticker"));
+    await contract.sendDocument(jid, Buffer.from("document"), "file.txt", "text/plain");
+    await contract.sendPoll(jid, { name: "Poll", values: ["one"] });
+    for (const call of calls) {
+        assert.equal(call[2]?.ephemeralExpiration, 86400);
+    }
+    assert.ok((calls[0]?.[2]).quoted, "quoted and ephemeral options are merged");
+    await contract.react(jid, quoted, "👍");
+    assert.equal(calls.at(-1)?.length, 2, "reactions do not receive ephemeral send options");
+    await contract.groupMetadata("group@g.us");
+    await contract.sendText("group@g.us", "group text");
+    assert.equal((calls.at(-1)?.[2]).ephemeralExpiration, 604800);
+});
+test("Baileys adapter getBusinessProfile handles success and failure", async () => {
+    const store = createStore();
+    const jid = "12345678@s.whatsapp.net";
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        getBusinessProfile: async () => ({ name: "Test Corp", id: "12345678" }),
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const result = await contract.getBusinessProfile(jid);
+    assert.deepStrictEqual(result, { name: "Test Corp", id: "12345678" });
+    const sockFail = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        getBusinessProfile: async () => { throw new Error("API error"); },
+    };
+    const { contract: contractFail } = createBaileysAdapter({ sock: sockFail, store });
+    const resultFail = await contractFail.getBusinessProfile(jid);
+    assert.strictEqual(resultFail, null);
+});
+test("Baileys adapter profilePictureUrl retrieves URL and handles error", async () => {
+    const store = createStore();
+    const jid = "12345678@s.whatsapp.net";
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        profilePictureUrl: async () => "https://example.com/profile.jpg",
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const result = await contract.profilePictureUrl(jid);
+    assert.strictEqual(result, "https://example.com/profile.jpg");
+    const sockFail = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        profilePictureUrl: async () => { throw new Error("API error"); },
+    };
+    const { contract: contractFail } = createBaileysAdapter({ sock: sockFail, store });
+    const resultFail = await contractFail.profilePictureUrl(jid);
+    assert.strictEqual(resultFail, null);
+});
+test("Baileys adapter fetchStatus retrieves status and handles error", async () => {
+    const store = createStore();
+    const jid = "12345678@s.whatsapp.net";
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        fetchStatus: async () => [{ id: jid, status: { status: "available" } }],
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const result = await contract.fetchStatus(jid);
+    assert.strictEqual(result, "available");
+    const sockNoArray = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        fetchStatus: async () => ({ status: "away" }),
+    };
+    const { contract: contractNoArray } = createBaileysAdapter({ sock: sockNoArray, store });
+    const resultNoArray = await contractNoArray.fetchStatus(jid);
+    assert.strictEqual(resultNoArray, "away");
+    const sockFail = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        fetchStatus: async () => { throw new Error("API error"); },
+    };
+    const { contract: contractFail } = createBaileysAdapter({ sock: sockFail, store });
+    const resultFail = await contractFail.fetchStatus(jid);
+    assert.strictEqual(resultFail, null);
+});
+test("Baileys adapter updateBlockStatus calls the underlying method", async () => {
+    const store = createStore();
+    const jid = "12345678@s.whatsapp.net";
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        updateBlockStatus: async () => { },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    await contract.updateBlockStatus(jid, "block");
+    assert.ok(true, "updateBlockStatus did not throw");
+    await contract.updateBlockStatus(jid, "unblock");
+    assert.ok(true, "updateBlockStatus remove did not throw");
+});
+test("Baileys adapter addOrEditContact calls the underlying method", async () => {
+    const store = createStore();
+    const jid = "12345678@s.whatsapp.net";
+    const info = { fullName: "Test User", firstName: "Test", saveOnPrimaryAddressbook: true };
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        addOrEditContact: async () => { },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    await contract.addOrEditContact(jid, info);
+    assert.ok(true, "addOrEditContact did not throw");
+    await contract.addOrEditContact(jid, { fullName: "Another User" });
+    assert.ok(true, "addOrEditContact second call did not throw");
+});
+test("Baileys adapter removeContact calls the underlying method", async () => {
+    const store = createStore();
+    const jid = "12345678@s.whatsapp.net";
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        removeContact: async () => { },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    await contract.removeContact(jid);
+    assert.ok(true, "removeContact did not throw");
+});
+test("Baileys adapter groupParticipantsUpdate calls the underlying method", async () => {
+    const store = createStore();
+    const jid = "group@g.us";
+    const users = ["user1@s.whatsapp.net", "user2@s.whatsapp.net"];
+    const action = "add";
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        groupParticipantsUpdate: async () => [{ status: "success" }],
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const result = await contract.groupParticipantsUpdate(jid, users, action);
+    assert.deepStrictEqual(result, [{ status: "success" }]);
+    await contract.groupParticipantsUpdate(jid, ["user3@s.whatsapp.net"], "remove");
+    assert.ok(true, "groupParticipantsUpdate remove did not throw");
+});
+test("Baileys adapter groupUpdateSubject and groupUpdateDescription call underlying methods", async () => {
+    const store = createStore();
+    const jid = "group@g.us";
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        groupUpdateSubject: async () => { },
+        groupUpdateDescription: async () => { },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    await contract.groupUpdateSubject(jid, "New Subject");
+    assert.ok(true, "groupUpdateSubject did not throw");
+    await contract.groupUpdateDescription(jid, "New Description");
+    assert.ok(true, "groupUpdateDescription did not throw");
+});
+test("Baileys adapter groupInviteCode and groupRevokeInvite call underlying methods", async () => {
+    const store = createStore();
+    const jid = "group@g.us";
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        groupInviteCode: async () => "https://chat.whatsapp.com/AAAA",
+        groupRevokeInvite: async () => { },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const code = await contract.groupInviteCode(jid);
+    assert.strictEqual(code, "https://chat.whatsapp.com/AAAA");
+    await contract.groupRevokeInvite(jid);
+    assert.ok(true, "groupRevokeInvite did not throw");
+});
+test("Baileys adapter updateProfilePicture, updateProfileName, updateProfileStatus call underlying methods", async () => {
+    const store = createStore();
+    const buffer = Buffer.from("fake-image-data");
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+        updateProfilePicture: async () => { },
+        updateProfileName: async () => { },
+        updateProfileStatus: async () => { },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    await contract.updateProfilePicture("12345678@s.whatsapp.net", buffer);
+    assert.ok(true, "updateProfilePicture did not throw");
+    await contract.updateProfileName("New Name");
+    assert.ok(true, "updateProfileName did not throw");
+    await contract.updateProfileStatus("Available");
+    assert.ok(true, "updateProfileStatus did not throw");
+});
+test("Baileys adapter me returns user info", async () => {
+    const store = createStore();
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net", lid: "12345678@lid" },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const me = await contract.me();
+    assert.strictEqual(me.id, "bot@s.whatsapp.net");
+    assert.strictEqual(me.lid, "12345678@lid");
+});
+test("Baileys adapter getHistory returns messages from store", async () => {
+    const store = createStore();
+    const jid = "12345678@s.whatsapp.net";
+    store.messages.set(jid, new Map([
+        ["msg1", { key: { id: "msg1", remoteJid: jid, fromMe: false }, message: { conversation: "hello" } }],
+        ["msg2", { key: { id: "msg2", remoteJid: jid, fromMe: true }, message: { conversation: "world" } }],
+    ]));
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const history = await contract.getHistory?.(jid, { limit: 2 });
+    assert.strictEqual(history?.length, 2);
+    assert.ok(history?.some((m) => m.body === "hello"));
+    assert.ok(history?.some((m) => m.body === "world"));
+});
+test("Baileys adapter downloadMedia returns null when no raw message", async () => {
+    const store = createStore();
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const result = await contract.downloadMedia({ chatId: "123", id: "msg1" }, {});
+    assert.strictEqual(result, null);
+});
+test("Baileys adapter decryptPollVote returns null when no vote data", async () => {
+    const store = createStore();
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const result = await contract.decryptPollVote?.({
+        voteKey: { remoteJid: "123", id: "msg1" },
+        pollKey: { remoteJid: "123", id: "msg1" },
+        pollEncKey: Buffer.alloc(0),
+    });
+    assert.strictEqual(result, null);
+});
+test("Baileys adapter aggregatePollVotes returns empty array when no poll data", async () => {
+    const store = createStore();
+    const sock = {
+        ev: new EventEmitter(),
+        user: { id: "bot@s.whatsapp.net" },
+    };
+    const { contract } = createBaileysAdapter({ sock, store });
+    const result = contract.aggregatePollVotes?.({
+        pollKey: { remoteJid: "123", id: "msg1" },
+        selfJid: undefined,
+        votes: [],
+    });
+    assert.deepStrictEqual(result, []);
+});

package/dist/drivers/jid.test.js

@@ -0,0 +1,40 @@
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { normalizeJid, denormalizeJid, toWireJid } from "#drivers/jid.js";
+describe("drivers/jid", () => {
+    describe("normalizeJid", () => {
+        test("handles empty string or nullish input", () => {
+            assert.equal(normalizeJid(""), "");
+        });
+        test("converts @s.whatsapp.net to @c.us", () => {
+            assert.equal(normalizeJid("5511999999999@s.whatsapp.net"), "5511999999999@c.us");
+        });
+        test("removes device suffix e.g. :12@", () => {
+            assert.equal(normalizeJid("5511999999999:12@s.whatsapp.net"), "5511999999999@c.us");
+        });
+        test("leaves group @g.us untouched", () => {
+            assert.equal(normalizeJid("12036301234567890@g.us"), "12036301234567890@g.us");
+        });
+    });
+    describe("denormalizeJid", () => {
+        test("converts @c.us to @s.whatsapp.net", () => {
+            assert.equal(denormalizeJid("5511999999999@c.us"), "5511999999999@s.whatsapp.net");
+        });
+        test("leaves already wire or non-c.us JIDs untouched", () => {
+            assert.equal(denormalizeJid("12036301234567890@g.us"), "12036301234567890@g.us");
+        });
+    });
+    describe("toWireJid", () => {
+        test("returns wire format for @s.whatsapp.net, @lid, @g.us untouched", () => {
+            assert.equal(toWireJid("5511999999999@s.whatsapp.net"), "5511999999999@s.whatsapp.net");
+            assert.equal(toWireJid("12345@lid"), "12345@lid");
+            assert.equal(toWireJid("12036301234567890@g.us"), "12036301234567890@g.us");
+        });
+        test("converts @c.us JID to @s.whatsapp.net", () => {
+            assert.equal(toWireJid("5511999999999@c.us"), "5511999999999@s.whatsapp.net");
+        });
+        test("converts plain phone number / digits to @s.whatsapp.net", () => {
+            assert.equal(toWireJid("+55 (11) 99999-9999"), "5511999999999@s.whatsapp.net");
+        });
+    });
+});

package/dist/drivers/types.js

@@ -2,11 +2,11 @@
  * src/drivers/types.ts
  *
  * Driver-neutral envelope types shared by every WhatsApp driver
- * implementation (Baileys today, whatsmeow in a later phase). The
- * full driver surface (send, react, presence, contacts, groups,
- * profile, media) is declared as `WaContract` in `#kernel/waContract.js`
- * — every driver implements it. This module holds only the message
- * shapes that flow across the driver boundary.
+ * implementation (Baileys today). The full driver surface (send, react,
+ * presence, contacts, groups, profile, media) is declared as
+ * `WaContract` in `#kernel/waContract.js` — every driver implements it.
+ * This module holds only the message shapes that flow across the driver
+ * boundary.
  *
  * Plugins depend on these types through the `WaContract` re-exports,
  * never on a specific driver's Baileys/grpc types.

package/dist/i18n/index.js

@@ -125,11 +125,24 @@ function interpolate(str, context = {}) {
 }
 export function t(key, context = {}) {
     ensureLoaded();
+    return translate(currentTranslations, fallbackTranslations, key, context);
+}
+/**
+ * Translates a key for an explicit language. This is useful for rendered
+ * content that accepts a language override, such as the command menu.
+ */
+export function tFor(lang, key, context = {}) {
+    ensureLoaded();
+    const targetLang = lang?.trim().toLowerCase() || currentLang || DEFAULT_LANG;
+    const targetTranslations = loadLocale(targetLang) || fallbackTranslations;
+    return translate(targetTranslations, fallbackTranslations, key, context);
+}
+function translate(targetTranslations, englishTranslations, key, context) {
     // Try current language first
-    let value = getNestedValue(currentTranslations, key);
+    let value = getNestedValue(targetTranslations, key);
     // Fallback to English if not found
     if (value === undefined) {
-        value = getNestedValue(fallbackTranslations, key);
+        value = getNestedValue(englishTranslations, key);
     }
     // If still not found, return the key
     if (value === undefined) {

package/dist/kernel/activeDriverSend.js

@@ -0,0 +1,21 @@
+/**
+ * activeDriverSend.ts
+ *
+ * Driver-neutral send helper. Ensures rate-limiting and throttling
+ * are applied to all outbound text sends from plugins, then sends
+ * through whichever single driver is currently active in the
+ * DriverManager. There is no fallback between drivers — driver
+ * selection is mutually exclusive and decided once at boot (see
+ * main.ts / driverManager.ts).
+ */
+import { waitForSendSlot } from "./sendGuard.js";
+import { getDriverManager } from "./driverManager.js";
+/**
+ * Send text using the active driver, respecting the rate-limiting send guard.
+ */
+export async function sendActiveDriverText(jid, text, opts = {}) {
+    const dm = getDriverManager();
+    const driver = dm.active();
+    await waitForSendSlot(jid, { cooldown: true, jitter: true });
+    return await driver.sendText(jid, text, opts);
+}

package/dist/kernel/activeDriverSend.test.js

@@ -0,0 +1,89 @@
+import test, { describe, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { sendActiveDriverText } from "#kernel/activeDriverSend.js";
+import { getDriverManager, _resetDriverManagerForTests } from "#kernel/driverManager.js";
+function createMockDriver(name, ready = true, failsSend = false) {
+    const mockRef = (id) => ({ id, chatId: "123@c.us", timestamp: Date.now() });
+    return {
+        name,
+        isReady: () => ready,
+        sendText: async (jid, text) => {
+            if (failsSend)
+                throw new Error(`${name} sendText failed`);
+            return mockRef(`msg_${name}`);
+        },
+        connect: async () => { },
+        disconnect: async () => { },
+        me: () => ({ id: "123@c.us" }),
+        sendImage: async () => mockRef("image"),
+        sendVideo: async () => mockRef("image"),
+        sendAudio: async () => mockRef("image"),
+        sendDocument: async () => mockRef("image"),
+        sendSticker: async () => mockRef("image"),
+        sendLocation: async () => mockRef("loc"),
+        sendContact: async () => mockRef("contact"),
+        sendReaction: async () => { },
+        sendPoll: async () => mockRef("poll"),
+        react: async () => { },
+        deleteMessage: async () => { },
+        editMessage: async () => { },
+        sendPresenceUpdate: async () => { },
+        readMessages: async () => { },
+        onWhatsApp: async () => null,
+        getBusinessProfile: async () => null,
+        profilePictureUrl: async () => null,
+        fetchStatus: async () => null,
+        updateBlockStatus: async () => { },
+        addOrEditContact: async () => { },
+        removeContact: async () => { },
+        groupMetadata: async () => ({ subject: "Test Group", participants: [] }),
+        groupParticipantsUpdate: async () => [],
+        groupUpdateSubject: async () => { },
+        groupUpdateDescription: async () => { },
+        groupInviteCode: async () => "",
+        groupRevokeInvite: async () => "",
+        updateProfilePicture: async () => { },
+        updateProfileName: async () => { },
+        updateProfileStatus: async () => { },
+        downloadMedia: async () => null,
+        on: () => () => { },
+    };
+}
+describe("kernel/activeDriverSend", () => {
+    beforeEach(() => {
+        _resetDriverManagerForTests();
+    });
+    test("delivers text via the active driver when healthy", async () => {
+        const dm = getDriverManager();
+        const driver = createMockDriver("baileys");
+        dm.register(driver, { isPrimary: true });
+        const ref = await sendActiveDriverText("5511999999999@c.us", "hello");
+        assert.equal(ref.id, "msg_baileys");
+    });
+    test("propagates error when the active driver fails to send", async () => {
+        const dm = getDriverManager();
+        const failingDriver = createMockDriver("baileys", true, true);
+        dm.register(failingDriver, { isPrimary: true });
+        await assert.rejects(async () => sendActiveDriverText("5511999999999@c.us", "failing send"), /baileys sendText failed/);
+    });
+    test("passes quoted and mentions options through to the driver", async () => {
+        const dm = getDriverManager();
+        let receivedOpts = null;
+        const driver = {
+            ...createMockDriver("baileys"),
+            sendText: async (_jid, _text, opts) => {
+                receivedOpts = opts;
+                return { id: "msg1", chatId: _jid, timestamp: Date.now() };
+            },
+        };
+        dm.register(driver, { isPrimary: true });
+        const quotedRef = { id: "orig-msg", remoteJid: "123@s.whatsapp.net", fromMe: false };
+        const ref = await sendActiveDriverText("5511999999999@c.us", "reply", { quoted: quotedRef, mentions: ["@user1"] });
+        assert.equal(ref.id, "msg1");
+        assert.deepStrictEqual(receivedOpts, { quoted: quotedRef, mentions: ["@user1"] });
+    });
+    test("throws when no driver is registered", async () => {
+        const dm = getDriverManager();
+        await assert.rejects(async () => sendActiveDriverText("5511999999999@c.us", "no driver"), /no active driver/i);
+    });
+});

package/dist/kernel/alerts.js

@@ -29,6 +29,7 @@ import { spawn } from "child_process";
 import nodemailer from "nodemailer";
 import { CONFIG_DIR, ADMIN_JID, SMTP_HOST, SMTP_PORT, SMTP_SEC, SMTP_USER, SMTP_PASS, SMTP_FROM, SMTP_TO, SMTP_INSECURE, } from "#config";
 import { logger } from "#logger";
+import { t } from "#i18n";
 const ALERTS_LOG_FILE = path.join(CONFIG_DIR, "alerts.log");
 let sockProvider = null;
 /**
@@ -160,25 +161,18 @@ export function fireAlert(kind, details = {}) {
     if (kind === "send_failed_no_fallback") {
         event = {
             level: "critical",
-            title: "manybot: sem driver de fallback",
+            title: t("alerts.noFallbackTitle"),
             message: `jid=${details.jid} primary=${details.primary}`,
         };
     }
     else if (kind === "send_failed_both_drivers") {
         event = {
             level: "critical",
-            title: "manybot: envio falhou nos dois drivers",
+            title: t("alerts.bothDriversFailedTitle"),
             message: `jid=${details.jid} ${details.primary}->${details.secondary}` +
                 (details.error ? ` error=${String(details.error)}` : ""),
         };
     }
-    else if (kind === "whatsmeow_subprocess_halted") {
-        event = {
-            level: "critical",
-            title: "manybot: subprocesso whatsmeow halted",
-            message: `fallback indisponível: ${details.reason ?? "unknown"} — bot segue só com Baileys`,
-        };
-    }
     else {
         event = {
             level: "warning",

package/dist/kernel/chatSession.js

@@ -0,0 +1,65 @@
+/**
+ * chatSession.ts
+ *
+ * Phase 7 of MANYBOT-6.md — exclusive chat session, kernel primitive.
+ *
+ * Prevents two plugins from running an interactive flow (a game, the
+ * figurinha timeout session, a music-download prompt, etc.) in the same
+ * chat at the same time. The kernel only owns the lock itself — WHO holds
+ * it and for how long. Everything about the session's own state (timeout,
+ * collected media, turn tracking, ...) stays entirely inside the owning
+ * plugin; `commands.yaml` only ever registers commands, never internal
+ * flow state.
+ *
+ * Deliberately NOT persisted (no settingsDb / SQLite): a session lock only
+ * makes sense for the lifetime of the running process — restarting the
+ * bot should never leave a chat stuck "locked" by a plugin that no longer
+ * remembers it opened one.
+ *
+ * many-ai's passive continuation window (its own multi-turn follow-up
+ * mechanism) is a separate category by design and never touches this
+ * lock — see the Phase 7 note in MANYBOT-6.md. This module does not
+ * special-case many-ai; it simply never gets called by it.
+ */
+const sessions = new Map();
+/**
+ * Attempts to open an exclusive session for `pluginName` in `chatId`.
+ * Returns `true` if the session is now held by `pluginName` — either it
+ * was free, or `pluginName` already held it (idempotent re-acquire, e.g.
+ * a plugin calling acquire() again on a later message of its own flow).
+ * Returns `false` if another plugin already holds the session.
+ */
+export function acquireSession(chatId, pluginName) {
+    const current = sessions.get(chatId);
+    if (current && current.pluginName !== pluginName) {
+        return false;
+    }
+    sessions.set(chatId, { pluginName, acquiredAt: current?.acquiredAt ?? Date.now() });
+    return true;
+}
+/**
+ * Releases the session in `chatId`, but only if it is currently held by
+ * `pluginName` — a plugin can never release a lock it doesn't own. No-op
+ * (returns `false`) if the chat has no session, or it's held by someone
+ * else.
+ */
+export function releaseSession(chatId, pluginName) {
+    const current = sessions.get(chatId);
+    if (!current || current.pluginName !== pluginName) {
+        return false;
+    }
+    sessions.delete(chatId);
+    return true;
+}
+/** Whether `chatId` currently has an open exclusive session (by anyone). */
+export function isSessionLocked(chatId) {
+    return sessions.has(chatId);
+}
+/** Which plugin currently holds the session in `chatId`, if any. */
+export function getSessionHolder(chatId) {
+    return sessions.get(chatId)?.pluginName ?? null;
+}
+/** Test-only: wipe all session state between tests. */
+export function __resetSessionsForTests() {
+    sessions.clear();
+}

package/dist/kernel/chatSession.test.js

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import test, { describe, beforeEach } from "node:test";
+import { acquireSession, releaseSession, isSessionLocked, getSessionHolder, __resetSessionsForTests, } from "#kernel/chatSession.js";
+describe("kernel/chatSession — Phase 7 exclusive chat session", () => {
+    beforeEach(() => {
+        __resetSessionsForTests();
+    });
+    test("acquire on a free chat succeeds and locks it", () => {
+        assert.equal(acquireSession("chat1", "gamePlugin"), true);
+        assert.equal(isSessionLocked("chat1"), true);
+        assert.equal(getSessionHolder("chat1"), "gamePlugin");
+    });
+    test("a different plugin cannot acquire an already-held session", () => {
+        assert.equal(acquireSession("chat1", "gamePlugin"), true);
+        assert.equal(acquireSession("chat1", "figurinhaPlugin"), false);
+        assert.equal(getSessionHolder("chat1"), "gamePlugin", "holder unchanged");
+    });
+    test("the same plugin re-acquiring its own session is idempotent", () => {
+        assert.equal(acquireSession("chat1", "gamePlugin"), true);
+        assert.equal(acquireSession("chat1", "gamePlugin"), true);
+        assert.equal(getSessionHolder("chat1"), "gamePlugin");
+    });
+    test("release only works for the plugin that holds the session", () => {
+        acquireSession("chat1", "gamePlugin");
+        assert.equal(releaseSession("chat1", "figurinhaPlugin"), false, "wrong plugin cannot release");
+        assert.equal(isSessionLocked("chat1"), true, "still locked");
+        assert.equal(releaseSession("chat1", "gamePlugin"), true);
+        assert.equal(isSessionLocked("chat1"), false);
+        assert.equal(getSessionHolder("chat1"), null);
+    });
+    test("releasing a chat with no session is a no-op", () => {
+        assert.equal(releaseSession("neverLocked", "anyPlugin"), false);
+    });
+    test("sessions are independent per chat", () => {
+        assert.equal(acquireSession("chatA", "gamePlugin"), true);
+        assert.equal(acquireSession("chatB", "figurinhaPlugin"), true);
+        assert.equal(getSessionHolder("chatA"), "gamePlugin");
+        assert.equal(getSessionHolder("chatB"), "figurinhaPlugin");
+    });
+    test("a freed session can be acquired by a different plugin afterward", () => {
+        acquireSession("chat1", "gamePlugin");
+        releaseSession("chat1", "gamePlugin");
+        assert.equal(acquireSession("chat1", "figurinhaPlugin"), true);
+        assert.equal(getSessionHolder("chat1"), "figurinhaPlugin");
+    });
+});