Zakaria/hermes-agent
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Hermes-agent

Browse Source
This commit is contained in:
Zakaria
2026-06-14 14:30:48 -04:00
commit dac4b88b94
5058 changed files with 1884848 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/discord_tool.py
+959
View File
@@ -0,0 +1,959 @@
"""Discord server introspection and management tool.
Provides the agent with the ability to interact with Discord servers
when running on the Discord gateway. Uses Discord REST API directly
with the bot token — no dependency on the gateway adapter's client.
Only included in the hermes-discord toolset, so it has zero cost
for users on other platforms.
The schema exposed to the model is filtered by two gates:
1. Privileged intents detected from GET /applications/@me at schema
build time. Actions that require an intent the bot doesn't have
(search_members / member_info → GUILD_MEMBERS intent) are hidden.
fetch_messages is kept regardless of MESSAGE_CONTENT intent, but
its description is annotated when the intent is missing.
2. User config allowlist at ``discord.server_actions``. If the user
sets a comma-separated list (or YAML list) of action names, only
those appear in the schema. Empty/unset means all intent-available
actions are exposed.
Per-guild permissions (MANAGE_ROLES etc.) are NOT pre-checked — Discord
returns a 403 at call time and :func:`_enrich_403` maps it to
actionable guidance the model can relay to the user.
"""
import json
import logging
import os
import urllib.error
import urllib.parse
import urllib.request
from typing import Any, Dict, List, Optional, Tuple
from tools.registry import registry
logger = logging.getLogger(__name__)
DISCORD_API_BASE = "https://discord.com/api/v10"
# Application flag bits (from GET /applications/@me → "flags").
# Source: https://discord.com/developers/docs/resources/application#application-object-application-flags
_FLAG_GATEWAY_GUILD_MEMBERS = 1 << 14
_FLAG_GATEWAY_GUILD_MEMBERS_LIMITED = 1 << 15
_FLAG_GATEWAY_MESSAGE_CONTENT = 1 << 18
_FLAG_GATEWAY_MESSAGE_CONTENT_LIMITED = 1 << 19
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _get_bot_token() -> Optional[str]:
"""Resolve the Discord bot token from environment."""
return os.getenv("DISCORD_BOT_TOKEN", "").strip() or None
def _discord_request(
method: str,
path: str,
token: str,
params: Optional[Dict[str, str]] = None,
body: Optional[Dict[str, Any]] = None,
timeout: int = 15,
) -> Any:
"""Make a request to the Discord REST API."""
url = f"{DISCORD_API_BASE}{path}"
if params:
url += "?" + urllib.parse.urlencode(params)
data = None
if body is not None:
data = json.dumps(body).encode("utf-8")
req = urllib.request.Request(
url,
data=data,
method=method,
headers={
"Authorization": f"Bot {token}",
"Content-Type": "application/json",
"User-Agent": "Hermes-Agent (https://github.com/NousResearch/hermes-agent)",
},
)
try:
with urllib.request.urlopen(req, timeout=timeout) as resp:
if resp.status == 204:
return None
return json.loads(resp.read().decode("utf-8"))
except urllib.error.HTTPError as e:
error_body = ""
try:
error_body = e.read().decode("utf-8", errors="replace")
except Exception:
pass
raise DiscordAPIError(e.code, error_body) from e
class DiscordAPIError(Exception):
"""Raised when a Discord API call fails."""
def __init__(self, status: int, body: str):
self.status = status
self.body = body
super().__init__(f"Discord API error {status}: {body}")
# ---------------------------------------------------------------------------
# Channel type mapping
# ---------------------------------------------------------------------------
_CHANNEL_TYPE_NAMES = {
0: "text",
2: "voice",
4: "category",
5: "announcement",
10: "announcement_thread",
11: "public_thread",
12: "private_thread",
13: "stage",
15: "forum",
16: "media",
}
def _channel_type_name(type_id: int) -> str:
return _CHANNEL_TYPE_NAMES.get(type_id, f"unknown({type_id})")
# ---------------------------------------------------------------------------
# Capability detection (application intents)
# ---------------------------------------------------------------------------
# Module-level cache so the app/me endpoint is hit at most once per process.
_capability_cache: Dict[str, Dict[str, Any]] = {}
def _detect_capabilities(token: str, *, force: bool = False) -> Dict[str, Any]:
"""Detect the bot's app-wide capabilities via GET /applications/@me.
Returns a dict with keys:
- ``has_members_intent``: GUILD_MEMBERS intent is enabled
- ``has_message_content``: MESSAGE_CONTENT intent is enabled
- ``detected``: detection succeeded (False means exposing everything
and letting runtime errors handle it)
Cached in a module-global. Pass ``force=True`` to re-fetch.
"""
global _capability_cache
if token in _capability_cache and not force:
return _capability_cache[token]
caps: Dict[str, Any] = {
"has_members_intent": True,
"has_message_content": True,
"detected": False,
}
try:
app = _discord_request("GET", "/applications/@me", token, timeout=5)
flags = int(app.get("flags", 0) or 0)
caps["has_members_intent"] = bool(
flags & (_FLAG_GATEWAY_GUILD_MEMBERS | _FLAG_GATEWAY_GUILD_MEMBERS_LIMITED)
)
caps["has_message_content"] = bool(
flags & (_FLAG_GATEWAY_MESSAGE_CONTENT | _FLAG_GATEWAY_MESSAGE_CONTENT_LIMITED)
)
caps["detected"] = True
except Exception as exc: # nosec — detection is best-effort
logger.info(
"Discord capability detection failed (%s); exposing all actions.", exc,
)
_capability_cache[token] = caps
return caps
def _reset_capability_cache() -> None:
"""Test hook: clear the detection cache."""
global _capability_cache
_capability_cache = {}
# ---------------------------------------------------------------------------
# Action implementations
# ---------------------------------------------------------------------------
def _list_guilds(token: str, **_kwargs: Any) -> str:
"""List all guilds the bot is a member of."""
guilds = _discord_request("GET", "/users/@me/guilds", token)
result = []
for g in guilds:
result.append({
"id": g["id"],
"name": g["name"],
"icon": g.get("icon"),
"owner": g.get("owner", False),
"permissions": g.get("permissions"),
})
return json.dumps({"guilds": result, "count": len(result)})
def _server_info(token: str, guild_id: str, **_kwargs: Any) -> str:
"""Get detailed information about a guild."""
g = _discord_request("GET", f"/guilds/{guild_id}", token, params={"with_counts": "true"})
return json.dumps({
"id": g["id"],
"name": g["name"],
"description": g.get("description"),
"icon": g.get("icon"),
"owner_id": g.get("owner_id"),
"member_count": g.get("approximate_member_count"),
"online_count": g.get("approximate_presence_count"),
"features": g.get("features", []),
"premium_tier": g.get("premium_tier"),
"premium_subscription_count": g.get("premium_subscription_count"),
"verification_level": g.get("verification_level"),
})
def _list_channels(token: str, guild_id: str, **_kwargs: Any) -> str:
"""List all channels in a guild, organized by category."""
channels = _discord_request("GET", f"/guilds/{guild_id}/channels", token)
# Organize: categories first, then channels under each
categories: Dict[Optional[str], Dict[str, Any]] = {}
uncategorized: List[Dict[str, Any]] = []
# First pass: collect categories
for ch in channels:
if ch["type"] == 4: # category
categories[ch["id"]] = {
"id": ch["id"],
"name": ch["name"],
"position": ch.get("position", 0),
"channels": [],
}
# Second pass: assign channels to categories
for ch in channels:
if ch["type"] == 4:
continue
entry = {
"id": ch["id"],
"name": ch.get("name", ""),
"type": _channel_type_name(ch["type"]),
"position": ch.get("position", 0),
"topic": ch.get("topic"),
"nsfw": ch.get("nsfw", False),
}
parent = ch.get("parent_id")
if parent and parent in categories:
categories[parent]["channels"].append(entry)
else:
uncategorized.append(entry)
# Sort
sorted_cats = sorted(categories.values(), key=lambda c: c["position"])
for cat in sorted_cats:
cat["channels"].sort(key=lambda c: c["position"])
uncategorized.sort(key=lambda c: c["position"])
result: List[Dict[str, Any]] = []
if uncategorized:
result.append({"category": None, "channels": uncategorized})
for cat in sorted_cats:
result.append({
"category": {"id": cat["id"], "name": cat["name"]},
"channels": cat["channels"],
})
total = sum(len(group["channels"]) for group in result)
return json.dumps({"channel_groups": result, "total_channels": total})
def _channel_info(token: str, channel_id: str, **_kwargs: Any) -> str:
"""Get detailed info about a specific channel."""
ch = _discord_request("GET", f"/channels/{channel_id}", token)
return json.dumps({
"id": ch["id"],
"name": ch.get("name"),
"type": _channel_type_name(ch["type"]),
"guild_id": ch.get("guild_id"),
"topic": ch.get("topic"),
"nsfw": ch.get("nsfw", False),
"position": ch.get("position"),
"parent_id": ch.get("parent_id"),
"rate_limit_per_user": ch.get("rate_limit_per_user", 0),
"last_message_id": ch.get("last_message_id"),
})
def _list_roles(token: str, guild_id: str, **_kwargs: Any) -> str:
"""List all roles in a guild."""
roles = _discord_request("GET", f"/guilds/{guild_id}/roles", token)
result = []
for r in sorted(roles, key=lambda r: r.get("position", 0), reverse=True):
result.append({
"id": r["id"],
"name": r["name"],
"color": f"#{r.get('color', 0):06x}" if r.get("color") else None,
"position": r.get("position", 0),
"mentionable": r.get("mentionable", False),
"managed": r.get("managed", False),
"member_count": r.get("member_count"),
"hoist": r.get("hoist", False),
})
return json.dumps({"roles": result, "count": len(result)})
def _member_info(token: str, guild_id: str, user_id: str, **_kwargs: Any) -> str:
"""Get info about a specific guild member."""
m = _discord_request("GET", f"/guilds/{guild_id}/members/{user_id}", token)
user = m.get("user", {})
return json.dumps({
"user_id": user.get("id"),
"username": user.get("username"),
"display_name": user.get("global_name"),
"nickname": m.get("nick"),
"avatar": user.get("avatar"),
"bot": user.get("bot", False),
"roles": m.get("roles", []),
"joined_at": m.get("joined_at"),
"premium_since": m.get("premium_since"),
})
def _search_members(token: str, guild_id: str, query: str, limit: int = 20, **_kwargs: Any) -> str:
"""Search for guild members by name."""
try:
limit = int(limit)
except (TypeError, ValueError):
limit = 20
params = {"query": query, "limit": str(min(limit, 100))}
members = _discord_request("GET", f"/guilds/{guild_id}/members/search", token, params=params)
result = []
for m in members:
user = m.get("user", {})
result.append({
"user_id": user.get("id"),
"username": user.get("username"),
"display_name": user.get("global_name"),
"nickname": m.get("nick"),
"bot": user.get("bot", False),
"roles": m.get("roles", []),
})
return json.dumps({"members": result, "count": len(result)})
def _fetch_messages(
token: str, channel_id: str, limit: int = 50,
before: Optional[str] = None, after: Optional[str] = None,
**_kwargs: Any,
) -> str:
"""Fetch recent messages from a channel."""
try:
limit = int(limit)
except (TypeError, ValueError):
limit = 50
params: Dict[str, str] = {"limit": str(min(limit, 100))}
if before:
params["before"] = before
if after:
params["after"] = after
messages = _discord_request("GET", f"/channels/{channel_id}/messages", token, params=params)
result = []
for msg in messages:
author = msg.get("author", {})
result.append({
"id": msg["id"],
"content": msg.get("content", ""),
"author": {
"id": author.get("id"),
"username": author.get("username"),
"display_name": author.get("global_name"),
"bot": author.get("bot", False),
},
"timestamp": msg.get("timestamp"),
"edited_timestamp": msg.get("edited_timestamp"),
"attachments": [
{"filename": a.get("filename"), "url": a.get("url"), "size": a.get("size")}
for a in msg.get("attachments", [])
],
"reactions": [
{"emoji": r.get("emoji", {}).get("name"), "count": r.get("count", 0)}
for r in msg.get("reactions", [])
] if msg.get("reactions") else [],
"pinned": msg.get("pinned", False),
})
return json.dumps({"messages": result, "count": len(result)})
def _list_pins(token: str, channel_id: str, **_kwargs: Any) -> str:
"""List pinned messages in a channel."""
messages = _discord_request("GET", f"/channels/{channel_id}/pins", token)
result = []
for msg in messages:
author = msg.get("author", {})
result.append({
"id": msg["id"],
"content": msg.get("content", "")[:200], # Truncate for overview
"author": author.get("username"),
"timestamp": msg.get("timestamp"),
})
return json.dumps({"pinned_messages": result, "count": len(result)})
def _pin_message(token: str, channel_id: str, message_id: str, **_kwargs: Any) -> str:
"""Pin a message in a channel."""
_discord_request("PUT", f"/channels/{channel_id}/pins/{message_id}", token)
return json.dumps({"success": True, "message": f"Message {message_id} pinned."})
def _unpin_message(token: str, channel_id: str, message_id: str, **_kwargs: Any) -> str:
"""Unpin a message from a channel."""
_discord_request("DELETE", f"/channels/{channel_id}/pins/{message_id}", token)
return json.dumps({"success": True, "message": f"Message {message_id} unpinned."})
def _delete_message(token: str, channel_id: str, message_id: str, **_kwargs: Any) -> str:
"""Delete a message from a channel or thread."""
_discord_request("DELETE", f"/channels/{channel_id}/messages/{message_id}", token)
return json.dumps({"success": True, "message": f"Message {message_id} deleted."})
def _create_thread(
token: str, channel_id: str, name: str,
message_id: Optional[str] = None,
auto_archive_duration: int = 1440,
**_kwargs: Any,
) -> str:
"""Create a thread in a channel."""
if message_id:
# Create thread from an existing message
path = f"/channels/{channel_id}/messages/{message_id}/threads"
body: Dict[str, Any] = {
"name": name,
"auto_archive_duration": auto_archive_duration,
}
else:
# Create a standalone thread
path = f"/channels/{channel_id}/threads"
body = {
"name": name,
"auto_archive_duration": auto_archive_duration,
"type": 11, # PUBLIC_THREAD
}
thread = _discord_request("POST", path, token, body=body)
return json.dumps({
"success": True,
"thread_id": thread["id"],
"name": thread.get("name"),
})
def _add_role(token: str, guild_id: str, user_id: str, role_id: str, **_kwargs: Any) -> str:
"""Add a role to a guild member."""
_discord_request("PUT", f"/guilds/{guild_id}/members/{user_id}/roles/{role_id}", token)
return json.dumps({"success": True, "message": f"Role {role_id} added to user {user_id}."})
def _remove_role(token: str, guild_id: str, user_id: str, role_id: str, **_kwargs: Any) -> str:
"""Remove a role from a guild member."""
_discord_request("DELETE", f"/guilds/{guild_id}/members/{user_id}/roles/{role_id}", token)
return json.dumps({"success": True, "message": f"Role {role_id} removed from user {user_id}."})
# ---------------------------------------------------------------------------
# Action dispatch + metadata
# ---------------------------------------------------------------------------
_ACTIONS = {
"list_guilds": _list_guilds,
"server_info": _server_info,
"list_channels": _list_channels,
"channel_info": _channel_info,
"list_roles": _list_roles,
"member_info": _member_info,
"search_members": _search_members,
"fetch_messages": _fetch_messages,
"list_pins": _list_pins,
"pin_message": _pin_message,
"unpin_message": _unpin_message,
"delete_message": _delete_message,
"create_thread": _create_thread,
"add_role": _add_role,
"remove_role": _remove_role,
}
_CORE_ACTION_NAMES = frozenset({"fetch_messages", "search_members", "create_thread"})
_ADMIN_ACTION_NAMES = frozenset(_ACTIONS.keys()) - _CORE_ACTION_NAMES
_CORE_ACTIONS = {k: v for k, v in _ACTIONS.items() if k in _CORE_ACTION_NAMES}
_ADMIN_ACTIONS = {k: v for k, v in _ACTIONS.items() if k in _ADMIN_ACTION_NAMES}
# Single-source-of-truth manifest: action → (signature, one-line description).
# Consumed by :func:`_build_schema` so the schema's top-level description
# always matches the registered action set.
_ACTION_MANIFEST: List[Tuple[str, str, str]] = [
("list_guilds", "()", "list servers the bot is in"),
("server_info", "(guild_id)", "server details + member counts"),
("list_channels", "(guild_id)", "all channels grouped by category"),
("channel_info", "(channel_id)", "single channel details"),
("list_roles", "(guild_id)", "roles sorted by position"),
("member_info", "(guild_id, user_id)", "lookup a specific member"),
("search_members", "(guild_id, query)", "find members by name prefix"),
("fetch_messages", "(channel_id)", "recent messages; optional before/after snowflakes"),
("list_pins", "(channel_id)", "pinned messages in a channel"),
("pin_message", "(channel_id, message_id)", "pin a message"),
("unpin_message", "(channel_id, message_id)", "unpin a message"),
("delete_message", "(channel_id, message_id)", "delete a message"),
("create_thread", "(channel_id, name)", "create a public thread; optional message_id anchor"),
("add_role", "(guild_id, user_id, role_id)", "assign a role"),
("remove_role", "(guild_id, user_id, role_id)", "remove a role"),
]
# Actions that require the GUILD_MEMBERS privileged intent.
_INTENT_GATED_MEMBERS = frozenset({"member_info", "search_members"})
# Per-action required params for runtime validation.
_REQUIRED_PARAMS: Dict[str, List[str]] = {
"server_info": ["guild_id"],
"list_channels": ["guild_id"],
"list_roles": ["guild_id"],
"member_info": ["guild_id", "user_id"],
"search_members": ["guild_id", "query"],
"channel_info": ["channel_id"],
"fetch_messages": ["channel_id"],
"list_pins": ["channel_id"],
"pin_message": ["channel_id", "message_id"],
"unpin_message": ["channel_id", "message_id"],
"delete_message": ["channel_id", "message_id"],
"create_thread": ["channel_id", "name"],
"add_role": ["guild_id", "user_id", "role_id"],
"remove_role": ["guild_id", "user_id", "role_id"],
}
# ---------------------------------------------------------------------------
# Config-based action allowlist
# ---------------------------------------------------------------------------
def _load_allowed_actions_config() -> Optional[List[str]]:
"""Read ``discord.server_actions`` from user config.
Returns a list of allowed action names, or ``None`` if the user
hasn't restricted the set (default: all actions allowed).
Accepts either a comma-separated string or a YAML list.
Unknown action names are dropped with a log warning.
"""
try:
from hermes_cli.config import load_config
cfg = load_config()
except Exception as exc:
logger.debug("discord: could not load config (%s); allowing all actions.", exc)
return None
raw = (cfg.get("discord") or {}).get("server_actions")
if raw is None or raw == "":
return None
if isinstance(raw, str):
names = [n.strip() for n in raw.split(",") if n.strip()]
elif isinstance(raw, (list, tuple)):
names = [str(n).strip() for n in raw if str(n).strip()]
else:
logger.warning(
"discord.server_actions: unexpected type %s; ignoring.", type(raw).__name__,
)
return None
valid = [n for n in names if n in _ACTIONS]
invalid = [n for n in names if n not in _ACTIONS]
if invalid:
logger.warning(
"discord.server_actions: unknown action(s) ignored: %s. "
"Known: %s",
", ".join(invalid), ", ".join(_ACTIONS.keys()),
)
return valid
def _available_actions(
caps: Dict[str, Any],
allowlist: Optional[List[str]],
) -> List[str]:
"""Compute the visible action list from intents + config allowlist.
Preserves the canonical order from :data:`_ACTIONS`.
"""
actions: List[str] = []
for name in _ACTIONS:
# Intent filter
if not caps.get("has_members_intent", True) and name in _INTENT_GATED_MEMBERS:
continue
# Config allowlist filter
if allowlist is not None and name not in allowlist:
continue
actions.append(name)
return actions
# ---------------------------------------------------------------------------
# Schema construction
# ---------------------------------------------------------------------------
def _build_schema(
actions: List[str],
caps: Optional[Dict[str, Any]] = None,
tool_name: str = "discord",
) -> Optional[Dict[str, Any]]:
"""Build the tool schema for the given filtered action list.
Returns ``None`` when *actions* is empty — callers should drop the
tool from registration in that case.
"""
caps = caps or {}
if not actions:
return None
# Action manifest lines (action-first, parameter-scoped).
manifest_lines = [
f" {name}{sig} — {desc}"
for name, sig, desc in _ACTION_MANIFEST
if name in actions
]
manifest_block = "\n".join(manifest_lines)
content_note = ""
affected_actions = {"fetch_messages", "list_pins"} & set(actions)
if affected_actions and caps.get("detected") and caps.get("has_message_content") is False:
names = " and ".join(sorted(affected_actions))
content_note = (
f"\n\nNOTE: Bot does NOT have the MESSAGE_CONTENT privileged intent. "
f"{names} will return message metadata (author, "
"timestamps, attachments, reactions, pin state) but `content` will be "
"empty for messages not sent as a direct mention to the bot or in DMs. "
"Enable the intent in the Discord Developer Portal to see all content."
)
if tool_name == "discord_admin":
description = (
"Manage a Discord server via the REST API.\n\n"
"Available actions:\n"
f"{manifest_block}\n\n"
"Call list_guilds first to discover guild_ids, then list_channels for "
"channel_ids. Runtime errors will tell you if the bot lacks a specific "
"per-guild permission (e.g. MANAGE_ROLES for add_role)."
f"{content_note}"
)
else:
description = (
"Read and participate in a Discord server.\n\n"
"Available actions:\n"
f"{manifest_block}\n\n"
"Use the channel_id from the current conversation context. "
"Use search_members to look up user IDs by name prefix."
f"{content_note}"
)
properties: Dict[str, Any] = {
"action": {
"type": "string",
"enum": actions,
},
"guild_id": {
"type": "string",
"description": "Discord server (guild) ID.",
},
"channel_id": {
"type": "string",
"description": "Discord channel ID.",
},
"user_id": {
"type": "string",
"description": "Discord user ID.",
},
"role_id": {
"type": "string",
"description": "Discord role ID.",
},
"message_id": {
"type": "string",
"description": "Discord message ID.",
},
"query": {
"type": "string",
"description": "Member name prefix to search for (search_members).",
},
"name": {
"type": "string",
"description": "New thread name (create_thread).",
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Max results (default 50). Applies to fetch_messages, search_members.",
},
"before": {
"type": "string",
"description": "Snowflake ID for reverse pagination (fetch_messages).",
},
"after": {
"type": "string",
"description": "Snowflake ID for forward pagination (fetch_messages).",
},
"auto_archive_duration": {
"type": "integer",
"enum": [60, 1440, 4320, 10080],
"description": "Thread archive duration in minutes (create_thread, default 1440).",
},
}
return {
"name": tool_name,
"description": description,
"parameters": {
"type": "object",
"properties": properties,
"required": ["action"],
},
}
def _get_dynamic_schema(
action_subset: Dict[str, Any],
tool_name: str,
) -> Optional[Dict[str, Any]]:
"""Build a dynamic schema for *action_subset* filtered by intents + config."""
token = _get_bot_token()
if not token:
return None
caps = _detect_capabilities(token)
allowlist = _load_allowed_actions_config()
actions = [a for a in _available_actions(caps, allowlist) if a in action_subset]
if not actions:
return None
return _build_schema(actions, caps, tool_name=tool_name)
def get_dynamic_schema_core() -> Optional[Dict[str, Any]]:
return _get_dynamic_schema(_CORE_ACTIONS, "discord")
def get_dynamic_schema_admin() -> Optional[Dict[str, Any]]:
return _get_dynamic_schema(_ADMIN_ACTIONS, "discord_admin")
def get_dynamic_schema() -> Optional[Dict[str, Any]]:
"""Backward-compat wrapper — returns core schema."""
return get_dynamic_schema_core()
# ---------------------------------------------------------------------------
# 403 error enrichment
# ---------------------------------------------------------------------------
_ACTION_403_HINT = {
"pin_message": (
"Bot lacks MANAGE_MESSAGES permission in this channel. "
"Ask the server admin to grant the bot a role that has MANAGE_MESSAGES, "
"or a per-channel overwrite."
),
"unpin_message": (
"Bot lacks MANAGE_MESSAGES permission in this channel."
),
"delete_message": (
"Bot lacks MANAGE_MESSAGES permission in this channel, or cannot view the channel/message."
),
"create_thread": (
"Bot lacks CREATE_PUBLIC_THREADS in this channel, or cannot view it."
),
"add_role": (
"Either the bot lacks MANAGE_ROLES, or the target role sits higher "
"than the bot's highest role. Roles can only be assigned below the "
"bot's own position in the role hierarchy."
),
"remove_role": (
"Either the bot lacks MANAGE_ROLES, or the target role sits higher "
"than the bot's highest role."
),
"fetch_messages": (
"Bot cannot view this channel (missing VIEW_CHANNEL or READ_MESSAGE_HISTORY)."
),
"list_pins": (
"Bot cannot view this channel (missing VIEW_CHANNEL or READ_MESSAGE_HISTORY)."
),
"channel_info": (
"Bot cannot view this channel (missing VIEW_CHANNEL)."
),
"search_members": (
"Likely missing the Server Members privileged intent — enable it in the "
"Discord Developer Portal under your bot's settings."
),
"member_info": (
"Bot cannot see this guild member (missing Server Members intent or "
"insufficient permissions)."
),
}
def _enrich_403(action: str, body: str) -> str:
"""Return a user-friendly guidance string for a 403 on ``action``."""
hint = _ACTION_403_HINT.get(action)
base = f"Discord API 403 (forbidden) on '{action}'."
if hint:
return f"{base} {hint} (Raw: {body})"
return f"{base} (Raw: {body})"
# ---------------------------------------------------------------------------
# Check function
# ---------------------------------------------------------------------------
def check_discord_tool_requirements() -> bool:
"""Tool is available only when a Discord bot token is configured."""
return bool(_get_bot_token())
# ---------------------------------------------------------------------------
# Handlers
# ---------------------------------------------------------------------------
def _run_discord_action(
action: str,
valid_actions: Dict[str, Any],
tool_label: str,
guild_id: str = "",
channel_id: str = "",
user_id: str = "",
role_id: str = "",
message_id: str = "",
query: str = "",
name: str = "",
limit: int = 50,
before: str = "",
after: str = "",
auto_archive_duration: int = 1440,
) -> str:
"""Shared handler logic for both discord tools."""
token = _get_bot_token()
if not token:
return json.dumps({"error": "DISCORD_BOT_TOKEN not configured."})
action_fn = valid_actions.get(action)
if not action_fn:
return json.dumps({
"error": f"Unknown action: {action}",
"available_actions": list(valid_actions.keys()),
})
# Config-level allowlist gate (defense in depth — schema already filtered,
# but a stale cached schema from a prior config should not let denied
# actions through).
allowlist = _load_allowed_actions_config()
if allowlist is not None and action not in allowlist:
return json.dumps({
"error": (
f"Action '{action}' is disabled by config (discord.server_actions). "
f"Allowed: {', '.join(allowlist) if allowlist else '<none>'}"
),
})
local_vars = {
"guild_id": guild_id,
"channel_id": channel_id,
"user_id": user_id,
"role_id": role_id,
"message_id": message_id,
"query": query,
"name": name,
}
missing = [p for p in _REQUIRED_PARAMS.get(action, []) if not local_vars.get(p)]
if missing:
return json.dumps({
"error": f"Missing required parameters for '{action}': {', '.join(missing)}",
})
try:
return action_fn(
token=token,
guild_id=guild_id,
channel_id=channel_id,
user_id=user_id,
role_id=role_id,
message_id=message_id,
query=query,
name=name,
limit=limit,
before=before,
after=after,
auto_archive_duration=auto_archive_duration,
)
except DiscordAPIError as e:
logger.warning("Discord API error in %s action '%s': %s", tool_label, action, e)
if e.status == 403:
return json.dumps({"error": _enrich_403(action, e.body)})
return json.dumps({"error": str(e)})
except Exception as e:
logger.exception("Unexpected error in %s action '%s'", tool_label, action)
return json.dumps({"error": f"Unexpected error: {e}"})
def discord_core(action: str, **kwargs) -> str:
"""Execute a core Discord action (fetch_messages, search_members, create_thread)."""
return _run_discord_action(action, _CORE_ACTIONS, "discord", **kwargs)
def discord_admin_handler(action: str, **kwargs) -> str:
"""Execute a Discord admin action (server management)."""
return _run_discord_action(action, _ADMIN_ACTIONS, "discord_admin", **kwargs)
# ---------------------------------------------------------------------------
# Tool registration
# ---------------------------------------------------------------------------
_HANDLER_DEFAULTS = {
"action": "", "guild_id": "", "channel_id": "", "user_id": "",
"role_id": "", "message_id": "", "query": "", "name": "",
"limit": 50, "before": "", "after": "", "auto_archive_duration": 1440,
}
def _make_handler(handler_fn):
"""Create a registry-compatible handler lambda for a discord handler."""
return lambda args, **kw: handler_fn(
**{k: args.get(k, v) for k, v in _HANDLER_DEFAULTS.items()},
)
_STATIC_CORE_SCHEMA = _build_schema(
list(_CORE_ACTIONS.keys()), caps={"detected": False}, tool_name="discord",
)
_STATIC_ADMIN_SCHEMA = _build_schema(
list(_ADMIN_ACTIONS.keys()), caps={"detected": False}, tool_name="discord_admin",
)
registry.register(
name="discord",
toolset="discord",
schema=_STATIC_CORE_SCHEMA,
handler=_make_handler(discord_core),
check_fn=check_discord_tool_requirements,
requires_env=["DISCORD_BOT_TOKEN"],
)
registry.register(
name="discord_admin",
toolset="discord_admin",
schema=_STATIC_ADMIN_SCHEMA,
handler=_make_handler(discord_admin_handler),
check_fn=check_discord_tool_requirements,
requires_env=["DISCORD_BOT_TOKEN"],
)