Support Python package distribution for plugins

[jpshackelford]

Summary

Extend the plugin system to support distributing plugins as Python packages (pip/uv installable) in addition to the current git-based approach. This would enable plugin authors to leverage Python's dependency management for transitive dependencies, including plugin-to-plugin dependencies.

Motivation

The current plugin system fetches plugins from git repositories, which works well but lacks dependency management. When a plugin requires Python libraries or depends on other plugins, users must manually ensure all dependencies are installed. Python packaging solves this automatically - pip install openhands-plugin-security would install both the plugin and all its dependencies.

Desired Outcomes

• Plugins can be distributed via PyPI or private registries
• Plugin dependencies (both Python libraries and other plugins) are resolved automatically by pip/uv
• The plugin directory structure remains identical whether consumed from git or from a Python package
• Plugins can optionally include Python code for custom tools and agent behavior
• Plugins install to an isolated directory to avoid polluting the agent's working environment

[enyst]

Python code for custom tools

This only means scripts/ directory, right? I'd suggest to maybe modify the issue description, so that the agent remains on track.

[jpshackelford]

No. larger vision here. See design doc. Scripts directory would be something different.

[enyst]

No. larger vision here. See design doc. Scripts directory would be something different.

Reading, thank you!

As I'm reading, I wonder if we can keep these separate, to keep it simpler:

• install from pypi a regular plugin (or can we do this already?)
• then consider how else we can extend; that is, what else we may want to install as a customization (e.g. create_agent)

Is there a reason why "Support Python package distribution for plugins" would need to define a new system/extension for plugins?

[enyst]

Status update: PR #2031 adds installed plugin management utilities (install/uninstall/list/get/load/update) for Claude-style plugin directories. Plugins install into ~/.openhands/plugins/installed/ and are tracked in .installed.json.

This is still git/local-path based only; it doesn’t address Python package (pip/uv) distribution yet, and there’s no enable/disable state in the SDK (enablement is still by passing selected plugins into Conversation/AgentContext).