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

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

openhands/sdk/plugin/types.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 import re
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import frontmatter
 from pydantic import BaseModel, Field, field_validator, model_validator
@@ -15,6 +15,117 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 MARKETPLACE_MANIFEST_DIRS = [".plugin", ".claude-plugin"]
 MARKETPLACE_MANIFEST_FILE = "marketplace.json"
 
+
+class PluginSource(BaseModel):
+    """Specification for a plugin to load.
+
+    This model describes where to find a plugin and is used by load_plugins()
+    to fetch and load plugins from various sources.
+
+    Examples:
+        >>> # GitHub repository
+        >>> PluginSource(source="github:owner/repo", ref="v1.0.0")
+
+        >>> # Plugin from monorepo subdirectory
+        >>> PluginSource(
+        ...     source="github:owner/monorepo",
+        ...     repo_path="plugins/my-plugin"
+        ... )
+
+        >>> # Local path
+        >>> PluginSource(source="/path/to/plugin")
+    """
+
+    source: str = Field(
+        description="Plugin source: 'github:owner/repo', any git URL, or local path"
+    )
+    ref: str | None = Field(
+        default=None,
+        description="Optional branch, tag, or commit (only for git sources)",
+    )
+    repo_path: str | None = Field(
+        default=None,
+        description=(
+            "Subdirectory path within the git repository "
+            "(e.g., 'plugins/my-plugin' for monorepos). "
+            "Only relevant for git sources, not local paths."
+        ),
+    )
+
+    @field_validator("repo_path")
+    @classmethod
+    def validate_repo_path(cls, v: str | None) -> str | None:
+        """Validate repo_path is a safe relative path within the repository."""
+        if v is None:
+            return v
+        # Must be relative (no absolute paths)
+        if v.startswith("/"):
+            raise ValueError("repo_path must be relative, not absolute")
+        # No parent directory traversal
+        if ".." in Path(v).parts:
+            raise ValueError(
+                "repo_path cannot contain '..' (parent directory traversal)"
+            )
+        return v
+
+
+class ResolvedPluginSource(BaseModel):
+    """A plugin source with resolved ref (pinned to commit SHA).
+
+    Used for persistence to ensure deterministic behavior across pause/resume.
+    When a conversation is resumed, the resolved ref ensures we get exactly
+    the same plugin version that was used when the conversation started.
+
+    The resolved_ref is the actual commit SHA that was fetched, even if the
+    original ref was a branch name like 'main'. This prevents drift when
+    branches are updated between pause and resume.
+    """
+
+    source: str = Field(
+        description="Plugin source: 'github:owner/repo', any git URL, or local path"
+    )
+    resolved_ref: str | None = Field(
+        default=None,
+        description=(
+            "Resolved commit SHA (for git sources). None for local paths. "
+            "This is the actual commit that was checked out, even if the "
+            "original ref was a branch name."
+        ),
+    )
+    repo_path: str | None = Field(
+        default=None,
+        description="Subdirectory path within the git repository",
+    )
+    original_ref: str | None = Field(
+        default=None,
+        description="Original ref from PluginSource (for debugging/display)",
+    )
+
+    @classmethod
+    def from_plugin_source(
+        cls, plugin_source: PluginSource, resolved_ref: str | None
+    ) -> ResolvedPluginSource:
+        """Create a ResolvedPluginSource from a PluginSource and resolved ref."""
+        return cls(
+            source=plugin_source.source,
+            resolved_ref=resolved_ref,
+            repo_path=plugin_source.repo_path,
+            original_ref=plugin_source.ref,
+        )
+
+    def to_plugin_source(self) -> PluginSource:
+        """Convert back to PluginSource using the resolved ref.
+
+        When loading from persistence, use the resolved_ref to ensure we get
+        the exact same version that was originally fetched.
+        """
+        return PluginSource(
+            source=self.source,
+            ref=self.resolved_ref,  # Use resolved SHA, not original ref
+            repo_path=self.repo_path,
+        )
+
+
 # Type aliases for marketplace plugin entry configurations
 # These provide better documentation than dict[str, Any] while remaining flexible
 
@@ -35,6 +146,10 @@ type LspServersDict = dict[str, dict[str, Any]]
 type HooksConfigDict = dict[str, Any]
 
 
+if TYPE_CHECKING:
+    from openhands.sdk.context.skills import Skill
+
+
 class PluginAuthor(BaseModel):
     """Author information for a plugin."""
 
@@ -250,6 +365,53 @@ class CommandDefinition(BaseModel):
             metadata=metadata,
         )
 
