openhands-sdk 1.8.1__py3-none-any.whl → 1.9.0__py3-none-any.whl

openhands/sdk/git/utils.py

@@ -1,4 +1,5 @@
 import logging
+import re
 import shlex
 import subprocess
 from pathlib import Path
@@ -13,12 +14,17 @@ logger = logging.getLogger(__name__)
 GIT_EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
 
 
-def run_git_command(args: list[str], cwd: str | Path) -> str:
+def run_git_command(
+    args: list[str],
+    cwd: str | Path | None = None,
+    timeout: int = 30,
+) -> str:
     """Run a git command safely without shell injection vulnerabilities.
 
     Args:
         args: List of command arguments (e.g., ['git', 'status', '--porcelain'])
-        cwd: Working directory to run the command in
+        cwd: Working directory to run the command in (optional for commands like clone)
+        timeout: Timeout in seconds (default: 30)
 
     Returns:
         Command output as string
@@ -33,7 +39,7 @@ def run_git_command(args: list[str], cwd: str | Path) -> str:
             capture_output=True,
             text=True,
             check=False,
-            timeout=30,  # Prevent hanging commands
+            timeout=timeout,
         )
 
         if result.returncode != 0:
@@ -212,3 +218,112 @@ def validate_git_repository(repo_dir: str | Path) -> Path:
             raise GitRepositoryError(f"Not a git repository: {repo_path}") from e
 
     return repo_path
+
+
+# ============================================================================
+# Git URL utilities
+# ============================================================================
+
+
+def is_git_url(source: str) -> bool:
+    """Check if a source string looks like a git URL.
+
+    Detects git URLs by their protocol/scheme rather than enumerating providers.
+    This handles any git hosting service (GitHub, GitLab, Codeberg, self-hosted, etc.)
+
+    Args:
+        source: String to check.
+
+    Returns:
+        True if the string appears to be a git URL, False otherwise.
+
+    Examples:
+        >>> is_git_url("https://github.com/owner/repo.git")
+        True
+        >>> is_git_url("git@github.com:owner/repo.git")
+        True
+        >>> is_git_url("/local/path")
+        False
+    """
+    # HTTPS/HTTP URLs to git repositories
+    if source.startswith(("https://", "http://")):
+        return True
+
+    # SSH format: git@host:path or user@host:path
+    if re.match(r"^[\w.-]+@[\w.-]+:", source):
+        return True
+
+    # Git protocol
+    if source.startswith("git://"):
+        return True
+
+    # File protocol (for testing)
+    if source.startswith("file://"):
+        return True
+
+    return False
+
+
+def normalize_git_url(url: str) -> str:
+    """Normalize a git URL by ensuring .git suffix for HTTPS URLs.
+
+    Args:
+        url: Git URL to normalize.
+
+    Returns:
+        Normalized URL with .git suffix for HTTPS/HTTP URLs.
+
+    Examples:
+        >>> normalize_git_url("https://github.com/owner/repo")
+        "https://github.com/owner/repo.git"
+        >>> normalize_git_url("https://github.com/owner/repo.git")
+        "https://github.com/owner/repo.git"
+        >>> normalize_git_url("git@github.com:owner/repo.git")
+        "git@github.com:owner/repo.git"
+    """
+    if url.startswith(("https://", "http://")) and not url.endswith(".git"):
+        url = url.rstrip("/")
+        url = f"{url}.git"
+    return url
+
+
+def extract_repo_name(source: str) -> str:
+    """Extract a human-readable repository name from a git URL or path.
+
+    Extracts the last path component (repo name) and sanitizes it for use
+    in directory names or display purposes.
+
+    Args:
+        source: Git URL or local path string.
+
+    Returns:
+        A sanitized name suitable for use in directory names (max 32 chars).
+
+    Examples:
+        >>> extract_repo_name("https://github.com/owner/my-repo.git")
+        "my-repo"
+        >>> extract_repo_name("git@github.com:owner/my-repo.git")
+        "my-repo"
+        >>> extract_repo_name("/path/to/local-repo")
+        "local-repo"
+    """
+    # Strip common prefixes to get to the path portion
+    name = source
+    for prefix in ("github:", "https://", "http://", "git://", "file://"):
+        if name.startswith(prefix):
+            name = name[len(prefix) :]
+            break
+
+    # Handle SSH format: user@host:path -> path
+    if "@" in name and ":" in name and "/" not in name.split(":")[0]:
+        name = name.split(":", 1)[1]
+
+    # Remove .git suffix and get last path component
+    name = name.rstrip("/").removesuffix(".git")
+    name = name.rsplit("/", 1)[-1]
+
+    # Sanitize: keep alphanumeric, dash, underscore only
+    name = re.sub(r"[^a-zA-Z0-9_-]", "-", name)
+    name = re.sub(r"-+", "-", name).strip("-")
+
+    return name[:32] if name else "repo"

openhands/sdk/hooks/__init__.py

@@ -5,7 +5,12 @@ Hooks are event-driven scripts that execute at specific lifecycle events
 during agent execution, enabling deterministic control over agent behavior.
 """
 
