Orb Code Review (powered by GLM-4.7 on Orb Cloud)

Summary

This is a draft RFC/prototype PR proposing a richer Discord-native UX direction for Hermes. The implementation includes 56 files with 15,177 additions and 837 deletions, introducing a comprehensive Discord platform implementation with native slash commands, interactive components, and improved runtime control flows. As explicitly stated by the author, this is not a merge-ready PR but a working prototype to solicit feedback on the architectural direction.

Architecture

High-Level Overview

The prototype proposes a significant expansion of Discord platform capabilities:

New Discord Implementation Structure:

gateway/platforms/discord_impl/
├── components.py           # Reusable Discord UI components
├── config.py              # Discord configuration
├── delivery.py            # Message delivery handling
├── history.py             # Conversation history management
├── intake.py              # Message intake and processing
├── interactions.py        # User interaction handling
├── messaging.py           # Discord messaging
├── model_picker.py        # Interactive model selection
├── native_commands.py     # Native slash command runtime
├── permissions.py         # Discord permission handling
├── runtime_state.py       # Runtime state management
├── runtime_views.py       # Runtime view components
├── state.py               # State management
├── threads.py             # Discord thread handling
├── command_sessions.py    # Command session management
└── __init__.py

Core Features Proposed:

1. Native Slash Command Runtime: Full Discord slash command support
2. Rich Commands: Enhanced /status, /help, /commands, /whoami
3. Interactive Model Management: /model, /models, /model status
4. Reusable Components: Buttons, selects, modals for Discord UI
5. Approval Flows: Richer approval and runtime-control mechanisms
6. Thread/Session Control: Improved session and focus management

Architectural Changes

1. Command Catalog System (gateway/command_catalog.py):

• Centralized command registration and discovery
• Command metadata and documentation
• Permission and access control

2. Modular Discord Implementation:

• Separation of concerns (intake, delivery, messaging, etc.)
• Component-based UI architecture
• State management for complex interactions

3. Interactive Components (gateway/platforms/discord_impl/components.py):

• Reusable Discord UI components
• Button and select menu handlers
• Modal form support

4. Runtime State Management:

• Tracking command sessions
• Managing multi-step interactions
• State persistence and recovery

Issues

Critical Issues

None - This is a draft RFC, not a merge-ready PR.

Warnings

1. Massive Scope - Should Be Split

Issue: This PR touches 56 files with 15K+ lines of code, making it impossible to review thoroughly and dangerous to merge.

Impact:

• Cannot be reviewed effectively in single PR
• High risk of introducing bugs
• Difficult to test comprehensively
• Blocks other development

Suggested Approach:

Phase 1 - Foundation (Merge First):

• gateway/command_catalog.py - Command infrastructure
• gateway/channel_directory.py - Channel management
• Basic gateway/platforms/discord_impl/ structure

Phase 2 - Core Components:

• components.py - UI components
• config.py - Configuration
• permissions.py - Permission handling
• state.py - State management

Phase 3 - Messaging and Intake:

• intake.py - Message intake
• delivery.py - Message delivery
• messaging.py - Messaging
• history.py - History management

Phase 4 - Interactive Features:

• model_picker.py - Model selection
• runtime_views.py - Runtime views
• runtime_state.py - Runtime state
• threads.py - Thread handling

Phase 5 - Commands and Interactions:

• native_commands.py - Slash commands
• interactions.py - User interactions
• command_sessions.py - Session management

2. Missing Documentation and Design Decisions

Issue: The PR description is high-level but lacks detailed architectural documentation explaining:

• Design Rationale: Why this architecture? Alternatives considered?
• Data Models: How are sessions, threads, runtime state structured?
• Error Handling: How are errors handled in interactive flows?
• State Persistence: Where is state stored? How long does it persist?
• Concurrency: How are concurrent interactions handled?
• Backward Compatibility: How does this affect existing Discord functionality?

Suggested Additions:

Create docs/discord-ux-rfc.md:

