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

openhands/sdk/hooks/config.py

@@ -7,7 +7,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 from openhands.sdk.hooks.types import HookEventType
 
@@ -15,6 +15,26 @@ from openhands.sdk.hooks.types import HookEventType
 logger = logging.getLogger(__name__)
 
 
+def _pascal_to_snake(name: str) -> str:
+    """Convert PascalCase to snake_case."""
+    # Insert underscore before uppercase letters and lowercase everything
+    result = re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+    return result
+
+
+# Valid snake_case field names for hook events
+_VALID_HOOK_FIELDS: frozenset[str] = frozenset(
+    {
+        "pre_tool_use",
+        "post_tool_use",
+        "user_prompt_submit",
+        "session_start",
+        "session_end",
+        "stop",
+    }
+)
+
+
 class HookType(str, Enum):
     """Types of hooks that can be executed."""
 
@@ -77,9 +97,117 @@ class HookMatcher(BaseModel):
 
 
 class HookConfig(BaseModel):
-    """Configuration for all hooks, loaded from .openhands/hooks.json."""
+    """Configuration for all hooks.
+
+    Hooks can be configured either by loading from `.openhands/hooks.json` or
+    by directly instantiating with typed fields:
+
+        # Direct instantiation with typed fields (recommended):
+        config = HookConfig(
+            pre_tool_use=[
+                HookMatcher(
+                    matcher="terminal",
+                    hooks=[HookDefinition(command="block_dangerous.sh")]
+                )
+            ]
+        )
+
+        # Load from JSON file:
+        config = HookConfig.load(".openhands/hooks.json")
+    """
+
+    model_config = {
+        "extra": "forbid",
+    }
+
+    pre_tool_use: list[HookMatcher] = Field(
+        default_factory=list,
+        description="Hooks that run before tool execution",
+    )
+    post_tool_use: list[HookMatcher] = Field(
+        default_factory=list,
+        description="Hooks that run after tool execution",
+    )
+    user_prompt_submit: list[HookMatcher] = Field(
+        default_factory=list,
+        description="Hooks that run when user submits a prompt",
+    )
+    session_start: list[HookMatcher] = Field(
+        default_factory=list,
+        description="Hooks that run when a session starts",
+    )
+    session_end: list[HookMatcher] = Field(
+        default_factory=list,
+        description="Hooks that run when a session ends",
+    )
+    stop: list[HookMatcher] = Field(
+        default_factory=list,
+        description="Hooks that run when the agent attempts to stop",
+    )
+
+    def is_empty(self) -> bool:
+        """Check if this config has no hooks configured."""
+        return not any(
+            [
+                self.pre_tool_use,
+                self.post_tool_use,
+                self.user_prompt_submit,
+                self.session_start,
+                self.session_end,
+                self.stop,
+            ]
+        )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_hooks_input(cls, data: Any) -> Any:
+        """Support JSON format with PascalCase keys and 'hooks' wrapper.
+
+        We intentionally continue supporting these formats for interoperability with
+        existing integrations (e.g. Claude Code plugin hook files).
+        """
+        if not isinstance(data, dict):
+            return data
+
+        # Unwrap legacy format: {"hooks": {"PreToolUse": [...]}}
+        if "hooks" in data:
+            if len(data) != 1:
+                logger.warning(
+                    'HookConfig legacy wrapper format should be {"hooks": {...}}. '
+                    "Extra top-level keys will be ignored."
+                )
+            data = data["hooks"]
+
+        # Convert PascalCase keys to snake_case field names
+        normalized: dict[str, Any] = {}
+        seen_fields: set[str] = set()
+
+        for key, value in data.items():
+            snake_key = _pascal_to_snake(key)
+            is_pascal_case = snake_key != key
+
+            if is_pascal_case:
+                # Validate that PascalCase key maps to a known field
+                if snake_key not in _VALID_HOOK_FIELDS:
+                    valid_types = ", ".join(sorted(_VALID_HOOK_FIELDS))
+                    raise ValueError(
+                        f"Unknown event type '{key}'. Valid types: {valid_types}"
+                    )
+
+            # Check for duplicate keys (both PascalCase and snake_case provided)
+            if snake_key in seen_fields:
+                raise ValueError(
+                    f"Duplicate hook event: both '{key}' and its snake_case "
+                    f"equivalent '{snake_key}' were provided"
+                )
+            seen_fields.add(snake_key)
+            normalized[snake_key] = value
+
+        # Preserve backwards compatibility without deprecating any supported formats.
+        # The legacy 'hooks' wrapper and PascalCase keys are accepted for
+        # interoperability and should not emit a deprecation warning.
 