-from openhands.sdk.hooks.config import HookConfig, HookDefinition, HookMatcher
+from openhands.sdk.hooks.config import (
+    HookConfig,
+    HookDefinition,
+    HookMatcher,
+    HookType,
+)
 from openhands.sdk.hooks.conversation_hooks import (
     HookEventProcessor,
     create_hook_callback,
@@ -19,6 +24,7 @@ __all__ = [
     "HookConfig",
     "HookDefinition",
     "HookMatcher",
+    "HookType",
     "HookExecutor",
     "HookResult",
     "HookManager",

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/io/base.py

@@ -1,4 +1,6 @@
 from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from contextlib import contextmanager
 
 
 class FileStore(ABC):
@@ -6,6 +8,9 @@ class FileStore(ABC):
 
     This class defines the interface for file storage backends that can
     handle basic file operations like reading, writing, listing, and deleting files.
+
+    Implementations should provide a locking mechanism via the `lock()` context
+    manager for thread/process-safe operations.
     """
 
     @abstractmethod
@@ -46,3 +51,50 @@ class FileStore(ABC):
         Args:
             path: The file or directory path to delete.
         """
+
+    @abstractmethod
+    def exists(self, path: str) -> bool:
+        """Check if a file or directory exists at the specified path.
+
+        Args:
+            path: The file or directory path to check.
+
+        Returns:
+            True if the path exists, False otherwise.
+        """
+
+    @abstractmethod
+    def get_absolute_path(self, path: str) -> str:
+        """Get the absolute filesystem path for a given relative path.
+
+        Args:
+            path: The relative path within the file store.
+
+        Returns:
+            The absolute path on the filesystem.
+        """
+
+    @abstractmethod
+    @contextmanager
+    def lock(self, path: str, timeout: float = 30.0) -> Iterator[None]:
+        """Acquire an exclusive lock for the given path.
+
+        This context manager provides thread and process-safe locking.
+        Implementations may use file-based locking, threading locks, or
+        other mechanisms as appropriate.
+
+        Args:
+            path: The path to lock (used to identify the lock).
+            timeout: Maximum seconds to wait for lock acquisition.
+
+        Yields:
+            None when lock is acquired.
+
+        Raises:
+            TimeoutError: If lock cannot be acquired within timeout.
+
+        Note:
+            File-based locking (flock) does NOT work reliably on NFS mounts
+            or network filesystems.
+        """
+        yield  # pragma: no cover

openhands/sdk/io/local.py

@@ -1,5 +1,9 @@
 import os
 import shutil
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from filelock import FileLock, Timeout
 
 from openhands.sdk.io.cache import MemoryLRUCache
 from openhands.sdk.logger import get_logger
@@ -117,3 +121,24 @@ class LocalFileStore(FileStore):
 
         except Exception as e:
             logger.error(f"Error clearing local file store: {str(e)}")
+
+    def exists(self, path: str) -> bool:
+        """Check if a file or directory exists."""
+        return os.path.exists(self.get_full_path(path))
+
+    def get_absolute_path(self, path: str) -> str:
+        """Get absolute filesystem path."""
+        return self.get_full_path(path)
+
+    @contextmanager
+    def lock(self, path: str, timeout: float = 30.0) -> Iterator[None]:
+        """Acquire file-based lock using flock."""
+        lock_path = self.get_full_path(path)
+        os.makedirs(os.path.dirname(lock_path), exist_ok=True)
+        file_lock = FileLock(lock_path)
+        try:
+            with file_lock.acquire(timeout=timeout):
+                yield
+        except Timeout:
+            logger.error(f"Failed to acquire lock within {timeout}s: {lock_path}")
+            raise TimeoutError(f"Lock acquisition timed out: {path}")

openhands/sdk/io/memory.py

@@ -1,4 +1,8 @@
 import os
+import threading
+import uuid
+from collections.abc import Iterator
+from contextlib import contextmanager
 
 from openhands.sdk.io.base import FileStore
 from openhands.sdk.logger import get_logger
@@ -9,9 +13,13 @@ logger = get_logger(__name__)
 
 class InMemoryFileStore(FileStore):
     files: dict[str, str]
+    _instance_id: str
+    _lock: threading.Lock
 
     def __init__(self, files: dict[str, str] | None = None) -> None:
         self.files = {}
+        self._instance_id = uuid.uuid4().hex
+        self._lock = threading.Lock()
         if files is not None:
             self.files = files
 
@@ -51,4 +59,29 @@ class InMemoryFileStore(FileStore):
                 del self.files[key]
             logger.debug(f"Cleared in-memory file store: {path}")
         except Exception as e:
-            logger.error(f"Error clearing in-memory file store: {str(e)}")
+            logger.error(f"Error clearing in-memory file store: {e}")
+
+    def exists(self, path: str) -> bool:
+        """Check if a file exists."""
+        if path in self.files:
+            return True
+        return any(f.startswith(path + "/") for f in self.files)
+
+    def get_absolute_path(self, path: str) -> str:
+        """Get absolute path (uses temp dir with unique instance ID)."""
+        import tempfile
+
+        return os.path.join(
+            tempfile.gettempdir(), f"openhands_inmemory_{self._instance_id}", path
+        )
+
+    @contextmanager
+    def lock(self, path: str, timeout: float = 30.0) -> Iterator[None]:
+        """Acquire thread lock for in-memory store."""
+        acquired = self._lock.acquire(timeout=timeout)
+        if not acquired:
+            raise TimeoutError(f"Lock acquisition timed out: {path}")
+        try:
+            yield
+        finally:
+            self._lock.release()

openhands/sdk/llm/llm.py

@@ -424,8 +424,11 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     ) -> None:
         if self.retry_listener is not None:
             self.retry_listener(attempt_number, num_retries, _err)
-        if self._telemetry is not None and _err is not None:
-            self._telemetry.on_error(_err)
+        # NOTE: don't call Telemetry.on_error here.
+        # This function runs for each retried failure (before the next attempt),
+        # which would create noisy duplicate error logs.
+        # The completion()/responses() exception handlers call Telemetry.on_error
+        # after retries are exhausted (final failure), which is what we want to log.
 
     # =========================================================================
     # Serializers
@@ -697,6 +700,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
             telemetry_ctx.update(
                 {
                     "llm_path": "responses",
+                    "instructions": instructions,
                     "input": input_items[:],
                     "tools": tools,
                     "kwargs": {k: v for k, v in call_kwargs.items()},

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/llm/utils/telemetry.py

@@ -1,6 +1,7 @@
 import json
 import os
 import time
+import traceback
 import uuid
 import warnings
 from collections.abc import Callable
@@ -121,7 +122,46 @@ class Telemetry(BaseModel):
         return self.metrics.deep_copy()
 
     def on_error(self, _err: BaseException) -> None:
-        # Stub for error tracking / counters
+        # Best-effort logging for failed requests (so we can debug malformed
+        # request payloads, e.g. orphaned Responses reasoning items).
+        self._last_latency = time.time() - (self._req_start or time.time())
+
+        if not self.log_enabled:
+            return
+        if not self.log_dir and not self._log_completions_callback:
+            return
+
+        try:
+            filename = (
+                f"{self.model_name.replace('/', '__')}-"
+                f"{time.time():.3f}-"
+                f"{uuid.uuid4().hex[:4]}-error.json"
+            )
+
+            data = self._req_ctx.copy()
+            data["error"] = {
+                "type": type(_err).__name__,
+                "message": str(_err),
+                "repr": repr(_err),
+                "traceback": "".join(
+                    traceback.format_exception(type(_err), _err, _err.__traceback__)
+                ),
+            }
+            data["timestamp"] = time.time()
+            data["latency_sec"] = self._last_latency
+            data["cost"] = 0.0
+
+            log_data = json.dumps(data, default=_safe_json, ensure_ascii=False)
+
+            if self._log_completions_callback:
+                self._log_completions_callback(filename, log_data)
+            elif self.log_dir:
+                os.makedirs(self.log_dir, exist_ok=True)
+                fname = os.path.join(self.log_dir, filename)
+                with open(fname, "w", encoding="utf-8") as f:
+                    f.write(log_data)
+        except Exception as e:
+            warnings.warn(f"Telemetry error logging failed: {e}")
         return
 
     # ---------- Helpers ----------
@@ -335,7 +375,6 @@ class Telemetry(BaseModel):
                 os.makedirs(self.log_dir, exist_ok=True)
                 if not os.access(self.log_dir, os.W_OK):
                     raise PermissionError(f"log_dir is not writable: {self.log_dir}")
-
                 fname = os.path.join(self.log_dir, filename)
                 with open(fname, "w", encoding="utf-8") as f:
                     f.write(log_data)