Problem or Use Case

Currently, the Hermes Discord gateway operates in a passive responder mode — it can only receive and respond to messages sent directly via DM or @mention in real-time. This limitation prevents Hermes from being a true Discord server assistant.

Current Limitations

• Cannot read messages sent while offline or before session start
• No access to channel history for context gathering
• Cannot create/manage channels, roles, or server settings
• Unable to send proactive messages (only reactive responses)
• No voice channel capabilities
• Cannot access message reactions, embeds, or attachments from historical messages

Use Cases This Would Enable

• Context Recovery: "What did I ask you to do yesterday in #general?" — Retrieve tasks or requests from previous conversations without the user having to repeat themselves.
• Channel Monitoring: "Summarize the last 50 messages in #project-discussion" — Stay informed on active conversations without constant presence.
• Resource Aggregation: "Find all GitHub links shared in #resources this week" — Automatically collect and organize shared resources.
• Server Administration: "Create a new channel called 'meeting-notes' under the Work category" — Automate server organization.
• Member Management: "Give @new-hires the 'Onboarding' role" — Streamline onboarding workflows.
• Scheduled Communications: Post daily briefings or weekly digests to #announcements without manual triggering.
• Voice Participation: Join voice channels for audio briefings during travel (road mode).

This upgrade would transform Hermes from a simple chat responder into a full Discord server management assistant, enabling workflows like:

• "Review the last 20 messages in #pull-requests and summarize what needs my attention"
• "Create channels for the 5 new projects we discussed yesterday"
• "Post the weekly status report to #announcements every Monday at 9am"
• "Find all unanswered questions in #help from the last 24 hours"

The configuration-first approach ensures users can opt into only the features they need, maintaining security while enabling powerful automation.

Proposed Solution

A comprehensive upgrade to the Discord gateway enabling full bidirectional server interaction with granular configuration.

1. Message History & Context Access

Behavior:

• Fetch historical messages from any channel where the bot has READ_MESSAGE_HISTORY permission
• Retrieve messages by:
  • Time range (last N messages, since timestamp, between dates)
  • Keyword/phrase search
  • Author filter
  • Message type filter (regular, pinned, system)
• Access message metadata: reactions, embeds, attachments, edit history
• Read thread and forum post content
• Cache recently accessed history for efficient context window building

CLI Flags:

hermes gateway discord --history-cache-ttl=3600 --max-history-fetch=1000

Config Options:

discord:
  gateway_mode: "full"  # "minimal" (current) or "full" (this proposal)
  history:
    cache_ttl_seconds: 3600
    max_fetch_per_request: 1000
    enable_search_indexing: true

2. Channel Management

Behavior:

• Create text channels, voice channels, stage channels, and forums
• Delete/archive channels with confirmation
• Modify channel properties:
  • Name, topic/description
  • Slow mode settings
  • NSFW flag
  • Category assignment
  • Position ordering
• Manage channel permissions (overwrite roles/users)
• Create channel categories and organize channels within them

CLI Flags:

hermes gateway discord --allow-channel-management=true --confirm-destructive-actions=true

Config Options:

discord:
  channel_management:
    enabled: true
    allow_creation: true
    allow_deletion: true  # requires confirmation
    allow_permission_changes: true
    max_channels_per_command: 10  # rate limiting

3. Server Administration

Behavior:

• Role Management:
  • Create/edit/delete roles
  • Modify role permissions, color, hoist status
  • Assign/remove roles from members
• Member Management:
  • Kick, ban, unban, timeout members
  • Fetch member list with filtering
  • View member activity/status
• Server Settings:
  • Edit server name, icon, banner
  • Modify verification level and explicit content filter
  • Manage server invites (create, revoke, list)
• Audit Access: Read server audit log for accountability

CLI Flags:

hermes gateway discord --allow-moderation=true --allow-role-management=true

Config Options:

