@manybot/manybot 5.6.1 → 5.8.0

package/dist/drivers/baileys/api/index.js

@@ -14,6 +14,7 @@ import { logger } from "#logger";
 import { t, createPluginT, reloadTranslations, getCurrentLang } from "#i18n";
 import { CONFIG, CONFIG_DIR } from "#config";
 import { enqueue } from "#download";
+import { waitForEditSlot } from "#kernel/sendGuard.js";
 import { schedule, cancelPlugin } from "#kernel/scheduler.js";
 import { emptyFolder } from "#utils/file.js";
 import { normalizeJid, denormalizeJid, toWireJid } from "#drivers/jid.js";
@@ -24,11 +25,14 @@ import path from "path";
 import os from "os";
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
-import { waitForSendSlot, simulateState, typingDuration, mediaDuration, waitForEditSlot } from "#sendguard";
+import { waitForSendSlot, simulateState, typingDuration, mediaDuration } from "#sendguard";
 import { sendWithFallback } from "#kernel/sendFallbackGuard.js";
 import { buildSettingsApi } from "#settingsdb";
+import * as commandAccess from "#kernel/commandAccess.js";
+import * as chatSession from "#kernel/chatSession.js";
+import { resolveDispatch, runCommand as dispatchCommand } from "#kernel/runCommand.js";
 import WebP from "node-webpmux";
-import { getAggregateVotesInPollMessage, decryptPollVote, jidNormalizedUser, } from "@whiskeysockets/baileys";
+import { jidNormalizedUser, } from "@whiskeysockets/baileys";
 // ── Raw-Baileys escape hatch ─────────────────────────────────────────────────
 //
 // This whole file is the Baileys driver's plugin-context builder, so the
@@ -175,13 +179,13 @@ function hasMention(contextInfo) {
     return !!(ci?.mentionedJid && Array.isArray(ci.mentionedJid) && ci.mentionedJid.length > 0);
 }
 /** True if the bot's own JID (PN or LID) is in contextInfo.mentionedJid. */