+    def to_skill(self, plugin_name: str) -> Skill:
+        """Convert this command to a keyword-triggered Skill.
+
+        Creates a Skill with a KeywordTrigger using the Claude Code namespacing
+        format: /<plugin-name>:<command-name>
+
+        Args:
+            plugin_name: The name of the plugin this command belongs to.
+
+        Returns:
+            A Skill object with the command content and a KeywordTrigger.
+
+        Example:
+            For a plugin "city-weather" with command "now":
+            - Trigger keyword: "/city-weather:now"
+            - When user types "/city-weather:now Tokyo", the skill activates
+        """
+        from openhands.sdk.context.skills import Skill
+        from openhands.sdk.context.skills.trigger import KeywordTrigger
+
+        # Build the trigger keyword in Claude Code namespace format
+        trigger_keyword = f"/{plugin_name}:{self.name}"
+
+        # Build skill content with $ARGUMENTS placeholder context
+        content_parts = []
+        if self.description:
+            content_parts.append(f"## {self.name}\n\n{self.description}\n")
+
+        if self.argument_hint:
+            content_parts.append(
+                f"**Arguments**: `$ARGUMENTS` - {self.argument_hint}\n"
+            )
+
+        if self.content:
+            content_parts.append(f"\n{self.content}")
+
+        skill_content = "\n".join(content_parts).strip()
+
+        return Skill(
+            name=f"{plugin_name}:{self.name}",
+            content=skill_content,
+            description=self.description or f"Command {self.name} from {plugin_name}",
+            trigger=KeywordTrigger(keywords=[trigger_keyword]),
+            source=self.source,
+            allowed_tools=self.allowed_tools if self.allowed_tools else None,
+        )
+
 
 class MarketplaceOwner(BaseModel):
     """Owner information for a marketplace.

openhands/sdk/secret/secrets.py

@@ -92,7 +92,19 @@ class LookupSecret(SecretSource):
         return result
 
 
-_SECRET_HEADERS = ["AUTHORIZATION", "KEY", "SECRET"]
+# Patterns used for substring matching against header names (case-insensitive).
+# Headers containing any of these patterns will be redacted during serialization.
+# Examples: X-Access-Token, Cookie, Authorization, X-API-Key, X-API-Secret
+_SECRET_HEADERS = [
+    "AUTHORIZATION",
+    "COOKIE",
+    "CREDENTIAL",
+    "KEY",
+    "PASSWORD",
+    "SECRET",
+    "SESSION",
+    "TOKEN",
+]
 
 
 def _is_secret_header(key: str):

openhands/sdk/utils/__init__.py

@@ -1,5 +1,6 @@
 """Utility functions for the OpenHands SDK."""
 
+from .command import sanitized_env
 from .deprecation import (
     deprecated,
     warn_deprecated,
@@ -19,4 +20,5 @@ __all__ = [
     "deprecated",
     "warn_deprecated",
     "sanitize_openhands_mentions",
+    "sanitized_env",
 ]

openhands/sdk/utils/async_utils.py

@@ -5,7 +5,9 @@ of synchronous conversation handling.
 """
 
 import asyncio
+import threading
 from collections.abc import Callable, Coroutine
+from concurrent.futures import Future
 from typing import Any
 
 from openhands.sdk.event.base import Event
@@ -21,10 +23,14 @@ class AsyncCallbackWrapper:
     but internally executes an async callback in an event loop running in a
     different thread. This allows async callbacks to be used in synchronous
     conversation contexts.