discord:
  administration:
    enabled: true
    role_management:
      allowed: true
      max_roles_per_command: 5
    member_moderation:
      kick_allowed: true
      ban_allowed: true
      timeout_allowed: true
      require_reason: true
    invite_management: true

4. Proactive Messaging & Interaction

Behavior:

• Send messages to any accessible channel without requiring a direct prompt
• Edit/delete previously sent bot messages
• Pin/unpin messages in channels
• Add/remove reactions to messages
• Reply to specific messages with threaded context
• Send rich embeds, files, and formatted messages

Config Options:

discord:
  proactive_messaging:
    enabled: true
    allowed_channels: ["announcements", "general", "bot-commands"]  # whitelist or "all"
    require_approval_for: ["announcements"]  # channels needing explicit approval
    max_daily_proactive: 50  # rate limit

5. Voice Channel Integration

Behavior:

• Join/leave voice channels programmatically
• Stream audio (TTS responses, audio file playback)
• Record audio from voice channels (with explicit consent/permissions)
• Manage voice channel settings (user limit, bitrate, region)
• Detect voice state changes (who joined/left)

CLI Flags:

hermes gateway discord --enable-voice=true --voice-recording-consent=explicit

Config Options:

discord:
  voice:
    enabled: true
    auto_join_on_request: true
    allow_recording: true
    recording_consent_mode: "explicit"  # "explicit", "implicit", "none"
    max_recording_duration_minutes: 60

6. Thread & Forum Management

Behavior:

• Create threads from existing messages
• Create standalone threads in thread-enabled channels
• Archive/unarchive threads
• Join/leave threads
• Manage forum posts (create, delete, tag management)
• Set thread auto-archive duration

Config Options:

discord:
  thread_management:
    enabled: true
    auto_archive_threads_after_days: 3
    allow_forum_post_creation: true

7. Event & Scheduling

Behavior:

• Create Discord events (scheduled voice/text events)
• Modify event details (time, description, cover image)
• List upcoming server events
• Delete/cancel events

Config Options:

discord:
  event_management:
    enabled: true
    default_event_duration_hours: 1

Required Discord Intents

The bot would need the following privileged intents enabled in the Discord Developer Portal:

• GUILD_MEMBERS — For member list and role management
• MESSAGE_CONTENT — For reading message content (now privileged)
• GUILD_PRESENCES — For presence/activity data (optional)

Required Bot Permissions

• MANAGE_CHANNELS — Channel creation/deletion/editing
• MANAGE_ROLES — Role management
• MANAGE_MESSAGES — Delete messages, pin/unpin
• MANAGE_GUILD — Server settings, invite management
• MODERATE_MEMBERS — Timeout members
• KICK_MEMBERS / BAN_MEMBERS — Member moderation
• VIEW_AUDIT_LOG — Read audit log
• CONNECT / SPEAK — Voice channel access
• Additional standard permissions: SEND_MESSAGES, READ_MESSAGE_HISTORY, etc.

API Endpoints to Implement

• GET /channels/{channel.id}/messages — Fetch message history
• POST /channels/{channel.id}/messages — Send proactive messages
• POST /guilds/{guild.id}/channels — Create channels
• PATCH /channels/{channel.id} — Modify channels
• POST /guilds/{guild.id}/roles — Create roles
• PUT /guilds/{guild.id}/members/{user.id}/roles/{role.id} — Assign roles
• PUT /guilds/{guild.id}/bans/{user.id} — Ban members
• POST /channels/{channel.id}/invites — Create invites
• POST /channels/{channel.id}/threads — Create threads

Security & Privacy Considerations

1. Permission Scoping: All actions respect Discord's permission hierarchy — Hermes cannot perform actions the bot role lacks permission for
2. Audit Logging: All administrative actions logged with:
   • Requester user ID
   • Action taken
   • Timestamp
   • Discord's native audit log reflects changes