-    hooks: dict[str, list[HookMatcher]] = Field(default_factory=dict)
+        return normalized
 
     @classmethod
     def load(
@@ -111,49 +239,34 @@ class HookConfig(BaseModel):
         if not path.exists():
             return cls()
 
-        try:
-            with open(path) as f:
-                data = json.load(f)
-            return cls.from_dict(data)
-        except (json.JSONDecodeError, OSError) as e:
-            # Log warning but don't fail - just return empty config
-            logger.warning(f"Failed to load hooks from {path}: {e}")
-            return cls()
+        with open(path) as f:
+            data = json.load(f)
+        # Use model_validate which triggers the model_validator
+        return cls.model_validate(data)
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "HookConfig":
-        """Create HookConfig from a dictionary."""
-        hooks_data = data.get("hooks", {})
-        hooks: dict[str, list[HookMatcher]] = {}
-
-        for event_type, matchers in hooks_data.items():
-            if not isinstance(matchers, list):
-                continue
-
-            hooks[event_type] = []
-            for matcher_data in matchers:
-                if isinstance(matcher_data, dict):
-                    # Parse hooks within the matcher
-                    hook_defs = []
-                    for hook_data in matcher_data.get("hooks", []):
-                        if isinstance(hook_data, dict):
-                            hook_defs.append(HookDefinition(**hook_data))
-
-                    hooks[event_type].append(
-                        HookMatcher(
-                            matcher=matcher_data.get("matcher", "*"),
-                            hooks=hook_defs,
-                        )
-                    )
+        """Create HookConfig from a dictionary.
+
+        Supports both legacy format with "hooks" wrapper and direct format:
+            # Legacy format:
+            {"hooks": {"PreToolUse": [...]}}
 
-        return cls(hooks=hooks)
+            # Direct format:
+            {"PreToolUse": [...]}
+        """
+        return cls.model_validate(data)
+
+    def _get_matchers_for_event(self, event_type: HookEventType) -> list[HookMatcher]:
+        """Get matchers for an event type."""
+        field_name = _pascal_to_snake(event_type.value)
+        return getattr(self, field_name, [])
 
     def get_hooks_for_event(
         self, event_type: HookEventType, tool_name: str | None = None
     ) -> list[HookDefinition]:
         """Get all hooks that should run for an event."""
-        event_key = event_type.value
-        matchers = self.hooks.get(event_key, [])
+        matchers = self._get_matchers_for_event(event_type)
 
         result: list[HookDefinition] = []
         for matcher in matchers:
@@ -164,17 +277,13 @@ class HookConfig(BaseModel):
 
     def has_hooks_for_event(self, event_type: HookEventType) -> bool:
         """Check if there are any hooks configured for an event type."""
-        return event_type.value in self.hooks and len(self.hooks[event_type.value]) > 0
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary format for serialization."""
-        hooks_dict = {k: [m.model_dump() for m in v] for k, v in self.hooks.items()}
-        return {"hooks": hooks_dict}
+        matchers = self._get_matchers_for_event(event_type)
+        return len(matchers) > 0
 
     def save(self, path: str | Path) -> None:
-        """Save hook configuration to a JSON file."""
+        """Save hook configuration to a JSON file using snake_case field names."""
         path = Path(path)
         path.parent.mkdir(parents=True, exist_ok=True)
 
         with open(path, "w") as f:
-            json.dump(self.to_dict(), f, indent=2)
+            json.dump(self.model_dump(mode="json", exclude_defaults=True), f, indent=2)

openhands/sdk/llm/utils/model_features.py

@@ -63,6 +63,9 @@ REASONING_EFFORT_MODELS: list[str] = [
     "o4-mini-2025-04-16",
     "gemini-2.5-flash",
     "gemini-2.5-pro",
+    # Gemini 3 family
+    "gemini-3-flash-preview",
+    "gemini-3-pro-preview",
     # OpenAI GPT-5 family (includes mini variants)
     "gpt-5",
     # Anthropic Opus 4.5

openhands/sdk/plugin/__init__.py

@@ -2,21 +2,38 @@
 
 This module provides support for loading and managing plugins that bundle
 skills, hooks, MCP configurations, agents, and commands together.
+
+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.plugin import Plugin
 from openhands.sdk.plugin.types import (
     AgentDefinition,
     CommandDefinition,
+    Marketplace,
+    MarketplaceMetadata,
+    MarketplaceOwner,
+    MarketplacePluginEntry,
+    MarketplacePluginSource,
     PluginAuthor,
     PluginManifest,
 )
 
 
 __all__ = [
+    # Plugin classes
     "Plugin",
+    "PluginFetchError",
     "PluginManifest",
     "PluginAuthor",
     "AgentDefinition",
     "CommandDefinition",
+    # Marketplace classes
+    "Marketplace",
+    "MarketplaceOwner",
+    "MarketplacePluginEntry",
+    "MarketplacePluginSource",
+    "MarketplaceMetadata",
 ]

openhands/sdk/plugin/fetch.py

@@ -0,0 +1,231 @@
+"""Plugin fetching utilities for remote plugin sources."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from openhands.sdk.git.cached_repo import GitHelper, try_cached_clone_or_update
+from openhands.sdk.git.utils import extract_repo_name, is_git_url, normalize_git_url
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+DEFAULT_CACHE_DIR = Path.home() / ".openhands" / "cache" / "plugins"
+
+
+class PluginFetchError(Exception):
+    """Raised when fetching a plugin fails."""
+
+    pass
+
+
+def parse_plugin_source(source: str) -> tuple[str, str]:
+    """Parse plugin source into (type, url).
+
+    Args:
+        source: Plugin source string. Can be:
+            - "github:owner/repo" - GitHub repository shorthand
+            - "https://github.com/owner/repo.git" - Full git URL
+            - "git@github.com:owner/repo.git" - SSH git URL
+            - "/local/path" - Local path
+
+    Returns:
+        Tuple of (source_type, normalized_url) where source_type is one of:
+        - "github": GitHub repository
+        - "git": Any git URL
+        - "local": Local filesystem path
+
+    Examples:
+        >>> parse_plugin_source("github:owner/repo")
+        ("github", "https://github.com/owner/repo.git")
+        >>> parse_plugin_source("https://gitlab.com/org/repo.git")
+        ("git", "https://gitlab.com/org/repo.git")
+        >>> parse_plugin_source("/local/path")
+        ("local", "/local/path")
+    """
+    source = source.strip()
+
+    # GitHub shorthand: github:owner/repo
+    if source.startswith("github:"):
+        repo_path = source[7:]  # Remove "github:" prefix
+        # Validate format
+        if "/" not in repo_path or repo_path.count("/") > 1:
+            raise PluginFetchError(
+                f"Invalid GitHub shorthand format: {source}. "
+                f"Expected format: github:owner/repo"
+            )
+        url = f"https://github.com/{repo_path}.git"
+        return ("github", url)
+
+    # Git URLs: detect by protocol/scheme rather than enumerating providers
+    # This handles GitHub, GitLab, Bitbucket, Codeberg, self-hosted instances, etc.
+    if is_git_url(source):
+        url = normalize_git_url(source)
+        return ("git", url)
+
+    # Local path: starts with /, ~, . or contains / without a URL scheme
+    if source.startswith(("/", "~", ".")):
+        return ("local", source)
+
+    if "/" in source and "://" not in source:
+        # Relative path like "plugins/my-plugin"
+        return ("local", source)
+
+    raise PluginFetchError(
+        f"Unable to parse plugin source: {source}. "
+        f"Expected formats: 'github:owner/repo', git URL, or local path"
+    )
+
+
+def get_cache_path(source: str, cache_dir: Path | None = None) -> Path:
+    """Get the cache path for a plugin source.
+
+    Creates a deterministic path based on a hash of the source URL.
+
+    Args:
+        source: The plugin source (URL or path).
+        cache_dir: Base cache directory. Defaults to ~/.openhands/cache/plugins/
+
+    Returns:
+        Path where the plugin should be cached.
+    """
+    if cache_dir is None:
+        cache_dir = DEFAULT_CACHE_DIR
+
+    # Create a hash of the source for the directory name
+    source_hash = hashlib.sha256(source.encode()).hexdigest()[:16]
+
+    # Extract repo name for human-readable cache directory name
+    readable_name = extract_repo_name(source)
+
+    cache_name = f"{readable_name}-{source_hash}"
+    return cache_dir / cache_name
+
+
+def _resolve_local_source(url: str, subpath: str | None) -> 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.
+    """
+    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")
+
+
+def _fetch_remote_source(
+    url: str,
+    cache_dir: Path,
+    ref: str | None,
+    update: bool,
+    subpath: str | None,
+    git_helper: GitHelper | None,
+    source: str,
+) -> Path:
+    """Fetch a remote plugin source and cache it locally.
+
+    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:
+        Path to the cached plugin directory.
+
+    Raises:
+        PluginFetchError: If fetching fails or subpath is invalid.
+    """
+    plugin_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=plugin_path,
+        ref=ref,
+        update=update,
+        git_helper=git_helper,
+    )
+
+    if result is None:
+        raise PluginFetchError(f"Failed to fetch plugin from {source}")
+
+    return _apply_subpath(plugin_path, subpath, "plugin repository")
+
+
+def _apply_subpath(base_path: Path, subpath: str | None, context: str) -> Path:
+    """Apply a subpath to a base path, validating it exists.
+
+    Args:
+        base_path: The root path.
+        subpath: Optional subdirectory path (may have leading/trailing slashes).
+        context: Description for error messages (e.g., "plugin repository").
+
+    Returns:
+        The final path (base_path if no subpath, otherwise base_path/subpath).
+
+    Raises:
+        PluginFetchError: If subpath doesn't exist.
+    """
+    if not subpath:
+        return base_path
+
+    final_path = base_path / subpath.strip("/")
+    if not final_path.exists():
+        raise PluginFetchError(f"Subdirectory '{subpath}' not found in {context}")
+    return final_path
+
+
+def fetch_plugin(
+    source: str,
+    cache_dir: Path | None = None,
+    ref: str | None = None,
+    update: bool = True,
+    subpath: 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
+            - "/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.
+        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.
+
+    Raises:
+        PluginFetchError: If fetching fails or subpath doesn't exist.
+    """
+    source_type, url = parse_plugin_source(source)
+
+    if source_type == "local":
+        return _resolve_local_source(url, subpath)
+
+    if cache_dir is None:
+        cache_dir = DEFAULT_CACHE_DIR
+
+    return _fetch_remote_source(
+        url, cache_dir, ref, update, subpath, git_helper, source
+    )

openhands/sdk/plugin/plugin.py

@@ -16,6 +16,7 @@ from openhands.sdk.context.skills.utils import (
 )
 from openhands.sdk.hooks import HookConfig
 from openhands.sdk.logger import get_logger
+from openhands.sdk.plugin.fetch import fetch_plugin
 from openhands.sdk.plugin.types import (
     AgentDefinition,
     CommandDefinition,
@@ -83,6 +84,59 @@ class Plugin(BaseModel):
         """Get the plugin description."""
         return self.manifest.description
 
+    @classmethod
+    def fetch(
+        cls,
+        source: str,
+        cache_dir: Path | None = None,
+        ref: str | None = None,
+        update: bool = True,
+        subpath: str | None = None,
+    ) -> Path:
+        """Fetch a plugin from a remote source and return the local cached path.
+
+        This method fetches plugins from remote sources (GitHub repositories, git URLs)
+        and caches them locally. Use the returned path with Plugin.load() to load
+        the plugin.
+
+        Args:
+            source: Plugin source - can be:
+                - "github:owner/repo" - GitHub repository shorthand
+                - "https://github.com/owner/repo.git" - Full git URL
+                - "/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.
+
+        Returns:
+            Path to the local plugin directory (ready for Plugin.load()).
+            If subpath is specified, returns the path to that subdirectory.
+
+        Raises:
+            PluginFetchError: If fetching fails or subpath doesn't exist.
+
+        Example:
+            >>> path = Plugin.fetch("github:owner/my-plugin")
+            >>> plugin = Plugin.load(path)
+
+            >>> # With specific version
+            >>> 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")
+            >>> 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
+        )
+
     @classmethod
     def load(cls, plugin_path: str | Path) -> Plugin:
         """Load a plugin from a directory.
@@ -239,10 +293,13 @@ def _load_hooks(plugin_dir: Path) -> HookConfig | None:
 
     try:
         hook_config = HookConfig.load(path=hooks_json)
-        # load() returns empty config on error, check if it has hooks
-        if hook_config.hooks:
-            return hook_config
-        return None
+        # If hooks.json exists but is invalid, HookConfig.load() returns an empty
+        # config and logs the validation error. Keep that distinct from "file not
+        # present" (None).
+        if hook_config.is_empty():
+            logger.info(f"No hooks configured in {hooks_json}")
+            return HookConfig()
+        return hook_config
     except Exception as e:
         logger.warning(f"Failed to load hooks from {hooks_json}: {e}")
         return None