+
+    Tracks pending futures to allow waiting for all callbacks to complete.
     """
 
     async_callback: AsyncConversationCallback
     loop: asyncio.AbstractEventLoop
+    _pending_futures: list[Future]
+    _lock: threading.Lock
 
     def __init__(
         self,
@@ -33,7 +39,36 @@ class AsyncCallbackWrapper:
     ):
         self.async_callback = async_callback
         self.loop = loop
+        self._pending_futures = []
+        self._lock = threading.Lock()
 
     def __call__(self, event: Event):
         if self.loop.is_running():
-            asyncio.run_coroutine_threadsafe(self.async_callback(event), self.loop)
+            future = asyncio.run_coroutine_threadsafe(
+                self.async_callback(event), self.loop
+            )
+            with self._lock:
+                # Clean up completed futures to avoid unbounded memory growth
+                self._pending_futures = [
+                    f for f in self._pending_futures if not f.done()
+                ]
+                self._pending_futures.append(future)
+
+    def wait_for_pending(self, timeout: float | None = None) -> None:
+        """Wait for all pending callbacks to complete.
+
+        Args:
+            timeout: Maximum time to wait in seconds. None means wait indefinitely.
+
+        Raises:
+            TimeoutError: If timeout is exceeded while waiting.
+        """
+        with self._lock:
+            futures = list(self._pending_futures)
+
+        for future in futures:
+            try:
+                future.result(timeout=timeout)
+            except Exception:
+                # Exceptions in callbacks are already logged, ignore here
+                pass

openhands/sdk/utils/command.py

@@ -1,7 +1,9 @@
+import os
 import shlex
 import subprocess
 import sys
 import threading
+from collections.abc import Mapping
 
 from openhands.sdk.logger import get_logger
 
@@ -9,6 +11,31 @@ from openhands.sdk.logger import get_logger
 logger = get_logger(__name__)
 
 
+def sanitized_env(
+    env: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Return a copy of *env* with sanitized values.
+
+    PyInstaller-based binaries rewrite ``LD_LIBRARY_PATH`` so their vendored
+    libraries win. This function restores the original value so that subprocess
+    will not use them.
+    """
+
+    base_env: dict[str, str]
+    if env is None:
+        base_env = dict(os.environ)
+    else:
+        base_env = dict(env)
+
+    if "LD_LIBRARY_PATH_ORIG" in base_env:
+        origin = base_env["LD_LIBRARY_PATH_ORIG"]
+        if origin:
+            base_env["LD_LIBRARY_PATH"] = origin
+        else:
+            base_env.pop("LD_LIBRARY_PATH", None)
+    return base_env
+
+
 def execute_command(
     cmd: list[str] | str,
     env: dict[str, str] | None = None,
@@ -29,7 +56,7 @@ def execute_command(
     proc = subprocess.Popen(
         cmd_to_run,
         cwd=cwd,
-        env=env,
+        env=sanitized_env(env),
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         text=True,

openhands/sdk/workspace/remote/base.py

@@ -50,12 +50,17 @@ class RemoteWorkspace(RemoteWorkspaceMixin, BaseWorkspace):
         if client is None:
             # Configure reasonable timeouts for HTTP requests
             # - connect: 10 seconds to establish connection
-            # - read: 60 seconds to read response (for LLM operations)
+            # - read: 600 seconds (10 minutes) to read response (for LLM operations)
             # - write: 10 seconds to send request
             # - pool: 10 seconds to get connection from pool
-            timeout = httpx.Timeout(connect=10.0, read=60.0, write=10.0, pool=10.0)
+            timeout = httpx.Timeout(
+                connect=10.0, read=self.read_timeout, write=10.0, pool=10.0
+            )
             client = httpx.Client(
-                base_url=self.host, timeout=timeout, headers=self._headers
+                base_url=self.host,
+                timeout=timeout,
+                headers=self._headers,
+                limits=httpx.Limits(max_connections=self.max_connections),
             )
             self._client = client
         return client

openhands/sdk/workspace/remote/remote_workspace_mixin.py

@@ -25,6 +25,15 @@ class RemoteWorkspaceMixin(BaseModel):
     working_dir: str = Field(
         description="The working directory for agent operations and tool execution."
     )
+    read_timeout: float = Field(
+        default=600.0,
+        description="Timeout in seconds for reading operations of httpx.Client.",
+    )
+    max_connections: int | None = Field(
+        default=None,
+        description="Maximum number of connections for httpx.Client. "
+        "None means no limit, useful for running many conversations in parallel.",
+    )
 
     def model_post_init(self, context: Any) -> None:
         # Set up remote host
@@ -87,26 +96,50 @@ class RemoteWorkspaceMixin(BaseModel):
             stdout_parts = []
             stderr_parts = []
             exit_code = None
+            last_order = -1  # Track highest order seen to fetch only new events
+            seen_event_ids: set[str] = set()  # Track seen IDs to detect duplicates
 
             while time.time() - start_time < timeout:
-                # Search for all events
+                # Search for new events (order > last_order)
+                params: dict[str, str | int] = {
+                    "command_id__eq": command_id,
+                    "sort_order": "TIMESTAMP",
+                    "limit": 100,
+                    "kind__eq": "BashOutput",
+                }
+                if last_order >= 0:
+                    params["order__gt"] = last_order
+
                 response = yield {
                     "method": "GET",
                     "url": f"{self.host}/api/bash/bash_events/search",
-                    "params": {
-                        "command_id__eq": command_id,
-                        "sort_order": "TIMESTAMP",
-                        "limit": 100,
-                    },
+                    "params": params,
                     "headers": self._headers,
                     "timeout": timeout,
                 }
                 response.raise_for_status()
                 search_result = response.json()
 
-                # Filter for BashOutput events for this command
+                # Process BashOutput events
                 for event in search_result.get("items", []):
                     if event.get("kind") == "BashOutput":
+                        # Check for duplicates - safety check in case caller
+                        # forgets to add kind__eq filter or API has a bug
+                        event_id = event.get("id")
+                        if event_id is not None:
+                            if event_id in seen_event_ids:
+                                raise RuntimeError(
+                                    f"Duplicate event received: {event_id}. "
+                                    "This should not happen with order__gt "
+                                    "filtering and kind filtering."
+                                )
+                            seen_event_ids.add(event_id)
+
+                        # Track the highest order we've seen
+                        event_order = event.get("order")
+                        if event_order is not None and event_order > last_order:
+                            last_order = event_order
+
                         if event.get("stdout"):
                             stdout_parts.append(event["stdout"])
                         if event.get("stderr"):

{openhands_sdk-1.9.1.dist-info → openhands_sdk-1.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.9.1
+Version: 1.11.0
 Summary: OpenHands SDK - Core functionality for building AI agents
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk