[M2] Plugin Management

[jpshackelford]

Parent: OpenHands/OpenHands-CLI#407 ([PRD] OpenHands CLI Plugin Support)

Summary

Implement CLI commands for installing, uninstalling, enabling, and disabling plugins from registered marketplaces. This provides persistent plugin management so users don't need to specify --plugin flags every time.

Background

With M1 providing explicit plugin loading and M2-Marketplace providing marketplace registration, users need commands to:

• Install plugins from marketplaces for persistent use
• Enable/disable plugins without removing them
• Search for plugins across registered marketplaces
• View installed plugin status

Requirements

Plugin Commands

# Search for plugins
oh plugin search formatter
oh plugin search --marketplace company-tools

# Install a plugin
oh plugin install code-formatter@company-tools
oh plugin install code-formatter  # Uses default/only marketplace

# List installed plugins
oh plugin list
oh plugin list --enabled
oh plugin list --disabled

# Enable/disable plugins
oh plugin disable code-formatter@company-tools
oh plugin enable code-formatter@company-tools

# Uninstall a plugin
oh plugin uninstall code-formatter@company-tools

# Show plugin details
oh plugin info code-formatter@company-tools

Plugin Identification

Plugins are identified as plugin-name@marketplace-name:

• code-formatter@company-tools - Fully qualified
• code-formatter - Shorthand (if unambiguous)

Storage

Installed plugins are stored in ~/.openhands/plugins.json:

{
  "installed": {
    "code-formatter@company-tools": {
      "enabled": true,
      "installed_at": "2024-01-15T10:30:00Z",
      "version": "1.2.0",
      "resolved_ref": "abc123def456"
    },
    "linter@community": {
      "enabled": false,
      "installed_at": "2024-01-14T09:00:00Z",
      "version": "2.0.1"
    }
  }
}

CLI Output Examples

Searching for plugins:

$ oh plugin search formatter
Searching marketplaces...

  code-formatter (v1.2.0) @ company-tools
    Format code using team standards
    Commands: format, check

  pretty-print (v0.5.0) @ community
    Pretty print JSON, YAML, and XML
    Commands: format, validate

Use 'oh plugin install <name>@<marketplace>' to install.

Installing a plugin:

$ oh plugin install code-formatter@company-tools
Installing 'code-formatter' from company-tools...

Plugin 'code-formatter@company-tools' installed!
  Version: 1.2.0
  Commands: format, check

The plugin is enabled and will be loaded in new conversations.

Listing plugins:

$ oh plugin list
Installed plugins:

  code-formatter@company-tools (v1.2.0) [enabled]
    Installed: 2 days ago
    Commands: format, check

  linter@community (v2.0.1) [disabled]
    Installed: 3 days ago
    Commands: lint, fix

2 plugins installed (1 enabled, 1 disabled)

Plugin info:

$ oh plugin info code-formatter@company-tools
Plugin: code-formatter
Marketplace: company-tools
Version: 1.2.0
Status: enabled
Installed: 2024-01-15T10:30:00Z

Description:
  Format code using team standards and best practices.

Commands:
  /code-formatter:format - Format code in specified path
  /code-formatter:check  - Check formatting without changes

Skills: 2
Hooks: 1
MCP Servers: 0

Behavior

• Installed & enabled plugins are automatically loaded on oh run
• Disabled plugins remain installed but are not loaded
• Uninstalling removes the plugin from storage
• Version conflicts across marketplaces warn the user

Acceptance Criteria

• oh plugin search QUERY searches across marketplaces
• oh plugin install NAME@MARKETPLACE installs a plugin
• oh plugin list shows installed plugins with status
• oh plugin enable/disable toggles plugin loading
• oh plugin uninstall removes a plugin
• oh plugin info shows detailed plugin information
• Enabled plugins auto-load on oh run
• Plugins persist in ~/.openhands/plugins.json
• Ambiguous plugin names produce helpful errors
• Installing non-existent plugins produces clear errors

