Design: LLM Profile Management with OpenHands Cloud Integration and MCP Support

[xingyaoww]

Summary

This PR adds comprehensive design documents for the LLM Profile Management feature requested in #68, with specific focus on:

1. Supporting ALL verified LLMs under OpenHands Cloud provider with easy switching
2. Integrating MCP (Model Context Protocol) configurations into profiles
3. Making profiles comprehensive (LLM + MCP + complete agent configuration)

Changes

New Files

• PROFILE_DESIGN.md - Complete technical design document covering:

  • Profile structure and philosophy
  • OpenHands Cloud provider integration
  • Directory structure and configuration formats
  • User experience flows and CLI commands
  • 4-phase implementation plan
  • Migration strategy for backward compatibility
  • Security considerations and future enhancements

• DESIGN_REVIEW_RESPONSE.md - Detailed responses to specific design questions:

  • How to support ALL verified LLMs under OpenHands Cloud provider
  • Enhanced approach vs. naive approach for profile generation
  • Version tracking strategy (embedded vs. separate file)
  • How to integrate MCP configurations into profiles
  • Hierarchical MCP configuration strategy
  • Profile as complete agent configuration

Key Design Decisions

1. Profile = Complete Agent Configuration

• Profiles contain LLM + MCP + Condenser + all agent settings
• Not just LLM settings, but complete environments
• Allows model-specific MCP configurations

2. OpenHands Cloud Integration

• Automatic profile generation for all verified models
• Version-tracked synchronization via last_opened_version in profiles.json
• Auto-regeneration when CLI version changes
• Manual sync via openhands profiles sync command

3. Hierarchical MCP Configuration

User Profile MCP
    ↓ (overrides)
Model-Specific Cloud MCP
    ↓ (overrides)
Global Cloud MCP
    ↓ (overrides)
Local Default MCP

4. Directory Structure

~/.openhands/
└── llms/
    ├── profiles.json                    # Single source of truth
    ├── default.json                     # Symlink to default profile
    ├── openhands-general.json          # Base template
    ├── openhands-gpt-4o-mini.json      # Auto-generated
    ├── openhands-claude-3-5-sonnet.json
    └── my-custom-profile.json          # User-created

5. User Experience Highlights

• Easy switching: openhands --profile <name> or interactive selector
• Profile management: openhands profiles list|create|edit|delete|sync
• Cloud commands: openhands cloud login|logout|status
• Backward compatible migration from agent_settings.json

Implementation Phases

Phase 1: Core Infrastructure ⭐ MUST HAVE

• ProfileManager class
• Profile storage and loading
• Migration from legacy config
• Basic CLI integration (--profile flag)

Phase 2: Cloud Integration ⭐ MUST HAVE

• CloudProfileGenerator class
• Version tracking and auto-regeneration
• Verified models fetching
• Cloud MCP configuration support

Phase 3: User Interface ⭐ SHOULD HAVE

• Interactive profile selector
• Profile management commands
• Cloud commands

Phase 4: Polish ✨ NICE TO HAVE

• Profile usage analytics
• Import/export
• Profile templates
• Smart profile switching

Advantages Over Naive Approach

Naive Approach	Enhanced Approach
Separate .last_opened_version file	Embedded in profiles.json (single source of truth)
Simple file existence check	Rich metadata with timestamps, model capabilities, descriptions
No user feedback during generation	Progress indicators and success messages
Regenerate all profiles blindly	Smart regeneration (only if version changed or user syncs)
No cloud status tracking	Track connection status, last sync time, auth state

Testing Strategy

No code changes in this PR - only design documents for review and discussion.

Once design is approved, implementation PRs will include:

• Unit tests for ProfileManager
• Tests for CloudProfileGenerator
• Migration tests
• Profile workflow integration tests
• MCP configuration merge tests

Questions for Reviewers

1. MCP Merge Strategy: Should user-defined MCP configs completely replace cloud configs, or merge with them? (Current design: merge by default)

2. Profile Immutability: Should cloud profiles be immutable (can only be copied, not edited)? (Current design: convert to user profile on edit)

3. Profile Persistence After Logout: What happens to cloud profiles after user logs out? (Current design: keep but don't update)

4. Sync Frequency: How often should we sync with OpenHands Cloud? (Current design: on version change + manual sync)

Related Issues

Closes #68

Next Steps

1. Gather feedback on design approach
2. Discuss and finalize design decisions
3. Create implementation plan with timeline
4. Begin Phase 1 implementation in separate PR

---

Note: This is a design-only PR. No functional changes are included. The design documents provide a comprehensive blueprint for implementing the feature in subsequent PRs.

@xingyaoww can click here to continue refining the PR

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
TOTAL	1173	205	82%

report-only-changed-files is enabled. No files were changed during this commit :)