@manybot/manybot 5.7.0 → 5.9.0

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

@@ -13,9 +13,12 @@ import { decodeContent } from "#drivers/baileys/adapter.js";
 import { logger } from "#logger";
 import { t, createPluginT, reloadTranslations, getCurrentLang } from "#i18n";
 import { CONFIG, CONFIG_DIR } from "#config";
+import { getChatPrefix } from "#kernel/chatOverrides.js";
 import { enqueue } from "#download";
+import { waitForEditSlot } from "#kernel/sendGuard.js";
 import { schedule, cancelPlugin } from "#kernel/scheduler.js";
 import { emptyFolder } from "#utils/file.js";
+import { parsePhone } from "#utils/phoneNumber.js";
 import { normalizeJid, denormalizeJid, toWireJid } from "#drivers/jid.js";
 import { mkdirSync } from "fs";
 import { readFile, writeFile, unlink, mkdtemp, rm } from "fs/promises";
@@ -24,9 +27,12 @@ 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 { jidNormalizedUser, } from "@whiskeysockets/baileys";
 // ── Raw-Baileys escape hatch ─────────────────────────────────────────────────
@@ -142,14 +148,35 @@ function msgIsGif(msg, store) {
     return !!raw.message?.videoMessage?.gifPlayback;
 }
 /** Sender JID — group participant or DM remote JID, normalized. */
-function getMsgSender(msg, store) {
-    // Prefer the @s.whatsapp.net form when we know it (Baileys-advisor split
-    // exposes both forms on incoming messages). The adapter fills
-    // `fromPn` when known; fall back to `chatId` for DMs.
-    const participant = msg._raw?.key?.participant
-        ?? msg.fromPn;
-    const raw = participant ?? msg.chatId;
-    return normalizeJid(store.resolveJid(normalizeJid(raw)));
+function getMsgSender(msg) {
+    // LID-canonical, matching normalizeContact()'s `id` and every other
+    // participant lookup in this file (`participantAlt ?? fromLid ?? fromPn
+    // ?? null`). `participantAlt` carries the alt-LID on group messages;
+    // `remoteJidAlt` carries it on DMs (Baileys puts the DM alt-LID on the
+    // key's remoteJidAlt, not participantAlt — there's no participant field
+    // at all in a 1:1 chat). When the account is already LID-addressed
+    // (addressingMode "lid"), `chatId` itself IS the @lid form and
+    // `remoteJidAlt` may hold the PN alt instead — check chatId first so
+    // that case isn't missed. No PN fallback: null is the correct, expected
+    // value when no LID has been learned for this contact yet, not a
+    // reason to silently hand back a legacy @c.us identity.
+    const dmLid = msg.chatId?.endsWith("@lid") ? msg.chatId : msg.remoteJidAlt;
+    const lid = msg.participantAlt ?? msg.fromLid ?? dmLid ?? null;
+    return lid ? normalizeJid(lid) : null;
+}
+/**
+ * PN companion of getMsgSender(), for the few internal consumers (command
+ * permissions today) that still need to match against phone-number-based
+ * config the way it's always been written. Never exposed on ctx.msg —
+ * `sender` there is LID-canonical only, per Baileys' own "migrate to LID,
+ * don't try to restore PN" guidance.
+ */
+function getMsgSenderPn(msg) {
+    if (msg.fromPn)
+        return normalizeJid(msg.fromPn);
+    if (msg.chatId && !msg.chatId.endsWith("@lid"))
+        return normalizeJid(msg.chatId);
+    return null;
 }
 /** Quoted-message metadata as the rest of the api uses it. */
 function getQuotedContext(msg) {
@@ -175,13 +202,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)
@@ -218,6 +245,25 @@ async function getGroupMetadataCached(contract, jid) {
     groupMetaCache.set(jid, { meta, at: Date.now() });
     return meta;
 }
+/**
+ * Same fetch as {@link getGroupMetadataCached}, but always hits the network
+ * and never reads the TTL cache — used for admin permission checks
+ * (`isAdmin`/`isSenderAdmin`), which gate the `admin:`/`botAdmin:` command
+ * permission and so cannot tolerate the up-to-5-minute staleness window.
+ * Invalidation on `group-participants.update` closes most of that window,
+ * but Baileys' own event-buffer bugs during reconnects (see the welcome-
+ * message gating fix) can drop the event entirely — leaving a demoted
+ * admin able to keep running admin-only commands until the TTL expires,
+ * or indefinitely if no later promote/demote re-triggers invalidation.
+ * The result is still written into the shared cache so unrelated cached
+ * reads (`getParticipants()`, chat name) benefit from the fresh fetch too.
+ */
+async function getGroupMetadataFresh(contract, jid) {
+    const sock = rawSocketOf(contract);
+    const meta = await sock.groupMetadata(jid);
+    groupMetaCache.set(jid, { meta, at: Date.now() });
+    return meta;
+}
 let groupMetaInvalidationBound = false;
 function bindGroupMetaInvalidation(contract) {
     if (groupMetaInvalidationBound)
@@ -232,6 +278,14 @@ function bindGroupMetaInvalidation(contract) {
                 groupMetaCache.delete(u.id);
     });
 }
+/** Test-only: clears the group-metadata cache and re-arms invalidation
+ *  binding so each test starts isolated (module-level singletons otherwise
+ *  persist for the life of the process). Not for production use. */
+export function __resetGroupMetaCacheForTests() {
+    groupMetaCache.clear();
+    groupNameCache.clear();
+    groupMetaInvalidationBound = false;
+}
 /**
  * Build a WAChat adapter from a BotMessage + store.
  * Exposed for use in messageHandler.ts.
@@ -351,7 +405,9 @@ function buildConfigApi() {
          * @param {any}    [defaultValue]
          */
         get(key, defaultValue = null) {
-            return CONFIG[key] ?? defaultValue;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- `get<T>` is a
+            // type-level convenience for callers; CONFIG itself is untyped.
+            return (CONFIG[key] ?? defaultValue);
         },
     };
 }
@@ -459,13 +515,72 @@ function mentionDisplayName(jid) {
  * Build a normalized contact object from a JID and optional store metadata.
  * isBusiness is resolved via contract.getBusinessProfile(jid) — it resolves
  * to a profile only for WhatsApp Business accounts, undefined otherwise.
+ *
+ * `id` invariant: the returned ID is the LID form whenever the bot can
+ * guarantee it (input was a `@lid`, or we resolved a `@s.whatsapp.net`
+ * JID through the LID↔PN cache). When the input is a phone-based JID
+ * and we don't have a LID mapping yet, `id` is `null` — handing back a
+ * PN in that case would be a lie about the user's preferred identity
+ * (LID is now the internal addressing mode WhatsApp uses; see MANYBOT-7
+ * and the Baileys 7 LID rollout).
+ *
+ * Phone fields (`number`/`numberRaw`/`numberPretty`/`country`/
+ * `countryCallingCode`) are populated by {@link parsePhone} once a PN
+ * form is known. If we have neither a PN nor a resolvable LID, every
+ * phone field stays `null`.
+ *
+ * Groups keep their `@g.us` JID as `id` — they're not subject to the
+ * LID/PN distinction and never have a phone number to parse.
+ *
  * @param {string}              jid
  * @param {RawStoreContact}     [info]
  * @param {string|null}         [botJid]
  * @param {WaContract}          [contract]
+ * @param {string|null}         [botLid]
  */
-async function normalizeContact(jid, info, botJid, contract) {
-    const number = jid.split("@")[0];
+async function normalizeContact(jid, info, botJid, contract, store, botLid) {
+    // Compute the canonical ID form (LID for users, group JID for groups,
+    // null when we can't pin a LID) and the resolved PN form (if any) in
+    // one pass — both are derived from the same LID↔PN cache + protocol-level
+    // resolver lookups, and a successful PN resolution feeds learnLid() so
+    // the next call is fully synchronous.
+    const isGroup = jid.endsWith("@g.us");
+    let resolvedId = isGroup ? jid : null;
+    let resolvedPn = null;
+    if (!isGroup) {
+        if (jid.endsWith("@lid")) {
+            // Input is already LID — that's the canonical ID; look up the PN.
+            resolvedId = jid;
+            const cached = store.resolveJid(jid);
+            if (cached && cached !== jid) {
+                resolvedPn = cached;
+            }
+            else if (contract?.resolveLid) {
+                try {
+                    const fresh = await contract.resolveLid(jid);
+                    if (fresh) {
+                        store.learnLid(jid, fresh);
+                        resolvedPn = fresh;
+                    }
+                }
+                catch { /* fall through to null — caller decides */ }
+            }
+        }
+        else if (jid.endsWith("@s.whatsapp.net") || jid.endsWith("@c.us")) {
+            // Input is PN. Prefer the LID form for `id`; cache lookup is sync.
+            const lid = store.resolvePn(jid);
+            if (lid) {
+                resolvedId = lid;
+                resolvedPn = normalizeJid(jid);
+            }
+            else {
+                // No LID mapping yet — id stays null per the invariant.
+                resolvedPn = normalizeJid(jid);
+            }
+        }
+        // Anything else (status broadcast, newsletter, meta AI…) — id = null.
+    }
+    const phone = parsePhone(resolvedPn);
     let isBusiness = false;
     // We already have a contact record for this jid (learned from a real
     // contacts.upsert or an actual message from them) — that alone proves
@@ -474,7 +589,7 @@ async function normalizeContact(jid, info, botJid, contract) {
     // raw @lid we've never resolved to a phone number (returns a false
     // "doesn't exist" instead of throwing).
     let isWAAccount = Boolean(info);
-    if (!isWAAccount && contract && !jid.endsWith("@g.us")) {
+    if (!isWAAccount && contract && !isGroup) {
         try {
             const results = await contract.onWhatsApp(jid);
             isWAAccount = Boolean(results?.[0]?.exists);
@@ -488,9 +603,9 @@ async function normalizeContact(jid, info, botJid, contract) {
     // which we can't verify this way) — nothing backs this contact.
     // Matches the old whatsapp-web.js contract: getContactById() threw /
     // resolved to null for an unknown ID instead of returning a hollow object.
-    if (!jid.endsWith("@g.us") && !isWAAccount)
+    if (!isGroup && !isWAAccount)
         return null;
-    if (contract && !jid.endsWith("@g.us")) {
+    if (contract && !isGroup) {
         try {
             isBusiness = Boolean(await contract.getBusinessProfile(jid));
         }
@@ -499,8 +614,12 @@ async function normalizeContact(jid, info, botJid, contract) {
         }
     }
     return {
-        id: jid,
-        number,
+        id: resolvedId,
+        number: phone.number,
+        numberRaw: phone.numberRaw,
+        numberPretty: phone.numberPretty,
+        country: phone.country,
+        countryCallingCode: phone.countryCallingCode,
         pushname: info?.notify ?? null,
         name: info?.name ?? info?.verifiedName ?? null,
         // Baileys' Contact type has no "short name" equivalent (that's a
@@ -509,14 +628,49 @@ async function normalizeContact(jid, info, botJid, contract) {
         isBusiness,
         isEnterprise: false,
         isBlocked: false,
-        isMe: botJid ? jid === normalizeJid(botJid) : false,
+        isMe: (botJid && jid === normalizeJid(botJid)) || (botLid && jid === normalizeJid(botLid)) || false,
         isWAAccount,
-        isUser: !jid.endsWith("@g.us"),
-        isGroup: jid.endsWith("@g.us"),
-        mention: { text: `@${mentionDisplayName(jid)}`, mentions: [toWireJid(jid)] },
+        isUser: !isGroup,
+        isGroup,
+        // Mention text: for `@lid` contacts WhatsApp always renders the raw
+        // LID digits (privacy — it never reveals the phone number here, even
+        // when we've resolved one internally), matching mobile's "no saved
+        // contact" fallback. Only PN-native contacts get the pretty/raw phone
+        // form.
+        mention: {
+            text: resolvedId?.endsWith("@lid")
+                ? `@${mentionDisplayName(resolvedId)}`
+                : phone.numberPretty
+                    ? `@${phone.numberPretty}`
+                    : phone.numberRaw
+                        ? `@${phone.numberRaw}`
+                        : `@${mentionDisplayName(jid)}`,
+            mentions: [toWireJid(jid)],
+        },
     };
 }
 // ── 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 {
         /**
@@ -533,7 +687,15 @@ function buildChatsApi(store) {
     };
 }
 // ── Contact API ───────────────────────────────────────────────────────────────
-function buildContactsApi(contract, store, botJid) {
+export function buildContactsApi(contract, store, botJid, botLid) {
+    // Teach the store the bot's own LID↔PN mapping proactively — it's
+    // known synchronously from contract.me() and doesn't need a resolveLid()
+    // round trip or a prior sync to have taught the store this pairing
+    // (e.g. contacts.get() on the bot's own id before any message from the
+    // bot's own account arrived to populate it via message handling).
+    // Without this, self-lookups keep every phone-number field null.
+    if (botLid && botJid)
+        store.learnLid(botLid, botJid);
     return {
         /**
          * Get a normalized contact object by JID.
@@ -602,7 +764,8 @@ function buildContactsApi(contract, store, botJid) {
             if (botJid &&
                 normalizedContactId.endsWith("@lid") &&
                 resolved === normalizeJid(botJid) &&
-                normalizedContactId !== normalizeJid(botJid)) {
+                normalizedContactId !== normalizeJid(botJid) &&
+                !(botLid && normalizedContactId === normalizeJid(botLid))) {
                 logger.warn(`[contacts.get] "${contactId}" resolved to the bot's own JID — discarding stale lidMap entry, treating as unresolved.`);
                 store.forgetLid(normalizedContactId);
                 resolved = normalizedContactId;
@@ -625,7 +788,7 @@ function buildContactsApi(contract, store, botJid) {
                 notify: resolvedInfo?.notify ?? raw?.notify,
                 verifiedName: resolvedInfo?.verifiedName ?? raw?.verifiedName,
             } : undefined;
-            return normalizeContact(resolved, info, botJid, contract);
+            return normalizeContact(resolved, info, botJid, contract, store, botLid);
         },
         /**
          * Get the profile picture URL of a contact.
@@ -713,21 +876,33 @@ function makeHistoryArray(entries, store) {
     const arr = entries;
     arr.last = (n) => makeHistoryArray(typeof n === "number" ? entries.slice(-n) : entries.slice(), store);
     arr.from = (senderId) => {
-        const target = normalizeJid(store.resolveJid(normalizeJid(senderId)));
+        // `e.sender` is LID-canonical (see getMsgSender()) — resolve a
+        // phone-number input to its LID before comparing. If it's already
+        // `@lid`, pass through unchanged. If no LID mapping is known for a
+        // PN input, there's nothing to match against (filters to empty),
+        // same as e.sender being null for that contact.
+        const normalized = normalizeJid(senderId.trim());
+        const target = normalized.endsWith("@lid") ? normalized : store.resolvePn(normalized);
+        if (!target)
+            return makeHistoryArray([], store);
         return makeHistoryArray(entries.filter((e) => e.sender === target), store);
     };
     return arr;
 }
 export function buildMessageContext(msg, contract, store, guardOptions = {}) {
-    const sock = rawSocketOf(contract);
     const body = getMsgBody(msg);
-    const prefix = CONFIG.CMD_PREFIX;
+    const prefix = getChatPrefix(msg.chatId);
     const rawArgs = body.trim().split(/\s+/);
     const first = rawArgs[0]?.toLowerCase() ?? "";
     const hasPrefix = first.startsWith(prefix);
     const command = hasPrefix ? first.slice(prefix.length) : "";
     const rawJid = msg.chatId;
-    const sender = getMsgSender(msg, store);
+    const sender = getMsgSender(msg);
+    const senderPn = getMsgSenderPn(msg);
+    // Best-known identity for anything that still needs a non-null jid
+    // internally (contact lookup, the sender-name fallback below) — prefers
+    // LID, falls back to PN, and finally the chat itself so it's never empty.
+    const contactId = sender ?? senderPn ?? msg.chatId;
     const cooldown = guardOptions.cooldown ?? true;
     const jitter = guardOptions.jitter ?? true;
     const contextInfo = getContextInfo(msg);
@@ -742,6 +917,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 +944,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 +969,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 {
@@ -786,7 +980,8 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
         type: getMsgType(msg),
         fromMe: msg.fromMe,
         sender,
-        senderName: msg.pushName ?? sender.replace(/(:\d+)?@.*$/, ""),
+        senderPn,
+        senderName: msg.pushName ?? contactId.replace(/(:\d+)?@.*$/, ""),
         command,
         args: rawArgs.slice(1),
         is(cmd) {
@@ -794,6 +989,7 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
         },
         hasMedia: msgHasMedia(msg),
         isGif: msgIsGif(msg, store),
+        mentionedJid: msg.mentionedJid ?? [],
         async downloadMedia(opts = {}) {
             try {
                 // contract.downloadMedia handles reupload internally via the
@@ -821,7 +1017,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 +1041,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,
@@ -863,12 +1062,13 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
          * @returns {Promise<object|null>} null if the sender can't be confirmed as a real WhatsApp account.
          */
         async getContact() {
-            const info = store.contacts[sender]
-                ?? store.contacts[denormalizeJid(sender)]
+            const info = store.contacts[contactId]
+                ?? store.contacts[denormalizeJid(contactId)]
                 ?? store.contacts[store.resolveJid(msg.fromPn ?? "")]
                 ?? store.contacts[denormalizeJid(store.resolveJid(msg.fromPn ?? ""))];
-            const botJid = sock.user?.id ? jidNormalizedUser(sock.user.id) : null;
-            return normalizeContact(sender, info, botJid, contract);
+            const botJid = contract.me().id ? jidNormalizedUser(contract.me().id) : null;
+            const botLid = contract.me().lid ? normalizeJid(contract.me().lid) : null;
+            return normalizeContact(contactId, info, botJid, contract, store, botLid);
         },
     };
 }
@@ -961,7 +1161,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,
@@ -1472,8 +1675,45 @@ 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) {
+    const me = contract.me();
+    const botJid = me.id ? normalizeJid(jidNormalizedUser(me.id)) : null;
+    const botLid = me.lid ? normalizeJid(me.lid) : null;
+    /**
+     * 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.");
@@ -1503,7 +1743,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 }));
         }
     }
     /**
@@ -1518,16 +1758,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);
             },
@@ -1542,22 +1801,31 @@ 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]);
+            if (users.some((u) => {
+                const n = normalizeJid(u);
+                return (botJid && n === botJid) || (botLid && n === botLid);
+            })) {
+                throw new Error(t("driver.cannotKickSelf"));
+            }
+            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) {
@@ -1765,7 +2033,7 @@ function buildPollApi(contract, store, rawJid, guardOptions, pluginName) {
                     handle._updateFromAggregated(aggregated);
                 }
                 catch (err) {
-                    logger.error(`[poll] erro ao decriptar voto: ${err}`);
+                    logger.error(`[poll] ${t("driver.pollDecryptFailed", { error: err })}`);
                 }
             }
         });
@@ -1819,7 +2087,9 @@ function buildPollApi(contract, store, rawJid, guardOptions, pluginName) {
 }
 // ── Base API (shared between setup and runtime) ───────────────────────────────
 function buildBaseApi(contract, store, pluginRegistry, pluginName) {
-    const botJid = contract.me().id ? jidNormalizedUser(contract.me().id) : null;
+    const me = contract.me();
+    const botJid = me.id ? jidNormalizedUser(me.id) : null;
+    const botLid = me.lid ? normalizeJid(me.lid) : null;
     if (!botJid)
         logger.warn("[pluginApi] botId is null — socket may not be ready yet.");
     return {
@@ -1832,9 +2102,10 @@ function buildBaseApi(contract, store, pluginRegistry, pluginName) {
         scheduler: buildSchedulerApi(pluginName),
         plugins: buildPluginsApi(pluginRegistry),
         chats: buildChatsApi(store),
-        contacts: buildContactsApi(contract, store, botJid),
+        contacts: buildContactsApi(contract, store, botJid, botLid),
         storage: buildStorageApi(pluginName),
-        botId: botJid,
+        botId: botLid ?? botJid,
+        commands: buildCommandsApi(),
     };
 }
 // ── Setup API ─────────────────────────────────────────────────────────────────
@@ -1852,12 +2123,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.
@@ -1873,7 +2184,7 @@ export function buildSetupApi(contract, store, pluginRegistry, pluginName) {
  * @param {object}          [params.guardOptions]
  */
 export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginName, guardOptions = {}, }) {
-    const prefix = CONFIG.CMD_PREFIX;
+    const prefix = getChatPrefix(msg.chatId);
     const body = getMsgBody(msg);
     const rawArgs = body.trim().split(/\s+/);
     const first = rawArgs[0]?.toLowerCase() ?? "";
@@ -1881,7 +2192,7 @@ export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginNam
     const command = hasPrefix ? first.slice(prefix.length) : "";
     const rawJid = msg.chatId;
     const normJid = normalizeJid(rawJid);
-    const sender = getMsgSender(msg, store);
+    const sender = getMsgSender(msg);
     const cooldown = (guardOptions.cooldown ?? true);
     const jitter = (guardOptions.jitter ?? true);
     bindGroupMetaInvalidation(contract);
@@ -1907,6 +2218,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 ─────────────────────────────────────────────────────────────────
@@ -1949,6 +2262,9 @@ export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginNam
             },
             /**
              * Check if a contact is an admin of this group.
+             * Always fetches fresh (bypasses the group-metadata TTL cache) —
+             * this gates the `admin:` command permission, so it cannot risk
+             * serving a stale "still admin" result after a demote.
              * @param {string} contactId
              * @returns {Promise<boolean>}
              */
@@ -1956,7 +2272,7 @@ export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginNam
                 if (!chat.isGroup)
                     return false;
                 try {
-                    const meta = await getGroupMetadataCached(contract, rawJid);
+                    const meta = await getGroupMetadataFresh(contract, rawJid);
                     return meta.participants.some(p => matchesParticipant([contactId], p.id) && (p.admin === "admin" || p.admin === "superadmin"));
                 }
                 catch {
@@ -1965,13 +2281,16 @@ export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginNam
             },
             /**
              * Check if the message sender is an admin of this group.
+             * Always fetches fresh (bypasses the group-metadata TTL cache) — see
+             * {@link isAdmin} for why: this gates the `botAdmin:`/`admin:`
+             * permission checks in commandPermissions.ts.
              * @returns {Promise<boolean>}
              */
             async isSenderAdmin() {
                 if (!chat.isGroup)
                     return false;
                 try {
-                    const meta = await getGroupMetadataCached(contract, rawJid);
+                    const meta = await getGroupMetadataFresh(contract, rawJid);
                     // The adapter's pre-extracted participant fields give us both the
                     // LID and PN forms of the sender; match either against the group's
                     // own participant list.
@@ -1984,6 +2303,9 @@ export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginNam
             },
             /**
              * Check if the bot is an admin of this group.
+             * Always fetches fresh (bypasses the group-metadata TTL cache) — see
+             * {@link isAdmin} for why: this gates the `botAdmin:` permission
+             * check in commandPermissions.ts.
              * @returns {Promise<boolean>}
              */
             async isBotAdmin() {
@@ -1995,7 +2317,7 @@ export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginNam
                 if (!botCandidates.some(Boolean))
                     return false;
                 try {
-                    const meta = await getGroupMetadataCached(contract, rawJid);
+                    const meta = await getGroupMetadataFresh(contract, rawJid);
                     return meta.participants.some(p => matchesParticipant(botCandidates, p.id) && (p.admin === "admin" || p.admin === "superadmin"));
                 }
                 catch {
@@ -2008,7 +2330,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 ──────────────────────────────────────────────────────────────────