# Discord UX RFC

## Overview

## Architecture

### Data Models

### State Management

### Error Handling

### Concurrency Model

### Migration Path

## Examples

## Testing Strategy

3. No Tests Included

Issue: With 15K+ lines of new code, there are no visible tests in the file list.

Impact:

• Cannot verify correctness
• High risk of regressions
• Difficult to maintain

Suggested Fix:

Add comprehensive test coverage:

tests/gateway/discord_impl/
├── test_components.py
├── test_model_picker.py
├── test_native_commands.py
├── test_runtime_state.py
├── test_interactions.py
└── test_command_sessions.py

4. Unclear Migration Path

Issue: The PR significantly refactors gateway/platforms/discord.py (+638/-546) but doesn't explain:

• How existing Discord functionality is preserved
• Whether this is a breaking change
• How users migrate from old to new implementation
• Whether old and new can coexist

Suggested Approach:

Option A: Incremental Migration

# Keep old implementation working
from gateway.platforms.discord import DiscordPlatform as OldDiscordPlatform
# Add new implementation
from gateway.platforms.discord_impl import DiscordPlatform as NewDiscordPlatform

# Feature flag to switch between implementations
USE_NEW_DISCORD = os.getenv('USE_NEW_DISCORD', 'false') == 'true'

DiscordPlatform = NewDiscordPlatform if USE_NEW_DISCORD else OldDiscordPlatform

Option B: Separate Implementation

• Keep existing discord.py as-is
• Add new discord_v2.py with new implementation
• Allow users to choose which version to use

5. Performance Considerations

Issue: With rich interactive components and state management, there are potential performance concerns:

• State Storage: Where is session state stored? Memory? Database?
• Concurrency: How are multiple simultaneous interactions handled?
• Memory Leaks: Are there cleanup mechanisms for abandoned sessions?
• Database Queries: Are interactive components causing N+1 queries?

Suggested Analysis:

# Document performance characteristics
# In docs/discord-ux-performance.md

## State Storage
- **Storage**: Redis (recommended) or in-memory
- **TTL**: 24 hours for inactive sessions
- **Cleanup**: Background task every hour

## Concurrency
- **Max concurrent sessions**: 100 per guild
- **Rate limiting**: 10 interactions/second per user
- **Queue**: FIFO queue for rate-limited requests

## Memory Usage
- **Average session size**: ~5KB
- **Max sessions**: 10,000 (50MB total)
- **Cleanup**: Expire after 24h inactivity

Suggestions

1. Create Incremental Migration Plan

Break down into mergeable PRs:

1. PR 1: Command catalog infrastructure (no user-visible changes)
2. PR 2: Basic Discord components (buttons, selects)
3. PR 3: Enhanced slash commands (/help, /status)
4. PR 4: Interactive model picker
5. PR 5: Runtime state management
6. PR 6: Advanced features (threads, approvals)

2. Add Design Document

Create comprehensive RFC document:

# Discord UX RFC

## Problem Statement

Current Discord integration limitations...

## Proposed Solution

### Architecture

### Component Design

### State Management

### Error Handling

## Migration Plan

### Phase 1: Foundation
### Phase 2: Core Features
### Phase 3: Advanced Features

## Risks and Mitigations

## Alternatives Considered

## Testing Strategy

## Performance Considerations

3. Implement Feature Flags

Allow gradual rollout:

# In config.py
class DiscordConfig:
    # Feature flags
    enable_native_commands: bool = False
    enable_interactive_components: bool = False
    enable_model_picker: bool = False
    enable_runtime_views: bool = False
    
    # Configuration
    max_concurrent_sessions: int = 100
    session_ttl_hours: int = 24
    state_backend: Literal['memory', 'redis'] = 'memory'

4. Add Monitoring and Observability

# Add metrics for Discord operations
from prometheus_client import Counter, Histogram

discord_command_counter = Counter(
    'hermes_discord_commands_total',
    'Total Discord commands executed',
    ['command', 'status']
)

