openhands-sdk 1.9.1__py3-none-any.whl → 1.10.0__py3-none-any.whl

openhands/sdk/mcp/utils.py

@@ -10,7 +10,6 @@ from openhands.sdk.logger import get_logger
 from openhands.sdk.mcp.client import MCPClient
 from openhands.sdk.mcp.exceptions import MCPTimeoutError
 from openhands.sdk.mcp.tool import MCPToolDefinition
-from openhands.sdk.tool.tool import ToolDefinition
 
 
 logger = get_logger(__name__)
@@ -32,37 +31,38 @@ async def log_handler(message: LogMessage):
     logger.log(level, msg, extra=extra)
 
 
-async def _list_tools(client: MCPClient) -> list[ToolDefinition]:
-    """List tools from an MCP client."""
-    tools: list[ToolDefinition] = []
-
-    async with client:
-        assert client.is_connected(), "MCP client is not connected."
-        mcp_type_tools: list[mcp.types.Tool] = await client.list_tools()
-        for mcp_tool in mcp_type_tools:
-            tool_sequence = MCPToolDefinition.create(
-                mcp_tool=mcp_tool, mcp_client=client
-            )
-            tools.extend(tool_sequence)  # Flatten sequence into list
-    assert not client.is_connected(), (
-        "MCP client should be disconnected after listing tools."
-    )
-    return tools
+async def _connect_and_list_tools(client: MCPClient) -> None:
+    """Connect to MCP server and populate client._tools."""
+    await client.connect()
+    mcp_type_tools: list[mcp.types.Tool] = await client.list_tools()
+    for mcp_tool in mcp_type_tools:
+        tool_sequence = MCPToolDefinition.create(mcp_tool=mcp_tool, mcp_client=client)
+        client._tools.extend(tool_sequence)
 
 
 def create_mcp_tools(
     config: dict | MCPConfig,
     timeout: float = 30.0,
-) -> list[MCPToolDefinition]:
-    """Create MCP tools from MCP configuration."""
-    tools: list[MCPToolDefinition] = []
+) -> MCPClient:
+    """Create MCP tools from MCP configuration.
+
+    Returns an MCPClient with tools populated. Use as a context manager:
+
+        with create_mcp_tools(config) as client:
+            for tool in client.tools:
+                # use tool
+        # Connection automatically closed
+    """
     if isinstance(config, dict):
         config = MCPConfig.model_validate(config)
     client = MCPClient(config, log_handler=log_handler)
 
     try:
-        tools = client.call_async_from_sync(_list_tools, timeout=timeout, client=client)
+        client.call_async_from_sync(
+            _connect_and_list_tools, timeout=timeout, client=client
+        )
     except TimeoutError as e:
+        client.sync_close()
         # Extract server names from config for better error message
         server_names = (
             list(config.mcpServers.keys()) if config.mcpServers else ["unknown"]
@@ -78,6 +78,14 @@ def create_mcp_tools(
         raise MCPTimeoutError(
             error_msg, timeout=timeout, config=config.model_dump()
         ) from e
+    except BaseException:
+        try:
+            client.sync_close()
+        except Exception as close_exc:
+            logger.warning(
+                "Failed to close MCP client during error cleanup", exc_info=close_exc
+            )
+        raise
 
-    logger.info(f"Created {len(tools)} MCP tools: {[t.name for t in tools]}")
-    return tools
+    logger.info(f"Created {len(client.tools)} MCP tools: {[t.name for t in client]}")
+    return client

openhands/sdk/plugin/__init__.py

@@ -7,7 +7,11 @@ It also provides support for plugin marketplaces - directories that list
 available plugins with their metadata and source locations.
 """
 
-from openhands.sdk.plugin.fetch import PluginFetchError
+from openhands.sdk.plugin.fetch import (
+    PluginFetchError,
+    fetch_plugin_with_resolution,
+)
+from openhands.sdk.plugin.loader import load_plugins
 from openhands.sdk.plugin.plugin import Plugin
 from openhands.sdk.plugin.types import (
     AgentDefinition,
@@ -19,6 +23,8 @@ from openhands.sdk.plugin.types import (
     MarketplacePluginSource,
     PluginAuthor,
     PluginManifest,
+    PluginSource,
+    ResolvedPluginSource,
 )
 
 
@@ -28,8 +34,13 @@ __all__ = [
     "PluginFetchError",
     "PluginManifest",
     "PluginAuthor",
+    "PluginSource",
+    "ResolvedPluginSource",
     "AgentDefinition",
     "CommandDefinition",
+    # Plugin loading
+    "load_plugins",
+    "fetch_plugin_with_resolution",
     # Marketplace classes
     "Marketplace",
     "MarketplaceOwner",

openhands/sdk/plugin/fetch.py

@@ -104,23 +104,22 @@ def get_cache_path(source: str, cache_dir: Path | None = None) -> Path:
     return cache_dir / cache_name
 
 
-def _resolve_local_source(url: str, subpath: str | None) -> Path:
+def _resolve_local_source(url: str) -> Path:
     """Resolve a local plugin source to a path.
 
     Args:
         url: Local path string (may contain ~ for home directory).
-        subpath: Optional subdirectory within the local path.
 
     Returns:
         Resolved absolute path to the plugin directory.
 
     Raises:
-        PluginFetchError: If path doesn't exist or subpath is invalid.
+        PluginFetchError: If path doesn't exist.
     """
     local_path = Path(url).expanduser().resolve()
     if not local_path.exists():
         raise PluginFetchError(f"Local plugin path does not exist: {local_path}")
-    return _apply_subpath(local_path, subpath, "local plugin path")
+    return local_path
 
 
 def _fetch_remote_source(
@@ -194,38 +193,143 @@ def fetch_plugin(
     cache_dir: Path | None = None,
     ref: str | None = None,
     update: bool = True,
-    subpath: str | None = None,
+    repo_path: str | None = None,
     git_helper: GitHelper | None = None,
 ) -> Path:
     """Fetch a plugin from a remote source and return the local cached path.
 
     Args:
         source: Plugin source - can be:
-            - "github:owner/repo" - GitHub repository shorthand
-            - "https://github.com/owner/repo.git" - Full git URL
+            - Any git URL (GitHub, GitLab, Bitbucket, Codeberg, self-hosted, etc.)
+              e.g., "https://gitlab.com/org/repo", "git@bitbucket.org:team/repo.git"
+            - "github:owner/repo" - GitHub shorthand (convenience syntax)
             - "/local/path" - Local path (returned as-is)
         cache_dir: Directory for caching. Defaults to ~/.openhands/cache/plugins/
         ref: Optional branch, tag, or commit to checkout.
         update: If True and cache exists, update it. If False, use cached version as-is.
-        subpath: Optional subdirectory path within the repo. If specified, the returned
-            path will point to this subdirectory instead of the repository root.
+        repo_path: Subdirectory path within the git repository
+            (e.g., 'plugins/my-plugin' for monorepos). Only relevant for git
+            sources, not local paths. If specified, the returned path will
+            point to this subdirectory instead of the repository root.
         git_helper: GitHelper instance (for testing). Defaults to global instance.
 
     Returns:
         Path to the local plugin directory (ready for Plugin.load()).
-        If subpath is specified, returns the path to that subdirectory.
+        If repo_path is specified, returns the path to that subdirectory.
+
+    Raises:
+        PluginFetchError: If fetching fails or repo_path doesn't exist.
+    """
+    path, _ = fetch_plugin_with_resolution(
+        source=source,
+        cache_dir=cache_dir,
+        ref=ref,
+        update=update,
+        repo_path=repo_path,
+        git_helper=git_helper,
+    )
+    return path
+
+
+def fetch_plugin_with_resolution(
+    source: str,
+    cache_dir: Path | None = None,
+    ref: str | None = None,
+    update: bool = True,
+    repo_path: str | None = None,
+    git_helper: GitHelper | None = None,
+) -> tuple[Path, str | None]:
+    """Fetch a plugin and return both the path and the resolved commit SHA.
+
+    This is similar to fetch_plugin() but also returns the actual commit SHA
+    that was checked out. This is useful for persistence - storing the resolved
+    SHA ensures that conversation resume gets exactly the same plugin version.
+
+    Args:
+        source: Plugin source (see fetch_plugin for formats).
+        cache_dir: Directory for caching. Defaults to ~/.openhands/cache/plugins/
+        ref: Optional branch, tag, or commit to checkout.
+        update: If True and cache exists, update it. If False, use cached version as-is.
+        repo_path: Subdirectory path within the git repository.
+        git_helper: GitHelper instance (for testing). Defaults to global instance.
+
+    Returns:
+        Tuple of (path, resolved_ref) where:
+        - path: Path to the local plugin directory
+        - resolved_ref: Commit SHA that was checked out (None for local sources)
 
     Raises:
-        PluginFetchError: If fetching fails or subpath doesn't exist.
+        PluginFetchError: If fetching fails or repo_path doesn't exist.
     """
     source_type, url = parse_plugin_source(source)
 
     if source_type == "local":
-        return _resolve_local_source(url, subpath)
+        if repo_path is not None:
+            raise PluginFetchError(
+                f"repo_path is not supported for local plugin sources. "
+                f"Specify the full path directly instead of "
+                f"source='{source}' + repo_path='{repo_path}'"
+            )
+        return _resolve_local_source(url), None
 
     if cache_dir is None:
         cache_dir = DEFAULT_CACHE_DIR
 
-    return _fetch_remote_source(
-        url, cache_dir, ref, update, subpath, git_helper, source
+    git = git_helper if git_helper is not None else GitHelper()
+
+    plugin_path, resolved_ref = _fetch_remote_source_with_resolution(
+        url, cache_dir, ref, update, repo_path, git, source
+    )
+    return plugin_path, resolved_ref
+
+
+def _fetch_remote_source_with_resolution(
+    url: str,
+    cache_dir: Path,
+    ref: str | None,
+    update: bool,
+    subpath: str | None,
+    git_helper: GitHelper,
+    source: str,
+) -> tuple[Path, str]:
+    """Fetch a remote plugin source and return path + resolved commit SHA.
+
+    Args:
+        url: Git URL to fetch.
+        cache_dir: Base directory for caching.
+        ref: Optional branch, tag, or commit to checkout.
+        update: Whether to update existing cache.
+        subpath: Optional subdirectory within the repository.
+        git_helper: GitHelper instance for git operations.
+        source: Original source string (for error messages).
+
+    Returns:
+        Tuple of (path, resolved_ref) where resolved_ref is the commit SHA.
+
+    Raises:
+        PluginFetchError: If fetching fails or subpath is invalid.
+    """
+    repo_cache_path = get_cache_path(url, cache_dir)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    result = try_cached_clone_or_update(
+        url=url,
+        repo_path=repo_cache_path,
+        ref=ref,
+        update=update,
+        git_helper=git_helper,
     )
+
+    if result is None:
+        raise PluginFetchError(f"Failed to fetch plugin from {source}")
+
+    # Get the actual commit SHA that was checked out
+    try:
+        resolved_ref = git_helper.get_head_commit(repo_cache_path)
+    except Exception as e:
+        logger.warning(f"Could not get commit SHA for {source}: {e}")
+        # Fall back to the requested ref if we can't get the SHA
+        resolved_ref = ref or "HEAD"
+
+    final_path = _apply_subpath(repo_cache_path, subpath, "plugin repository")
+    return final_path, resolved_ref

openhands/sdk/plugin/loader.py

@@ -0,0 +1,111 @@
+"""Plugin loading utility for multi-plugin support.
+
+This module provides the canonical function for loading multiple plugins
+and merging them into an agent. It is used by:
+- LocalConversation (for SDK-direct users)
+- ConversationService (for agent-server users)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from openhands.sdk.hooks import HookConfig
+from openhands.sdk.logger import get_logger
+from openhands.sdk.plugin.plugin import Plugin
+from openhands.sdk.plugin.types import PluginSource
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.agent.base import AgentBase
+    from openhands.sdk.context import AgentContext
+
+
+logger = get_logger(__name__)
+
+
+def load_plugins(
+    plugin_specs: list[PluginSource],
+    agent: AgentBase,
+    max_skills: int = 100,
+) -> tuple[AgentBase, HookConfig | None]:
+    """Load multiple plugins and merge them into the agent.
+
+    This is the canonical function for plugin loading, used by:
+    - LocalConversation (for SDK-direct users)
+    - ConversationService (for agent-server users)
+
+    Plugins are loaded in order and their contents are merged with these semantics:
+    - Skills: Override by name (last plugin wins)
+    - MCP config: Override by key (last plugin wins)
+    - Hooks: Concatenate (all hooks run)
+
+    Args:
+        plugin_specs: List of plugin sources to load.
+        agent: Agent to merge plugins into.
+        max_skills: Maximum total skills allowed (defense-in-depth limit).
+
+    Returns:
+        Tuple of (updated_agent, merged_hook_config).
+        The agent has updated agent_context (with merged skills) and mcp_config.
+        The hook_config contains all hooks from all plugins concatenated.
+
+    Raises:
+        PluginFetchError: If any plugin fails to fetch.
+        FileNotFoundError: If any plugin fails to load (e.g., path not found).
+        ValueError: If max_skills limit is exceeded.
+
+    Example:
+        >>> from openhands.sdk.plugin import PluginSource
+        >>> plugins = [
+        ...     PluginSource(source="github:owner/security-plugin", ref="v1.0.0"),
+        ...     PluginSource(source="/local/custom-plugin"),
+        ... ]
+        >>> updated_agent, hooks = load_plugins(plugins, agent)
+    """
+    if not plugin_specs:
+        return agent, None
+
+    # Start with agent's existing context and MCP config
+    merged_context: AgentContext | None = agent.agent_context
+    merged_mcp: dict[str, Any] = dict(agent.mcp_config) if agent.mcp_config else {}
+    all_hooks: list[HookConfig] = []
+
+    for spec in plugin_specs:
+        logger.info(f"Loading plugin from {spec.source}")
+
+        # Fetch (downloads if needed, returns cached path)
+        path = Plugin.fetch(
+            source=spec.source,
+            ref=spec.ref,
+            repo_path=spec.repo_path,
+        )
+        plugin = Plugin.load(path)
+
+        logger.info(
+            f"Loaded plugin '{plugin.name}': "
+            f"{len(plugin.skills)} skills, "
+            f"hooks={'yes' if plugin.hooks else 'no'}, "
+            f"mcp_config={'yes' if plugin.mcp_config else 'no'}"
+        )
+
+        # Merge skills and MCP config separately
+        merged_context = plugin.add_skills_to(merged_context, max_skills=max_skills)
+        merged_mcp = plugin.add_mcp_config_to(merged_mcp)
+
+        # Collect hooks for later combination
+        if plugin.hooks and not plugin.hooks.is_empty():
+            all_hooks.append(plugin.hooks)
+
+    # Combine all hook configs (concatenation semantics)
+    combined_hooks = HookConfig.merge(all_hooks)
+
+    # Create updated agent with merged content
+    updated_agent = agent.model_copy(
+        update={
+            "agent_context": merged_context,
+            "mcp_config": merged_mcp,
+        }
+    )
+
+    return updated_agent, combined_hooks

openhands/sdk/plugin/plugin.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from pydantic import BaseModel, Field
 
@@ -25,6 +25,9 @@ from openhands.sdk.plugin.types import (
 )
 
 
+if TYPE_CHECKING:
+    from openhands.sdk.context import AgentContext
+
 logger = get_logger(__name__)
 
 # Directories to check for plugin manifest
@@ -84,6 +87,135 @@ class Plugin(BaseModel):
         """Get the plugin description."""
         return self.manifest.description
 
+    def get_all_skills(self) -> list[Skill]:
+        """Get all skills including those converted from commands.
+
+        Returns skills from both the skills/ directory and commands/ directory.
+        Commands are converted to keyword-triggered skills using the format
+        /<plugin-name>:<command-name>.
+
+        Returns:
+            Combined list of skills (original + command-derived skills).
+        """
+        all_skills = list(self.skills)
+
+        # Convert commands to skills with keyword triggers
+        for command in self.commands:
+            skill = command.to_skill(self.name)
+            all_skills.append(skill)
+
+        return all_skills
+
+    def add_skills_to(
+        self,
+        agent_context: AgentContext | None = None,
+        max_skills: int | None = None,
+    ) -> AgentContext:
+        """Add this plugin's skills to an agent context.
+
+        Plugin skills override existing skills with the same name.
+        Includes both explicit skills and command-derived skills.
+
+        Args:
+            agent_context: Existing agent context (or None to create new)
+            max_skills: Optional max total skills (raises ValueError if exceeded)
+
+        Returns:
+            New AgentContext with this plugin's skills added
+
+        Raises:
+            ValueError: If max_skills limit would be exceeded
+
+        Example:
+            >>> plugin = Plugin.load(Plugin.fetch("github:owner/plugin"))
+            >>> new_context = plugin.add_skills_to(agent.agent_context, max_skills=100)
+            >>> agent = agent.model_copy(update={"agent_context": new_context})
+        """
+        # Import at runtime to avoid circular import
+        from openhands.sdk.context import AgentContext
+
+        existing_skills = agent_context.skills if agent_context else []
+
+        # Get all skills including command-derived skills
+        all_skills = self.get_all_skills()
+
+        skills_by_name = {s.name: s for s in existing_skills}
+        for skill in all_skills:
+            if skill.name in skills_by_name:
+                logger.warning(f"Plugin skill '{skill.name}' overrides existing skill")
+            skills_by_name[skill.name] = skill
+
+        if max_skills is not None and len(skills_by_name) > max_skills:
+            raise ValueError(
+                f"Total skills ({len(skills_by_name)}) exceeds maximum ({max_skills})"
+            )
+
+        merged_skills = list(skills_by_name.values())
+
+        if agent_context:
+            return agent_context.model_copy(update={"skills": merged_skills})
+        return AgentContext(skills=merged_skills)
+
+    def add_mcp_config_to(
+        self,
+        mcp_config: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Add this plugin's MCP servers to an MCP config.
+
+        Plugin MCP servers override existing servers with the same name.
+
+        Merge semantics (Claude Code compatible):
+        - mcpServers: deep-merge by server name (last plugin wins for same server)
+        - Other top-level keys: shallow override (plugin wins)
+
+        Args:
+            mcp_config: Existing MCP config (or None to create new)
+
+        Returns:
+            New MCP config dict with this plugin's servers added
+
+        Example:
+            >>> plugin = Plugin.load(Plugin.fetch("github:owner/plugin"))
+            >>> new_mcp = plugin.add_mcp_config_to(agent.mcp_config)
+            >>> agent = agent.model_copy(update={"mcp_config": new_mcp})
+        """
+        base_config = mcp_config
+        plugin_config = self.mcp_config
+
+        if base_config is None and plugin_config is None:
+            return {}
+        if base_config is None:
+            return dict(plugin_config) if plugin_config else {}
+        if plugin_config is None:
+            return dict(base_config)
+
+        # Shallow copy to avoid mutating inputs
+        result = dict(base_config)
+
+        # Merge mcpServers by server name (Claude Code compatible behavior)
+        if "mcpServers" in plugin_config:
+            existing_servers = result.get("mcpServers", {})
+            for server_name in plugin_config["mcpServers"]:
+                if server_name in existing_servers:
+                    logger.warning(
+                        f"Plugin MCP server '{server_name}' overrides existing server"
+                    )
+            result["mcpServers"] = {
+                **existing_servers,
+                **plugin_config["mcpServers"],
+            }
+
+        # Other top-level keys: plugin wins (shallow override)
+        for key, value in plugin_config.items():
+            if key != "mcpServers":
+                if key in result:
+                    logger.warning(
+                        f"Plugin MCP config key '{key}' overrides existing value"
+                    )
+                result[key] = value
+
+        return result
+
     @classmethod
     def fetch(
         cls,
@@ -91,7 +223,7 @@ class Plugin(BaseModel):
         cache_dir: Path | None = None,
         ref: str | None = None,
         update: bool = True,
-        subpath: str | None = None,
+        repo_path: str | None = None,
     ) -> Path:
         """Fetch a plugin from a remote source and return the local cached path.
 
@@ -101,22 +233,24 @@ class Plugin(BaseModel):
 
         Args:
             source: Plugin source - can be:
-                - "github:owner/repo" - GitHub repository shorthand
-                - "https://github.com/owner/repo.git" - Full git URL
+                - Any git URL (GitHub, GitLab, Bitbucket, Codeberg, self-hosted, etc.)
+                  e.g., "https://gitlab.com/org/repo", "git@bitbucket.org:team/repo.git"
+                - "github:owner/repo" - GitHub shorthand (convenience syntax)
                 - "/local/path" - Local path (returned as-is)
             cache_dir: Directory for caching. Defaults to ~/.openhands/cache/plugins/
             ref: Optional branch, tag, or commit to checkout.
             update: If True and cache exists, update it. If False, use cached as-is.
-            subpath: Optional subdirectory path within the repo. If specified, the
-                returned path will point to this subdirectory instead of the
-                repository root.
+            repo_path: Subdirectory path within the git repository
+                (e.g., 'plugins/my-plugin' for monorepos). Only relevant for git
+                sources, not local paths. If specified, the returned path will
+                point to this subdirectory instead of the repository root.
 
         Returns:
             Path to the local plugin directory (ready for Plugin.load()).
-            If subpath is specified, returns the path to that subdirectory.
+            If repo_path is specified, returns the path to that subdirectory.
 
         Raises:
-            PluginFetchError: If fetching fails or subpath doesn't exist.
+            PluginFetchError: If fetching fails or repo_path doesn't exist.
 
         Example:
             >>> path = Plugin.fetch("github:owner/my-plugin")
@@ -126,15 +260,15 @@ class Plugin(BaseModel):
             >>> path = Plugin.fetch("github:owner/my-plugin", ref="v1.0.0")
             >>> plugin = Plugin.load(path)
 
-            >>> # Fetch a plugin from a subdirectory
-            >>> path = Plugin.fetch("github:owner/monorepo", subpath="plugins/sub")
+            >>> # Fetch a plugin from a subdirectory in a monorepo
+            >>> path = Plugin.fetch("github:owner/monorepo", repo_path="plugins/sub")
             >>> plugin = Plugin.load(path)
 
             >>> # Fetch and load in one step
             >>> plugin = Plugin.load(Plugin.fetch("github:owner/my-plugin"))
         """
         return fetch_plugin(
-            source, cache_dir=cache_dir, ref=ref, update=update, subpath=subpath
+            source, cache_dir=cache_dir, ref=ref, update=update, repo_path=repo_path
         )
 
     @classmethod
@@ -299,6 +433,7 @@ def _load_hooks(plugin_dir: Path) -> HookConfig | None:
         if hook_config.is_empty():
             logger.info(f"No hooks configured in {hooks_json}")
             return HookConfig()
+        logger.info(f"Loaded hooks from {hooks_json}")
         return hook_config
     except Exception as e:
         logger.warning(f"Failed to load hooks from {hooks_json}: {e}")
@@ -312,7 +447,14 @@ def _load_mcp_config(plugin_dir: Path) -> dict[str, Any] | None:
         return None
 
     try:
-        return load_mcp_config(mcp_json, skill_root=plugin_dir)
+        config = load_mcp_config(mcp_json, skill_root=plugin_dir)
+        if config and "mcpServers" in config:
+            server_names = list(config["mcpServers"].keys())
+            logger.info(
+                f"Loaded MCP config from {mcp_json} "
+                f"with {len(server_names)} server(s): {server_names}"
+            )
+        return config
     except Exception as e:
         logger.warning(f"Failed to load MCP config from {mcp_json}: {e}")
         return None