hermes-agent/plugins/platforms/discord/onboarding.py

"""Discord onboarding: check a bot token against Discord and walk the user through setup.

The Developer Portal is where Discord setup goes wrong: a token copied from the wrong page, the
Message Content Intent left off (Discord then refuses the bot's connection), an invite URL built
by hand, and Developer Mode just to learn your own user ID. ``GET /applications/@me`` with the
bot token answers all of it at once — the token works, which intents are on, how many servers the
bot is in, and who owns the application — so the CLI wizard and the dashboard/Desktop check route
both read :func:`check_bot_token` instead of asking the user to verify those by hand.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Optional
from urllib.parse import urlencode

# Every permission the adapter exercises (text, threads, reactions, voice). Named so the integer
# in the invite link and the docs can be re-derived instead of trusted.
INVITE_PERMISSION_BITS = {
    "Add Reactions": 6,
    "View Channels": 10,
    "Send Messages": 11,
    "Embed Links": 14,
    "Attach Files": 15,
    "Read Message History": 16,
    "Connect": 20,
    "Speak": 21,
    "Create Public Threads": 35,
    "Send Messages in Threads": 38,
}
INVITE_PERMISSIONS = sum(1 << bit for bit in INVITE_PERMISSION_BITS.values())
_TEAM_MEMBER_ACCEPTED = 2


@dataclass(frozen=True)
class DiscordBotCheck:
    app_id: str
    bot_name: str
    # (user_id, username): the application owner, or every accepted member of the owning team.
    owners: tuple[tuple[str, str], ...]
    message_content: bool
    server_members: bool
    server_count: Optional[int]

    @property
    def invite_url(self) -> str:
        # integration_type=0 is a server install, so Discord skips the "add to server or to my
        # apps?" question for applications that also allow user installs.
        query = urlencode({"client_id": self.app_id, "scope": "bot applications.commands",
                           "permissions": INVITE_PERMISSIONS, "integration_type": 0})
        return f"https://discord.com/oauth2/authorize?{query}"

    @property
    def bot_settings_url(self) -> str:
        return f"https://discord.com/developers/applications/{self.app_id}/bot"


def _owners(app: dict) -> tuple[tuple[str, str], ...]:
    team = app.get("team")
    if isinstance(team, dict):
        return tuple(
            (str(m["user"]["id"]), str(m["user"].get("username") or m["user"]["id"]))
            for m in team.get("members") or []
            if m.get("membership_state") == _TEAM_MEMBER_ACCEPTED and m.get("user", {}).get("id")
        )
    owner = app.get("owner") or {}
    return ((str(owner["id"]), str(owner.get("username") or owner["id"])),) if owner.get("id") else ()


def check_bot_token(token: str) -> DiscordBotCheck:
    """Read the application behind ``token``. Raises :class:`DiscordAPIError` (401 = bad token)
    or ``OSError`` when Discord is unreachable."""
    from tools.discord_tool import _FLAGS_GUILD_MEMBERS, _FLAGS_MESSAGE_CONTENT, _discord_request
    app = _discord_request("GET", "/applications/@me", token.strip(), timeout=10)
    flags = int(app.get("flags") or 0)
    bot = app.get("bot") or {}
    count = app.get("approximate_guild_count")
    return DiscordBotCheck(
        app_id=str(app["id"]),
        bot_name=str(bot.get("username") or app.get("name") or app["id"]),
        owners=_owners(app),
        message_content=bool(flags & _FLAGS_MESSAGE_CONTENT),
        server_members=bool(flags & _FLAGS_GUILD_MEMBERS),
        server_count=count if isinstance(count, int) else None,
    )


# ── CLI wizard (hermes setup / hermes gateway setup) ─────────────────────────


def _clean_discord_user_ids(raw: str) -> list:
    """Strip common Discord mention prefixes from a comma-separated ID string."""
    cleaned = []
    for uid in raw.replace(" ", "").split(","):
        uid = uid.strip()
        if uid.startswith("<@") and uid.endswith(">"):
            uid = uid.lstrip("<@!").rstrip(">")
        if uid.lower().startswith("user:"):
            uid = uid[5:]
        if uid:
            cleaned.append(uid)
    return cleaned


def _discord_token_shape_error(token: str) -> Optional[str]:
    """Reject a Discord bot token that is really the numeric application ID.

    Users routinely paste the application ID from the Developer Portal's General Information page
    instead of the bot token (Bot page). A real bot token is dot-separated base64 and never purely
    numeric, so this is a safe, narrow shape check.
    """
    if token and token.strip().isdigit():
        return ("That looks like a numeric application ID, not a bot token. "
                "Paste the bot token from the Discord Developer Portal (Bot page), "
                "not the application ID (General Information page).")
    return None


def _prompt_discord_bot_token(prompt) -> str:
    """Prompt for the bot token, re-prompting once when the answer is a numeric app ID."""
    from hermes_cli.cli_output import print_error
    token = ""
    for _attempt in range(2):
        token = prompt("Discord bot token", password=True)
        if not token:
            return ""
        error = _discord_token_shape_error(token)
        if error is None:
            return token
        print_error(error)
    # Second consecutive numeric answer: trust the user, keep the value.
    return token


def _prompt_checked_token(prompt) -> tuple[str, Optional[DiscordBotCheck]]:
    """A token Discord accepted (with its check), an unverifiable one (offline: ``None`` check),
    or ``("", None)`` when the user gave up."""
    from hermes_cli.cli_output import print_error, print_success, print_warning
    from hermes_cli.config import _check_non_ascii_credential
    from tools.discord_tool import DiscordAPIError
    for _attempt in range(3):
        # Same stripping save_env_value applies, done first: a non-ASCII paste can't go in an HTTP header.
        token = _check_non_ascii_credential("DISCORD_BOT_TOKEN", _prompt_discord_bot_token(prompt)).strip()
        if not token:
            return "", None
        try:
            check = check_bot_token(token)
        except ValueError:  # whitespace/control characters inside the paste: not a header-safe token
            print_error("That isn't a bot token (it contains a line break). Copy it again from the Bot page.")
            continue
        except DiscordAPIError as exc:
            if exc.status == 401:
                print_error("Discord rejected that token. On the Bot page click Reset Token, "
                            "copy the new token and paste it here.")
                continue
            print_warning(f"Couldn't verify the token (Discord answered {exc.status}); saving it anyway.")
            return token, None
        except OSError as exc:
            print_warning(f"Couldn't reach Discord to verify the token ({exc}); saving it anyway.")
            return token, None
        print_success(f"Token works: this is the bot \"{check.bot_name}\"")
        return token, check
    print_error("Discord rejected three tokens in a row; nothing was saved.")
    return "", None


def _ensure_message_content_intent(token: str, check: DiscordBotCheck, prompt) -> DiscordBotCheck:
    from hermes_cli.cli_output import print_info, print_success, print_warning
    from tools.discord_tool import DiscordAPIError
    for _attempt in range(5):
        if check.message_content:
            break
        print_warning("Message Content Intent is OFF: Discord will refuse the bot's connection until it's on.")
        print_info(f"   Turn it on here: {check.bot_settings_url}")
        print_info("   (Privileged Gateway Intents → Message Content Intent → Save Changes)")
        if prompt("Press Enter once it's saved to re-check, or type 'skip'").strip().lower() == "skip":
            return check
        try:
            check = check_bot_token(token)
        except (DiscordAPIError, OSError):
            return check
    if check.message_content:
        print_success("Message Content Intent is on")
    if not check.server_members:
        print_info("Optional: turn on Server Members Intent on the same page if you want to "
                   "allow people by username or role instead of user ID.")
    return check


def _print_invite(check: DiscordBotCheck) -> None:
    from hermes_cli.cli_output import print_info
    print()
    if check.server_count == 0:
        print_info("📨 The bot isn't in any server yet. Open this link to add it to yours:")
    else:
        print_info("📨 Invite link (adds the bot to a server with the permissions Hermes uses):")
    print_info(f"   {check.invite_url}")
    print_info("   Once you share a server with the bot you can also DM it directly.")


def _prompt_allowlist(check: Optional[DiscordBotCheck], prompt, prompt_yes_no) -> None:
    from hermes_cli.cli_output import print_info, print_success
    from hermes_cli.config import get_env_value, save_env_value
    print()
    print_info("🔒 Security: only allowlisted Discord users can talk to your bot.")
    # Reconfiguring keeps whoever is already allowed; the wizard only adds.
    allowed = _clean_discord_user_ids(get_env_value("DISCORD_ALLOWED_USERS") or "")
    if allowed:
        print_info(f"   Already allowed: {', '.join(allowed)}")
    if check and check.owners and not all(uid in allowed for uid, _name in check.owners):
        who = ", ".join(f"@{name}" for _uid, name in check.owners)
        question = (f"Allow yourself ({who}) to talk to the bot?" if len(check.owners) == 1
                    else f"Allow your team ({who}) to talk to the bot?")
        if prompt_yes_no(question, True):
            allowed += [uid for uid, _name in check.owners if uid not in allowed]
    print_info("   Others need their Discord user ID: Settings → Advanced → Developer Mode,")
    print_info("   then right-click their name → Copy User ID. Usernames work too.")
    raw = prompt("Other allowed users (comma-separated, Enter to skip)" if allowed
                 else "Allowed user IDs or usernames (comma-separated, leave empty for open access)")
    extra = _clean_discord_user_ids(raw or "")
    allowed += [uid for uid in extra if uid not in allowed]
    if check and not check.server_members and any(not uid.isdigit() for uid in extra):
        print_info("   Usernames are resolved when the gateway connects, which needs Server Members Intent: "
                   f"{check.bot_settings_url}")
    if allowed:
        save_env_value("DISCORD_ALLOWED_USERS", ",".join(allowed))
        print_success("Discord allowlist configured")
    else:
        print_info(
            "⚠️  No allowlist set. Discord will deny messages until you set "
            "DISCORD_ALLOWED_USERS, DISCORD_ALLOWED_ROLES, DISCORD_ALLOWED_CHANNELS, "
            "or DISCORD_ALLOW_ALL_USERS=true for open access."
        )


def _check_saved_token(token: str) -> Optional[DiscordBotCheck]:
    from tools.discord_tool import DiscordAPIError
    try:
        return check_bot_token(token) if token else None
    except (DiscordAPIError, OSError):
        return None


def interactive_setup() -> None:
    """Guide the user through Discord bot setup: token (checked live), intents, invite link,
    allowlist (defaults to the bot's owner) and home channel. CLI imports are lazy."""
    from hermes_cli.cli_output import print_header, print_info, print_success, prompt, prompt_yes_no
    from hermes_cli.config import get_env_value, remove_env_value, save_env_value
    from hermes_cli.setup_platforms import declines_reconfigure

    print_header("Discord")
    if declines_reconfigure("Discord", "Reconfigure Discord?", "DISCORD_BOT_TOKEN"):
        if not get_env_value("DISCORD_ALLOWED_USERS"):
            print_info(
                "⚠️  Discord has no user allowlist. With the fail-closed default, "
                "messages are denied unless you configure allowed users, roles, "
                "or channels, or set DISCORD_ALLOW_ALL_USERS=true."
            )
            if prompt_yes_no("Add allowed users now?", True):
                saved = _check_saved_token(get_env_value("DISCORD_BOT_TOKEN") or "")
                _prompt_allowlist(saved, prompt, prompt_yes_no)
        return
    for line in (
        "1. Open https://discord.com/developers/applications → New Application",
        "2. Open the Bot page → Reset Token → copy the token",
        "Hermes checks the token, the intents and the invite link for you next.",
        "Guide: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord",
    ):
        print_info(line)
    token, check = _prompt_checked_token(prompt)
    if not token:
        return
    save_env_value("DISCORD_BOT_TOKEN", token)
    print_success("Discord token saved")
    if check is None:
        print_info("Make sure Message Content Intent is on (Bot page → Privileged Gateway Intents), "
                   "or Discord will refuse the bot's connection.")
    else:
        check = _ensure_message_content_intent(token, check, prompt)
        _print_invite(check)
    _prompt_allowlist(check, prompt, prompt_yes_no)
    print()
    for line in (
        "📬 Home Channel: where Hermes delivers cron job results,",
        "   cross-platform messages, and notifications.",
        "   Easiest: type /set-home in a Discord channel once the bot is running.",
        "   Or paste a channel ID (Developer Mode → right-click a channel → Copy Channel ID).",
    ):
        print_info(line)
    home_channel = prompt("Home channel ID (leave empty to set later with /set-home)").strip()
    if home_channel:
        save_env_value("DISCORD_HOME_CHANNEL", home_channel)
    elif remove_env_value("DISCORD_HOME_CHANNEL"):
        print_info("Home channel cleared.")