discord_interaction_duration = Histogram(
    'hermes_discord_interaction_duration_seconds',
    'Discord interaction duration',
    ['interaction_type']
)

# In components.py
@discord_command_counter.labels(command='model', status='success').inc()
@discord_interaction_duration.labels(interaction_type='model_picker').time()
async def handle_model_selection(...):
    # ...

5. Create Proof of Concept for Review

Instead of full implementation, create focused PoCs:

PoC 1: Single Enhanced Command

• Implement just /model status with rich UI
• Demonstrate component architecture
• Get feedback on direction

PoC 2: Interactive Flow

• Implement simple multi-step interaction
• Demonstrate state management
• Validate approach

6. Gather Community Feedback First

Before implementation:

1. Create Discussion: Start GitHub Discussion [Feature]: Discord UX parity prototype without plugins or multi-account #2040
2. Survey Users: What Discord features do they want?
3. Prototype UI: Create mockups of proposed UI
4. Vote on Features: Prioritize what to implement first

7. Consider Backward Compatibility

Ensure existing functionality isn't broken:

# Maintain old API
class LegacyDiscordPlatform:
    """Legacy Discord platform for backward compatibility."""
    # Keep existing implementation

# New API with different import
class DiscordPlatform:
    """New enhanced Discord platform."""
    # New implementation

# Allow users to choose
DISCORD_PLATFORM = os.getenv('DISCORD_PLATFORM', 'legacy')

Cross-file Impact

Breaking Changes

Unknown - Not documented, but likely significant given the scope.

Public API Changes

Unknown - Need to document which APIs change.

Callers Affected

Potentially All Discord Users - This appears to be a major refactor of Discord functionality.

Test Coverage

Missing - No tests visible for 15K+ lines of code.

Dependencies

Unknown - Need to document new dependencies.

User Impact

Positive (if implemented correctly):

• Richer Discord UX
• Better command discoverability
• Interactive model selection
• Improved session management

Negative (if not implemented carefully):

• Breaking changes for existing users
• Performance degradation
• Increased complexity
• Maintenance burden

Assessment

💬 Comment Only

This is an impressive prototype that shows deep thought about Discord UX, but it's not ready for review as a mergeable PR. The author explicitly states this is draft-only, which is appropriate given the scope.

Recommendations:

Immediate Actions:

1. Split into smaller PRs - This is too large to review or merge safely
2. Add design documentation - Explain architectural decisions and trade-offs
3. Create migration plan - How to transition from old to new implementation
4. Add tests - Essential for 15K+ lines of new code
5. Document breaking changes - Be explicit about what breaks

Next Steps:

1. Create GitHub Discussion - Gather community feedback on direction
2. Create PoCs - Validate approach with smaller implementations
3. Incremental implementation - Merge foundation first, then features
4. Feature flags - Allow gradual rollout and testing
5. Performance testing - Validate scalability before full deployment

The prototype shows good architectural thinking, but the implementation approach needs to be more incremental and testable. The modular structure is solid, but the scope makes it impossible to review thoroughly or merge safely.

Suggested Path Forward:

1. Close this PR as draft/prototype
2. Create design discussion document
3. Implement Phase 1 (foundation) as separate PR
4. Get feedback and iterate
5. Gradually add features in mergeable increments

This is valuable work that should inform the future of Discord integration in Hermes, but it needs to be broken down into reviewable, testable, and mergeable pieces.

Related: #19413 — we've been running a standalone Discord components implementation (buttons, string-selects, REST + WebSocket paths) in production for a few weeks. It's bolted onto the current discord.py as a separate discord_components.py module. If this RFC moves forward with a discord_impl/ restructure, we'd close #19413 in favor of the upstream implementation — no need to carry our approach forward. Happy to share any lessons learned from the live deployment (ComponentStore lifecycle, REST vs WS interaction routing, `on_interaction) handler pitfalls, custom_id namespacing, etc).

Closing in favor of reviewing #19413