-function hasBotMention(contextInfo, sock, store) {
+function hasBotMention(contextInfo, contract, store) {
     const ci = contextInfo;
     const mentioned = ci?.mentionedJid;
     if (!mentioned || mentioned.length === 0)
         return false;
-    const botLid = sock.user?.lid;
-    const botCandidates = [sock.user?.id, botLid]
+    const me = contract.me();
+    const botCandidates = [me.id, me.lid]
         .filter((v) => !!v)
         .map(v => normalizeJid(store.resolveJid(normalizeJid(v))));
     if (botCandidates.length === 0)
@@ -223,11 +227,11 @@ function bindGroupMetaInvalidation(contract) {
     if (groupMetaInvalidationBound)
         return;
     groupMetaInvalidationBound = true;
-    const sock = rawSocketOf(contract);
-    const ev = sock.ev;
-    ev.on("group-participants.update", (u) => groupMetaCache.delete(u.id));
-    ev.on("groups.update", (updates) => {
-        for (const u of updates)
+    contract.on("group-participants.update", (u) => {
+        groupMetaCache.delete(u.id);
+    });
+    contract.on("groups.update", (p) => {
+        for (const u of p.updates)
             if (u.id)
                 groupMetaCache.delete(u.id);
     });
@@ -517,6 +521,27 @@ async function normalizeContact(jid, info, botJid, contract) {
     };
 }
 // ── Chats API ─────────────────────────────────────────────────────────────────
+function buildCommandsApi() {
+    return {
+        exists: commandAccess.exists,
+        desc: commandAccess.desc,
+        manual: commandAccess.manual,
+        list: commandAccess.list,
+        isMenuAlias: commandAccess.isMenuAlias,
+    };
+}
+// ── Session API (Phase 7, MANYBOT-6.md) ─────────────────────────────────────
+// Scoped to the current chat (normJid) + the calling plugin. Only built in
+// buildApi() (runtime), not buildBaseApi() — there is no "current chat" at
+// setup time to lock.
+function buildSessionApi(chatId, pluginName) {
+    return {
+        acquire: () => chatSession.acquireSession(chatId, pluginName),
+        release: () => { chatSession.releaseSession(chatId, pluginName); },
+        isLocked: () => chatSession.isSessionLocked(chatId),
+        isMine: () => chatSession.getSessionHolder(chatId) === pluginName,
+    };
+}
 function buildChatsApi(store) {
     return {
         /**
@@ -719,7 +744,6 @@ function makeHistoryArray(entries, store) {
     return arr;
 }
 export function buildMessageContext(msg, contract, store, guardOptions = {}) {
-    const sock = rawSocketOf(contract);
     const body = getMsgBody(msg);
     const prefix = CONFIG.CMD_PREFIX;
     const rawArgs = body.trim().split(/\s+/);
@@ -742,6 +766,21 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
     // We carry the same _raw.contextInfo on the synthetic so a recursive
     // getReply().getReply() keeps working (the inner call re-reads
     // getContextInfo off _raw.contextInfo).
+    //
+    // WhatsApp's contextInfo never carries the quoted author's pushname, so
+    // we best-effort it from the local contact store (same lookup pattern
+    // as getContact() below) instead of leaving it undefined -> falling
+    // back to the raw phone number in senderName.
+    const lookupPushName = (jid) => {
+        if (!jid)
+            return undefined;
+        const contacts = store.contacts;
+        const info = contacts[jid]
+            ?? contacts[denormalizeJid(jid)]
+            ?? contacts[store.resolveJid(jid)]
+            ?? contacts[denormalizeJid(store.resolveJid(jid))];
+        return info?.notify ?? undefined;
+    };
     const quotedRaw = contextInfo?.quotedMessage
         ? (() => {
             const decoded = decodeContent(contextInfo.quotedMessage);
@@ -754,6 +793,8 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
                 timestamp: 0,
                 body: decoded.body,
                 mimetype: decoded.mimetype,
+                fromPn: contextInfo.participant ?? undefined,
+                pushName: lookupPushName(contextInfo.participant),
                 _raw: {
                     contextInfo: {
                         stanzaId: contextInfo.stanzaId,
@@ -777,6 +818,8 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
                 type: "other",
                 contentHash: "",
                 timestamp: 0,
+                fromPn: msg.quotedKey.participant ?? undefined,
+                pushName: lookupPushName(msg.quotedKey.participant),
             }
             : null;
     return {
@@ -821,7 +864,7 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
             return buildMessageContext(quotedRaw, contract, store, { cooldown: false, jitter: false });
         },
         hasMention: hasMention(contextInfo),
-        hasBotMention: hasBotMention(contextInfo, sock, store),
+        hasBotMention: hasBotMention(contextInfo, contract, store),
         reply: makeSender(contract, store, rawJid, msg, { cooldown, jitter }),
         async react(emoji) {
             await contract.react(rawJid, {
@@ -845,7 +888,10 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
             if (!msg.fromMe) {
                 throw new Error("[pluginApi] edit() can only be used on the bot's own messages");
             }
-            if (!msg.id || !(await waitForEditSlot(msg.id)))
+            if (!msg.id)
+                return;
+            const allowed = await waitForEditSlot(msg.id);
+            if (!allowed)
                 return;
             await contract.editMessage(rawJid, {
                 id: msg.id,
@@ -867,7 +913,7 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
                 ?? store.contacts[denormalizeJid(sender)]
                 ?? store.contacts[store.resolveJid(msg.fromPn ?? "")]
                 ?? store.contacts[denormalizeJid(store.resolveJid(msg.fromPn ?? ""))];
-            const botJid = sock.user?.id ? jidNormalizedUser(sock.user.id) : null;
+            const botJid = contract.me().id ? jidNormalizedUser(contract.me().id) : null;
             return normalizeContact(sender, info, botJid, contract);
         },
     };
@@ -961,7 +1007,10 @@ class MessageHandle {
         if (!msg.fromMe) {
             throw new Error("[pluginApi] edit() can only be used on the bot's own messages");
         }
-        if (!msg.id || !(await waitForEditSlot(msg.id)))
+        if (!msg.id)
+            return;
+        const allowed = await waitForEditSlot(msg.id);
+        if (!allowed)
             return;
         await this._contract.editMessage(msg.chatId, {
             id: msg.id,
@@ -1321,20 +1370,58 @@ function buildSetupSendApi(contract, store) {
         },
     };
 }
-// ── Events API ────────────────────────────────────────────────────────────────
+const WA_EVENT_NAMES = new Set([
+    "messages.upsert",
+    "messages.update",
+    "messages.delete",
+    "messaging-history.set",
+    "chats.upsert",
+    "chats.update",
+    "chats.delete",
+    "contacts.upsert",
+    "contacts.update",
+    "group-participants.update",
+    "groups.upsert",
+    "groups.update",
+    "group.join-request",
+    "blocklist.set",
+    "blocklist.update",
+    "connection.update",
+]);
+function assertSupportedEvent(event) {
+    if (!WA_EVENT_NAMES.has(event)) {
+        throw new Error(`[events] unsupported event "${event}". Supported: ${[...WA_EVENT_NAMES].join(", ")}. ` +
+            `If you need this event, file an issue — adding events to WaEventName is a contract change.`);
+    }
+}
 const listenerRegistry = new Map();
-export function cleanupPluginEvents(pluginName, contract) {
-    const sock = rawSocketOf(contract);
+export function cleanupPluginEvents(pluginName, _contract) {
     const list = listenerRegistry.get(pluginName);
     if (list) {
-        for (const { event, handler } of list) {
+        for (const ref of list) {
             try {
-                sock.ev.off(event, handler);
+                ref.detach();
             }
             catch { }
         }
         listenerRegistry.delete(pluginName);
     }
+    // The poll-vote subscription is created in `buildPollApi` by calling
+    // `contract.on(...)` directly, so it lives outside `listenerRegistry`.
+    // Detach it here so the listener doesn't outlive the plugin (and a
+    // reloaded plugin can re-subscribe — `buildPollApi` gates on the
+    // `boundPollPlugins` map).
+    const pollDetach = boundPollPlugins.get(pluginName);
+    if (pollDetach) {
+        try {
+            pollDetach();
+        }
+        catch { }
+        boundPollPlugins.delete(pluginName);
+    }
+    // Drop the per-plugin poll registry so reloading a plugin doesn't see
+    // stale PollHandles from a prior instance.
+    pollRegistry.delete(pluginName);
     cancelPlugin(pluginName);
 }
 /**
@@ -1342,21 +1429,26 @@ export function cleanupPluginEvents(pluginName, contract) {
  * @param {string}     pluginName
  */
 function buildEventsApi(contract, pluginName) {
-    const sock = rawSocketOf(contract);
     return {
         on(event, handler) {
-            sock.ev.on(event, handler);
+            assertSupportedEvent(event);
+            const wrapped = (payload) => handler(payload);
+            const detach = contract.on(event, wrapped);
             if (!listenerRegistry.has(pluginName))
                 listenerRegistry.set(pluginName, new Set());
-            const ref = { event, handler };
+            const ref = { event, handler: wrapped, detach };
             listenerRegistry.get(pluginName).add(ref);
             return () => {
-                sock.ev.off(event, handler);
+                try {
+                    detach();
+                }
+                catch { }
                 listenerRegistry.get(pluginName)?.delete(ref);
             };
         },
         once(event) {
-            return new Promise(resolve => {
+            assertSupportedEvent(event);
+            return new Promise((resolve) => {
                 const off = this.on(event, (data) => { off(); resolve(data); });
             });
         },
@@ -1364,8 +1456,12 @@ function buildEventsApi(contract, pluginName) {
             const list = listenerRegistry.get(pluginName);
             if (!list)
                 return;
-            for (const { event, handler } of list)
-                sock.ev.off(event, handler);
+            for (const ref of list) {
+                try {
+                    ref.detach();
+                }
+                catch { }
+            }
             listenerRegistry.delete(pluginName);
         },
     };
@@ -1425,8 +1521,42 @@ async function resolveMentionJids(contract, store, jid, mentions) {
     }
     return Array.from(new Set(result.filter(Boolean)));
 }
-function buildAdminApi(contract, chatJid) {
-    const norm = (v) => (Array.isArray(v) ? v : [v]).map(toWireJid);
+function buildAdminApi(contract, store, chatJid) {
+    /**
+     * Resolve admin-supplied identifiers (bare phone number, @c.us,
+     * @s.whatsapp.net, or @lid) to the exact jid WhatsApp has on file for
+     * that participant *in this group*. A naive toWireJid() guess is only
+     * correct for pn-addressed groups — lid-addressed groups (increasingly
+     * common, e.g. when a member hides their phone number) only recognize
+     * that member by @lid, which a phone number typed by the admin can't
+     * produce on its own. Baileys' raw groupMetadata() participants carry
+     * `id` (whatever WA addresses them as here), `jid` (its best
+     * phone-number guess) and `lid` — check all three.
+     *
+     * Throws per-identifier if it doesn't match a current member, instead
+     * of silently sending a guessed jid that WhatsApp rejects deep inside
+     * the per-participant status array (see assertParticipantsUpdateOk).
+     */
+    async function resolveTargets(groupJid, identifiers) {
+        const meta = await getGroupMetadataCached(contract, groupJid);
+        const out = [];
+        for (const id of identifiers) {
+            const wire = toWireJid(id);
+            const resolved = normalizeJid(store.resolveJid(id));
+            const match = meta.participants.find((p) => {
+                const pAny = p;
+                return (toWireJid(pAny.id) === wire ||
+                    normalizeJid(store.resolveJid(pAny.id)) === resolved ||
+                    (pAny.jid ? toWireJid(pAny.jid) === wire : false) ||
+                    (pAny.lid ? toWireJid(pAny.lid) === wire : false));
+            });
+            if (!match) {
+                throw new Error(t("driver.groupParticipantNotFound", { id, group: groupJid }));
+            }
+            out.push(match.id);
+        }
+        return Array.from(new Set(out));
+    }
     function requireChat() {
         if (!chatJid)
             throw new Error("This admin operation requires a runtime group context.");
@@ -1456,7 +1586,7 @@ function buildAdminApi(contract, chatJid) {
         const failed = results.filter((r) => r?.status && r.status !== "200");
         if (failed.length > 0) {
             const detail = failed.map((r) => `${r.jid ?? "?"}=${r.status}`).join(", ");
-            throw new Error(`groupParticipantsUpdate("${action}") rejeitado para: ${detail}`);
+            throw new Error(t("driver.groupParticipantsUpdateRejected", { action, detail }));
         }
     }
     /**
@@ -1471,16 +1601,35 @@ function buildAdminApi(contract, chatJid) {
             results = await contract.groupParticipantsUpdate(jid, users, action);
         }
         catch (err) {
-            throw new Error(`groupParticipantsUpdate("${action}") falhou para o grupo "${jid}" com participantes [${users.join(", ")}]: ${err.message}`);
+            throw new Error(t("driver.groupParticipantsUpdateFailed", {
+                action,
+                group: jid,
+                users: users.join(", "),
+                message: err.message,
+            }));
         }
         assertParticipantsUpdateOk(action, results);
         return results;
     }
-    function createTargetableAction(action, memberIds) {
-        const users = norm(memberIds);
-        const executeCurrent = async () => { requireChat(); return action(chatJid, users); };
+    function createTargetableAction(action, memberIds, mode = "existingMember") {
+        const raw = Array.isArray(memberIds) ? memberIds : [memberIds];
+        const resolve = async (groupJid) => mode === "existingMember"
+            ? resolveTargets(groupJid, raw)
+            // `add` targets people who aren't members yet — there's no
+            // participant-list entry to match against, so fall back to a
+            // plain jid guess (the historical behavior).
+            : Array.from(new Set(raw.map(toWireJid)));
+        const executeCurrent = async () => {
+            requireChat();
+            const users = await resolve(chatJid);
+            return action(chatJid, users);
+        };
         return {
-            async to(targetJid) { await getGroup(targetJid); return action(targetJid, users); },
+            async to(targetJid) {
+                await getGroup(targetJid);
+                const users = await resolve(targetJid);
+                return action(targetJid, users);
+            },
             then(onfulfilled, onrejected) {
                 return executeCurrent().then(onfulfilled, onrejected);
             },
@@ -1495,22 +1644,25 @@ function buildAdminApi(contract, chatJid) {
     return {
         /** @param {string|string[]} memberIds — JID (@s.whatsapp.net/@lid), this framework's @c.us form, or a bare phone number */
         add(memberIds) {
-            return createTargetableAction((jid, users) => runParticipantsUpdate(jid, users, "add"), memberIds);
+            return createTargetableAction((jid, users) => runParticipantsUpdate(jid, users, "add"), memberIds, "newMember");
         },
         /** @param {string|string[]} memberIds — JID (@s.whatsapp.net/@lid), this framework's @c.us form, or a bare phone number */
         async kick(memberIds) {
             requireChat();
-            return runParticipantsUpdate(chatJid, norm(memberIds), "remove");
+            const users = await resolveTargets(chatJid, Array.isArray(memberIds) ? memberIds : [memberIds]);
+            return runParticipantsUpdate(chatJid, users, "remove");
         },
         /** @param {string|string[]} memberIds — JID (@s.whatsapp.net/@lid), this framework's @c.us form, or a bare phone number */
         async promote(memberIds) {
             requireChat();
-            return runParticipantsUpdate(chatJid, norm(memberIds), "promote");
+            const users = await resolveTargets(chatJid, Array.isArray(memberIds) ? memberIds : [memberIds]);
+            return runParticipantsUpdate(chatJid, users, "promote");
         },
         /** @param {string|string[]} memberIds — JID (@s.whatsapp.net/@lid), this framework's @c.us form, or a bare phone number */
         async demote(memberIds) {
             requireChat();
-            return runParticipantsUpdate(chatJid, norm(memberIds), "demote");
+            const users = await resolveTargets(chatJid, Array.isArray(memberIds) ? memberIds : [memberIds]);
+            return runParticipantsUpdate(chatJid, users, "demote");
         },
         /** @param {string} name */
         async setSubject(name) {
@@ -1563,11 +1715,15 @@ function buildMeApi(contract) {
 }
 // ── Poll API ──────────────────────────────────────────────────────────────────
 const pollRegistry = new Map();
-// Rebinding must happen per socket instance — a plugin name alone doesn't
-// tell us whether the listener is bound to the CURRENT (post-reconnect)
-// sock.ev or a dead one from before. WeakMap keyed by sock lets old
-// entries fall off automatically once that socket is garbage collected.
-const pollListenersBySocket = new WeakMap();
+// Per-process map of plugin names whose poll-vote subscription is bound,
+// to its unsubscribe handle. The contract handles rebinding to a fresh
+// socket on reconnect (its `on()` returns an unsubscribe that drops
+// cleanly on the dead socket's fan-out once it's torn down), so a simple
+// per-process map is enough — no per-sock WeakMap needed anymore.
+// `cleanupPluginEvents` MUST call the stored detach handle on unload so
+// the listener doesn't outlive the plugin and so a reloaded plugin can
+// re-subscribe.
+const boundPollPlugins = new Map();
 /**
  * Tracks votes for an active poll.
  * Obtained via ctx.poll.create().
@@ -1638,59 +1794,29 @@ function buildPollApi(contract, store, rawJid, guardOptions, pluginName) {
         pollRegistry.set(pluginName, new Map());
     const registry = pollRegistry.get(pluginName);
     // Keyed by creationId -> (voterKey -> latest vote entry). WhatsApp resends
-    // the *entire current selection* on every tap (not a diff), and Baileys'
-    // getAggregateVotesInPollMessage() replays whatever pollUpdates you give it
-    // with no dedup — so we must keep only the latest entry per voter ourselves,
-    // or retracted/changed votes keep counting alongside the new one.
+    // the *entire current selection* on every tap (not a diff), and the
+    // aggregatePollVotes() contract method replays whatever pollUpdates you
+    // give it with no dedup — so we must keep only the latest entry per
+    // voter ourselves, or retracted/changed votes keep counting alongside
+    // the new one.
     const pollVotesByCreationId = new Map();
-    // Poll decryption needs the raw Baileys socket (sock.ev for
-    // messages.upsert, sock.user for self-JID shape), so we lift it off the
-    // contract here. The WeakMap key is the socket itself so old listeners
-    // fall off automatically when the socket is replaced (reconnect).
-    const sock = rawSocketOf(contract);
-    let boundPlugins = pollListenersBySocket.get(sock);
-    if (!boundPlugins) {
-        boundPlugins = new Set();
-        pollListenersBySocket.set(sock, boundPlugins);
-    }
-    if (!boundPlugins.has(pluginName)) {
-        boundPlugins.add(pluginName);
-        const meId = sock.user?.id ? jidNormalizedUser(sock.user.id) : "me";
-        // WhatsApp doesn't consistently use the same JID shape (LID vs PN) for
-        // pollCreatorJid/voterJid when deriving the poll-vote decryption key —
-        // it depends on addressingMode, 1:1 vs group, and which side sent last.
-        // Trying to compute "the" correct JID up front (as the old resolveAuthor
-        // did, always preferring participantPn) causes AES-GCM auth failures
-        // whenever WhatsApp actually used the LID for that message. Instead,
-        // gather every plausible JID for each side and brute-force combinations
-        // until one decrypts successfully — see
-        // https://github.com/WhiskeySockets/Baileys/issues/2342 and #1678.
-        function jidCandidates(key) {
-            const cands = [];
-            if (key.fromMe) {
-                const selfLid = sock.user?.lid;
-                if (selfLid)
-                    cands.push(jidNormalizedUser(selfLid));
-                if (sock.user?.id)
-                    cands.push(jidNormalizedUser(sock.user.id));
-            }
-            else {
-                const rawParticipant = key.participant ?? key.remoteJid;
-                if (rawParticipant)
-                    cands.push(jidNormalizedUser(rawParticipant));
-                if (key.participantPn)
-                    cands.push(jidNormalizedUser(key.participantPn));
-                if (rawParticipant?.endsWith("@lid")) {
-                    const resolved = store.resolveJid(rawParticipant);
-                    if (resolved && resolved !== rawParticipant)
-                        cands.push(jidNormalizedUser(resolved));
-                }
-            }
-            return Array.from(new Set(cands.filter(Boolean)));
-        }
-        sock.ev.on("messages.upsert", async ({ messages: msgs }) => {
+    // Poll decryption is Baileys-specific. Both the subscription
+    // (`messages.upsert`) and the decryption/aggregation go through the
+    // contract — `buildPollApi` doesn't touch the raw socket anymore. The
+    // contract's optional methods are only implemented by the Baileys
+    // adapter; drivers that don't have poll decryption leave them off the
+    // contract and we silently no-op here (a bot on a non-Baileys driver
+    // simply can't track poll votes).
+    if (!boundPollPlugins.has(pluginName) &&
+        typeof contract.decryptPollVote === "function" &&
+        typeof contract.aggregatePollVotes === "function") {
+        const detach = contract.on("messages.upsert", async ({ messages: msgs }) => {
             for (const msg of msgs) {
-                const pum = msg.message?.pollUpdateMessage;
+                // Filter poll-update messages by reading the raw envelope from
+                // the store (the neutral `BotMessage` doesn't carry the
+                // `pollUpdateMessage` field — it's a Baileys-proto detail).
+                const raw = store.messages.get(msg.chatId)?.get(msg.id);
+                const pum = raw?.message?.pollUpdateMessage;
                 if (!pum)
                     continue;
                 const creationKey = pum.pollCreationMessageKey;
@@ -1703,51 +1829,52 @@ function buildPollApi(contract, store, rawJid, guardOptions, pluginName) {
                 if (!storeMsg || !pollEncKeyRaw || !pum.vote)
                     continue;
                 try {
-                    const pollEncKey = Buffer.isBuffer(pollEncKeyRaw)
-                        ? pollEncKeyRaw
-                        : Buffer.from(pollEncKeyRaw, "base64");
-                    const creatorCandidates = jidCandidates((creationKey ?? {}));
-                    const voterCandidates = jidCandidates(msg.key);
-                    let decryptedVote;
-                    for (const pollCreatorJid of creatorCandidates) {
-                        for (const voterJid of voterCandidates) {
-                            try {
-                                decryptedVote = decryptPollVote(pum.vote, {
-                                    pollEncKey,
-                                    pollCreatorJid,
-                                    pollMsgId: creationId,
-                                    voterJid,
-                                });
-                                break;
-                            }
-                            catch {
-                                // try next JID combination
-                            }
-                        }
-                        if (decryptedVote)
-                            break;
-                    }
-                    if (!decryptedVote) {
-                        throw new Error(`all JID combinations failed (creator=${JSON.stringify(creatorCandidates)}, voter=${JSON.stringify(voterCandidates)})`);
+                    const decrypted = await contract.decryptPollVote({
+                        voteKey: {
+                            id: msg.id,
+                            remoteJid: msg.chatId,
+                            fromMe: msg.fromMe,
+                            participant: msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? null,
+                        },
+                        pollKey: {
+                            id: creationId,
+                            remoteJid: creationKey?.remoteJid ?? null,
+                            fromMe: null,
+                            participant: creationKey?.participant ?? null,
+                        },
+                        pollEncKey: pollEncKeyRaw,
+                    });
+                    if (!decrypted) {
+                        throw new Error("decryptPollVote returned null — JID candidate exhaustion or stale enc key");
                     }
-                    const voterKey = msg.key.fromMe
-                        ? meId
-                        : jidNormalizedUser(msg.key.participant ?? msg.key.remoteJid ?? "");
+                    const voterKey = msg.fromMe
+                        ? (contract.me().id ?? "me")
+                        : jidNormalizedUser(msg.participantAlt ?? msg.fromLid ?? msg.chatId);
                     const votesByVoter = pollVotesByCreationId.get(creationId) ?? new Map();
                     votesByVoter.set(voterKey, {
-                        pollUpdateMessageKey: msg.key,
-                        vote: decryptedVote,
+                        pollUpdateMessageKey: { id: msg.id, remoteJid: msg.chatId, fromMe: msg.fromMe },
+                        vote: decrypted,
                         senderTimestampMs: pum.senderTimestampMs,
                     });
                     pollVotesByCreationId.set(creationId, votesByVoter);
-                    const aggregated = getAggregateVotesInPollMessage({ message: storeMsg.message, pollUpdates: Array.from(votesByVoter.values()) }, meId);
+                    const pollAggregateOpts = contract.aggregatePollVotes;
+                    const aggregated = pollAggregateOpts({
+                        pollKey: {
+                            id: creationId,
+                            remoteJid: creationKey?.remoteJid ?? null,
+                            fromMe: null,
+                        },
+                        votes: Array.from(votesByVoter.values()).map((v) => v.vote),
+                        selfJid: contract.me().id ?? undefined,
+                    });
                     handle._updateFromAggregated(aggregated);
                 }
                 catch (err) {
-                    logger.error(`[poll] erro ao decriptar voto: ${err}`);
+                    logger.error(`[poll] ${t("driver.pollDecryptFailed", { error: err })}`);
                 }
             }
         });
+        boundPollPlugins.set(pluginName, detach);
     }
     const cooldown = (guardOptions.cooldown ?? true);
     const jitter = (guardOptions.jitter ?? true);
@@ -1813,6 +1940,7 @@ function buildBaseApi(contract, store, pluginRegistry, pluginName) {
         contacts: buildContactsApi(contract, store, botJid),
         storage: buildStorageApi(pluginName),
         botId: botJid,
+        commands: buildCommandsApi(),
     };
 }
 // ── Setup API ─────────────────────────────────────────────────────────────────
@@ -1830,12 +1958,52 @@ export function buildSetupApi(contract, store, pluginRegistry, pluginName) {
     return {
         ...buildBaseApi(contract, store, pluginRegistry, pluginName),
         ...buildSetupSendApi(contract, store),
-        admin: buildAdminApi(contract, null),
+        admin: buildAdminApi(contract, store, null),
         events: buildEventsApi(contract, pluginName),
         me: buildMeApi(contract),
         settings: { global: buildSettingsApi(pluginName, "_global").global },
     };
 }
+// ── ctx.runCommand facet ─────────────────────────────────────────────────────
+/**
+ * Builds the `ctx.runCommand(invocation, rawArgs?)` facet for a runtime
+ * ctx bound to `msg`/`chat`. Deliberately built AFTER `buildApi` is
+ * declared (function declarations hoist) so it can call `buildApi`
+ * again, recursively, to build a context scoped to the TARGET
+ * command's owning plugin rather than reusing the caller's — same
+ * "own storage/plugins facet, not the caller's" principle as
+ * `ctx.plugins.require()`.
+ *
+ * @param {BotMessage}      msg
+ * @param {WAChat}          chat
+ * @param {WaContract}      contract
+ * @param {BotStore}        store
+ * @param {Map}             pluginRegistry
+ * @param {string}          callerPluginName
+ */
+function buildRunCommandFacet(msg, chat, contract, store, pluginRegistry, callerPluginName) {
+    return async function runCommandFacet(invocation, rawArgs = "") {
+        const resolution = resolveDispatch(invocation, rawArgs);
+        if (resolution.target.kind === "none") {
+            return { status: "no_dispatch", sentReply: null, suggestedReply: null };
+        }
+        const entry = resolution.target.kind === "sub" ? resolution.target.parent : resolution.target.entry;
+        const targetPluginName = entry.source === "plugin" ? entry.pluginName : null;
+        const targetCtx = targetPluginName && targetPluginName !== callerPluginName
+            ? buildApi({
+                msg, chat, contract, store, pluginRegistry,
+                pluginName: targetPluginName,
+                guardOptions: pluginRegistry.get(targetPluginName)?.guardOptions ?? {},
+            })
+            : buildApi({ msg, chat, contract, store, pluginRegistry, pluginName: callerPluginName });
+        return dispatchCommand({
+            pluginName: targetPluginName,
+            ctx: targetCtx,
+            resolution,
+            reply: targetCtx.msg.reply,
+        });
+    };
+}
 // ── Runtime API ───────────────────────────────────────────────────────────────
 /**
  * Runtime API — full context with message and chat.
@@ -1885,6 +2053,8 @@ export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginNam
     return {
         ...buildBaseApi(contract, store, pluginRegistry, pluginName),
         ...buildSendApi(contract, store, rawJid, guardOptions),
+        runCommand: buildRunCommandFacet(msg, chat, contract, store, pluginRegistry, pluginName),
+        session: buildSessionApi(normJid, pluginName),
         // ── msg ──────────────────────────────────────────────────────────────────
         msg: buildMessageContext(msg, contract, store, { cooldown, jitter }),
         // ── chat ─────────────────────────────────────────────────────────────────
@@ -1986,7 +2156,7 @@ export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginNam
             },
         },
         // ── admin ─────────────────────────────────────────────────────────────────
-        admin: buildAdminApi(contract, rawJid),
+        admin: buildAdminApi(contract, store, rawJid),
         // ── me ────────────────────────────────────────────────────────────────────
         me: buildMeApi(contract),
         // ── poll ──────────────────────────────────────────────────────────────────