3. User Confirmation: Destructive actions (delete channel, ban user) require explicit confirmation
4. Rate Limiting: Implement Discord rate limit handling (429 responses with retry-after headers)
5. Data Retention: Message history caching respects privacy — configurable retention limits

Global Configuration Example

discord:
  # Gateway mode selection
  gateway_mode: "full"  # "minimal" | "full"
  
  # History settings
  history:
    cache_ttl_seconds: 3600
    max_fetch_per_request: 1000
    enable_search_indexing: true
  
  # Feature toggles
  channel_management:
    enabled: true
    allow_deletion: true
    confirm_destructive: true
  
  administration:
    enabled: true
    role_management: true
    member_moderation:
      kick: true
      ban: true
      timeout: true
  
  proactive_messaging:
    enabled: true
    allowed_channels: "all"  # or list ["general", "bot-commands"]
  
  voice:
    enabled: true
    allow_recording: true
    recording_consent: "explicit"
  
  thread_management:
    enabled: true
  
  event_management:
    enabled: true

Acceptance Criteria

• Bot can fetch and display last N messages from any accessible channel
• Bot can search channel history by keyword/author/date
• Bot can create/delete text and voice channels
• Bot can create/edit/delete roles and assign them to members
• Bot can kick/ban/timeout members with appropriate permissions
• Bot can send messages to any channel without being directly prompted
• Bot can join voice channels and stream audio
• Bot can create/manage threads and forum posts
• All administrative actions are logged and require confirmation where destructive
• Permission errors are gracefully handled with clear user feedback

Alternatives Considered

Alternative 1: Webhook-Based Integration

Description: Use Discord webhooks for posting messages instead of a bot connection.
Pros:

• Simpler to set up
• No need for privileged intents
• Lower permission requirements

Cons:

• Cannot read channel history
• Cannot perform administrative actions
• Only supports sending messages, not full bidirectional communication
• No voice capabilities
• Rejected Because: Doesn't solve the core problem of context access and server management.

Alternative 2: Discord-Only Mode with Separate Bot Account

Description: Create a separate "Hermes-Admin" bot for management features, keeping the main responder lightweight.
Pros:

• Separation of concerns
• Can limit admin bot to specific servers
• Reduces risk of accidental admin actions

Cons:

• User confusion (two bots to interact with)
• Duplicate configuration
• Complex synchronization between bot instances
• Doesn't reduce intent requirements
• Rejected Because: Poor UX and unnecessary complexity; a single well-configured bot is cleaner.

Alternative 3: Minimal Permission Escalation

Description: Only request additional permissions when needed, prompt user to add them dynamically.
Pros:

• Principle of least privilege
• Users opt-in to specific features
• Lower barrier to entry

Cons:

• Complex implementation (dynamic permission checking)
• Poor UX (constant permission prompts)
• Discord doesn't support dynamic permission addition without re-invite
• Partially Accepted: Implemented via granular config options, but bot invites still require upfront permission specification.

Alternative 4: External Discord Client Integration

Description: Connect to user's personal Discord client instead of bot account.
Pros:

• Inherits user's permissions directly
• No bot setup required
• Can access DMs and private servers

Cons:

• Violates Discord ToS (automating user accounts)
• Requires Discord client modifications
• Security risk (requires user's token)
• Not scalable or officially supported
• Rejected Because: Violates Discord Terms of Service and poses security risks.

Alternative 5: Read-Only History, No Administration

Description: Add message history access but skip channel/server management features.
Pros:

• Simpler implementation
• Lower permission requirements
• Reduced security surface area

Cons:

• Doesn't enable full server assistant use cases
• Users still need manual intervention for organization tasks
• Half-measure that limits utility
• Rejected Because: Doesn't fulfill the vision of a comprehensive Discord assistant; admin features are frequently requested.

Feature Type

New tool

Scope

Large (new module or significant refactor)

Contribution

• I'd like to implement this myself and submit a PR