Dependencies

• M1: Plugin Loading and Command Invocation
• M2: Marketplace Management ([M2] Marketplace Management #411)

References

• Full Implementation Details (Gist)

[jpshackelford]

Proposed Implementation Notes

Data Models

from pydantic import BaseModel
from datetime import datetime

class InstalledPlugin(BaseModel):
    """An installed plugin."""
    enabled: bool = True
    installed_at: datetime
    version: str | None = None
    resolved_ref: str | None = None  # Git commit hash
    pinned_version: str | None = None  # For version locking

class PluginStore(BaseModel):
    """User's installed plugins."""
    installed: dict[str, InstalledPlugin] = {}

Storage Operations

from pathlib import Path

PLUGINS_FILE = Path.home() / ".openhands" / "plugins.json"

class PluginStorage:
    """Manage installed plugin storage."""
    
    @classmethod
    def load(cls) -> PluginStore:
        if PLUGINS_FILE.exists():
            data = json.loads(PLUGINS_FILE.read_text())
            return PluginStore.model_validate(data)
        return PluginStore()
    
    @classmethod
    def save(cls, store: PluginStore) -> None:
        PLUGINS_FILE.parent.mkdir(parents=True, exist_ok=True)
        PLUGINS_FILE.write_text(store.model_dump_json(indent=2))
    
    @classmethod
    def install(cls, qualified_name: str, version: str, ref: str) -> None:
        store = cls.load()
        store.installed[qualified_name] = InstalledPlugin(
            enabled=True,
            installed_at=datetime.now(),
            version=version,
            resolved_ref=ref
        )
        cls.save(store)
    
    @classmethod
    def uninstall(cls, qualified_name: str) -> bool:
        store = cls.load()
        if qualified_name in store.installed:
            del store.installed[qualified_name]
            cls.save(store)
            return True
        return False
    
    @classmethod
    def set_enabled(cls, qualified_name: str, enabled: bool) -> bool:
        store = cls.load()
        if qualified_name in store.installed:
            store.installed[qualified_name].enabled = enabled
            cls.save(store)
            return True
        return False
    
    @classmethod
    def get_enabled_plugins(cls) -> list[str]:
        store = cls.load()
        return [
            name for name, plugin in store.installed.items()
            if plugin.enabled
        ]

Plugin Name Resolution

def resolve_plugin_name(
    name: str, 
    marketplaces: dict[str, RegisteredMarketplace]
) -> str:
    """Resolve plugin name to fully qualified name@marketplace.
    
    Args:
        name: Either 'plugin-name' or 'plugin-name@marketplace'
        marketplaces: Registered marketplaces
    
    Returns:
        Fully qualified 'plugin-name@marketplace-name'
    
    Raises:
        AmbiguousPluginError: If name matches multiple marketplaces
        PluginNotFoundError: If plugin not found in any marketplace
    """
    if '@' in name:
        plugin_name, marketplace_name = name.rsplit('@', 1)
        if marketplace_name not in marketplaces:
            raise MarketplaceNotFoundError(marketplace_name)
        return name
    
    # Search all marketplaces for this plugin
    found_in = []
    for mp_name, mp in marketplaces.items():
        mp_data = load_marketplace_data(mp)
        if name in mp_data.plugins:
            found_in.append(mp_name)
    
    if len(found_in) == 0:
        raise PluginNotFoundError(name)
    elif len(found_in) == 1:
        return f"{name}@{found_in[0]}"
    else:
        raise AmbiguousPluginError(
            f"Plugin '{name}' found in multiple marketplaces: {found_in}. "
            f"Use '{name}@<marketplace>' to specify."
        )

Search Implementation

def search_plugins(
    query: str,
    marketplaces: dict[str, RegisteredMarketplace],
    marketplace_filter: str | None = None
) -> list[SearchResult]:
    """Search for plugins across marketplaces."""
    results = []
    
    for mp_name, mp in marketplaces.items():
        if marketplace_filter and mp_name != marketplace_filter:
            continue
        
        mp_data = load_marketplace_data(mp)
        for plugin_name, plugin_info in mp_data.plugins.items():
            # Match against name and description
            if query.lower() in plugin_name.lower():
                results.append(SearchResult(
                    name=plugin_name,
                    marketplace=mp_name,
                    version=plugin_info.version,
                    description=plugin_info.description,
                    commands=[c.name for c in plugin_info.commands]
                ))
            elif plugin_info.description and query.lower() in plugin_info.description.lower():
                results.append(SearchResult(
                    name=plugin_name,
                    marketplace=mp_name,
                    version=plugin_info.version,
                    description=plugin_info.description,
                    commands=[c.name for c in plugin_info.commands]
                ))
    
    return results

Auto-Loading on oh run

def get_plugins_for_conversation() -> list[PluginSource]:
    """Get PluginSource list for enabled installed plugins."""
    plugin_store = PluginStorage.load()
    marketplace_store = MarketplaceStorage.load()
    
    sources = []
    for qualified_name, plugin in plugin_store.installed.items():
        if not plugin.enabled:
            continue
        
        plugin_name, marketplace_name = qualified_name.rsplit('@', 1)
        marketplace = marketplace_store.marketplaces.get(marketplace_name)
        
        if marketplace is None:
            # Marketplace was removed - warn user
            print(f"Warning: Marketplace '{marketplace_name}' not found for plugin '{plugin_name}'")
            continue
        
        sources.append(PluginSource(
            source=marketplace.source.to_string(),
            ref=plugin.resolved_ref,
            plugin_name=plugin_name
        ))
    
    return sources

CLI Command Structure

def add_plugin_commands(subparsers):
    """Add plugin subcommands."""
    
    # Search
    search_parser = subparsers.add_parser('search', help='Search for plugins')
    search_parser.add_argument('query', help='Search query')
    search_parser.add_argument('--marketplace', help='Limit to specific marketplace')
    
    # Install
    install_parser = subparsers.add_parser('install', help='Install a plugin')
    install_parser.add_argument('name', help='Plugin name or name@marketplace')
    
    # List
    list_parser = subparsers.add_parser('list', help='List installed plugins')
    list_parser.add_argument('--enabled', action='store_true', help='Show only enabled')
    list_parser.add_argument('--disabled', action='store_true', help='Show only disabled')
    
    # Enable/Disable
    enable_parser = subparsers.add_parser('enable', help='Enable a plugin')
    enable_parser.add_argument('name', help='Plugin name')
    
    disable_parser = subparsers.add_parser('disable', help='Disable a plugin')
    disable_parser.add_argument('name', help='Plugin name')
    
    # Uninstall
    uninstall_parser = subparsers.add_parser('uninstall', help='Uninstall a plugin')
    uninstall_parser.add_argument('name', help='Plugin name')
    
    # Info
    info_parser = subparsers.add_parser('info', help='Show plugin details')
    info_parser.add_argument('name', help='Plugin name')

Testing Considerations

• Test plugin name resolution (qualified vs. shorthand)
• Test ambiguous name handling
• Test search across multiple marketplaces
• Test install/uninstall flow
• Test enable/disable persistence
• Test auto-loading on oh run
• Test handling of removed marketplaces

[enyst]

Status update: SDK PR OpenHands/software-agent-sdk#2031 adds installed plugin management utilities (install/uninstall/list/get/load/update) for Claude-style plugins under ~/.openhands/plugins/installed/ with .installed.json metadata. This gives the CLI a backend for /plugin install/list/uninstall.

There is still no enable/disable state in the SDK; enablement remains a CLI-owned config that must be passed into Conversation/AgentContext. Marketplace resolution/search remains CLI-side. AgentSkills management gap tracked in OpenHands/software-agent-sdk#2301.

[github-actions]

This issue is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.

[github-actions]

This issue is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.