openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/git/git_diff.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Get git diff in a single git file for the closest git repo in the file system"""
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+from openhands.sdk.git.exceptions import (
+    GitCommandError,
+    GitPathError,
+    GitRepositoryError,
+)
+from openhands.sdk.git.models import GitDiff
+from openhands.sdk.git.utils import (
+    get_valid_ref,
+    run_git_command,
+    validate_git_repository,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+MAX_FILE_SIZE_FOR_GIT_DIFF = 1024 * 1024  # 1 Mb
+
+
+def get_closest_git_repo(path: Path) -> Path | None:
+    """Find the closest git repository by walking up the directory tree.
+
+    Args:
+        path: Starting path to search from
+
+    Returns:
+        Path to the git repository root, or None if not found
+    """
+    current_path = path.resolve()
+
+    while True:
+        git_path = current_path / ".git"
+        if git_path.exists():  # Could be file (worktree) or directory
+            logger.debug(f"Found git repository at: {current_path}")
+            return current_path
+
+        parent = current_path.parent
+        if parent == current_path:  # Reached filesystem root
+            logger.debug(f"No git repository found for path: {path}")
+            return None
+        current_path = parent
+
+
+def get_git_diff(relative_file_path: str | Path) -> GitDiff:
+    """Get git diff for a single file.
+
+    Args:
+        relative_file_path: Path to the file relative to current working directory
+
+    Returns:
+        GitDiff object containing diff information
+
+    Raises:
+        GitPathError: If file is too large or doesn't exist
+        GitRepositoryError: If not in a git repository
+        GitCommandError: If git commands fail
+    """
+    path = Path(os.getcwd(), relative_file_path).resolve()
+
+    # Check if file exists
+    if not path.exists():
+        raise GitPathError(f"File does not exist: {path}")
+
+    # Check file size
+    try:
+        file_size = os.path.getsize(path)
+        if file_size > MAX_FILE_SIZE_FOR_GIT_DIFF:
+            raise GitPathError(
+                f"File too large for git diff: {file_size} bytes "
+                f"(max: {MAX_FILE_SIZE_FOR_GIT_DIFF} bytes)"
+            )
+    except OSError as e:
+        raise GitPathError(f"Cannot access file: {path}") from e
+
+    # Find git repository
+    closest_git_repo = get_closest_git_repo(path)
+    if not closest_git_repo:
+        raise GitRepositoryError(f"File is not in a git repository: {path}")
+
+    # Validate the git repository
+    validated_repo = validate_git_repository(closest_git_repo)
+
+    current_rev = get_valid_ref(validated_repo)
+    if not current_rev:
+        logger.warning(f"No valid git reference found for {validated_repo}")
+        return GitDiff(modified="", original="")
+
+    # Get the relative path from the git repo root
+    try:
+        relative_path_from_repo = path.relative_to(validated_repo)
+    except ValueError as e:
+        raise GitPathError(f"File is not within git repository: {path}") from e
+
+    # Get old content (from the ref)
+    try:
+        original = run_git_command(
+            ["git", "show", f"{current_rev}:{relative_path_from_repo}"], validated_repo
+        )
+    except GitCommandError:
+        logger.debug(f"No old content found for {path} at ref {current_rev}")
+        original = ""
+
+    # Get new content (current file)
+    try:
+        with open(path, encoding="utf-8") as f:
+            modified = "\n".join(f.read().splitlines())
+    except (OSError, UnicodeDecodeError) as e:
+        logger.error(f"Failed to read file {path}: {e}")
+        modified = ""
+
+    logger.info(f"Generated git diff for {path}")
+    return GitDiff(
+        modified=modified,
+        original=original,
+    )
+
+
+if __name__ == "__main__":
+    diff = get_git_diff(sys.argv[-1])
+    print(json.dumps(diff))

openhands/sdk/git/models.py

@@ -0,0 +1,21 @@
+from enum import Enum
+from pathlib import Path
+
+from pydantic import BaseModel
+
+
+class GitChangeStatus(Enum):
+    MOVED = "MOVED"
+    ADDED = "ADDED"
+    DELETED = "DELETED"
+    UPDATED = "UPDATED"
+
+
+class GitChange(BaseModel):
+    status: GitChangeStatus
+    path: Path
+
+
+class GitDiff(BaseModel):
+    modified: str | None
+    original: str | None

openhands/sdk/git/utils.py

@@ -0,0 +1,189 @@
+import logging
+import shlex
+import subprocess
+from pathlib import Path
+
+from openhands.sdk.git.exceptions import GitCommandError, GitRepositoryError
+
+
+logger = logging.getLogger(__name__)
+
+# Git empty tree hash - this is a well-known constant in git
+# representing the hash of an empty tree object
+GIT_EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+
+
+def run_git_command(args: list[str], cwd: str | Path) -> 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
+
+    Returns:
+        Command output as string
+
+    Raises:
+        GitCommandError: If the git command fails
+    """
+    try:
+        result = subprocess.run(
+            args,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,  # Prevent hanging commands
+        )
+
+        if result.returncode != 0:
+            cmd_str = shlex.join(args)
+            error_msg = f"Git command failed: {cmd_str}"
+            logger.error(
+                f"{error_msg}. Exit code: {result.returncode}. Stderr: {result.stderr}"
+            )
+            raise GitCommandError(
+                message=error_msg,
+                command=args,
+                exit_code=result.returncode,
+                stderr=result.stderr.strip(),
+            )
+
+        logger.debug(f"Git command succeeded: {shlex.join(args)}")
+        return result.stdout.strip()
+
+    except subprocess.TimeoutExpired as e:
+        cmd_str = shlex.join(args)
+        error_msg = f"Git command timed out: {cmd_str}"
+        logger.error(error_msg)
+        raise GitCommandError(
+            message=error_msg,
+            command=args,
+            exit_code=-1,
+            stderr="Command timed out",
+        ) from e
+    except FileNotFoundError as e:
+        error_msg = "Git command not found. Is git installed?"
+        logger.error(error_msg)
+        raise GitCommandError(
+            message=error_msg,
+            command=args,
+            exit_code=-1,
+            stderr="Git executable not found",
+        ) from e
+
+
+def get_valid_ref(repo_dir: str | Path) -> str | None:
+    """Get a valid git reference to compare against.
+
+    Tries multiple strategies to find a valid reference:
+    1. Current branch's origin (e.g., origin/main)
+    2. Default branch (e.g., origin/main, origin/master)
+    3. Merge base with default branch
+    4. Empty tree (for new repositories)
+
+    Args:
+        repo_dir: Path to the git repository
+
+    Returns:
+        Valid git reference hash, or None if no valid reference found
+    """
+    refs_to_try = []
+
+    # Try current branch's origin
+    try:
+        current_branch = run_git_command(
+            ["git", "--no-pager", "rev-parse", "--abbrev-ref", "HEAD"], repo_dir
+        )
+        if current_branch and current_branch != "HEAD":  # Not in detached HEAD state
+            refs_to_try.append(f"origin/{current_branch}")
+            logger.debug(f"Added current branch reference: origin/{current_branch}")
+    except GitCommandError:
+        logger.debug("Could not get current branch name")
+
+    # Try to get default branch from remote
+    try:
+        remote_info = run_git_command(
+            ["git", "--no-pager", "remote", "show", "origin"], repo_dir
+        )
+        for line in remote_info.splitlines():
+            if "HEAD branch:" in line:
+                default_branch = line.split(":")[-1].strip()
+                if default_branch:
+                    refs_to_try.append(f"origin/{default_branch}")
+                    logger.debug(
+                        f"Added default branch reference: origin/{default_branch}"
+                    )
+
+                    # Also try merge base with default branch
+                    try:
+                        merge_base = run_git_command(
+                            [
+                                "git",
+                                "--no-pager",
+                                "merge-base",
+                                "HEAD",
+                                f"origin/{default_branch}",
+                            ],
+                            repo_dir,
+                        )
+                        if merge_base:
+                            refs_to_try.append(merge_base)
+                            logger.debug(f"Added merge base reference: {merge_base}")
+                    except GitCommandError:
+                        logger.debug("Could not get merge base")
+                break
+    except GitCommandError:
+        logger.debug("Could not get remote information")
+
+    # Add empty tree as fallback for new repositories
+    refs_to_try.append(GIT_EMPTY_TREE_HASH)
+    logger.debug(f"Added empty tree reference: {GIT_EMPTY_TREE_HASH}")
+
+    # Find the first valid reference
+    for ref in refs_to_try:
+        try:
+            result = run_git_command(
+                ["git", "--no-pager", "rev-parse", "--verify", ref], repo_dir
+            )
+            if result:
+                logger.debug(f"Using valid reference: {ref} -> {result}")
+                return result
+        except GitCommandError:
+            logger.debug(f"Reference not valid: {ref}")
+            continue
+
+    logger.warning("No valid git reference found")
+    return None
+
+
+def validate_git_repository(repo_dir: str | Path) -> Path:
+    """Validate that the given directory is a git repository.
+
+    Args:
+        repo_dir: Path to check
+
+    Returns:
+        Validated Path object
+
+    Raises:
+        GitRepositoryError: If not a valid git repository
+    """
+    repo_path = Path(repo_dir).resolve()
+
+    if not repo_path.exists():
+        raise GitRepositoryError(f"Directory does not exist: {repo_path}")
+
+    if not repo_path.is_dir():
+        raise GitRepositoryError(f"Path is not a directory: {repo_path}")
+
+    # Check if it's a git repository by looking for .git directory or file
+    git_dir = repo_path / ".git"
+    if not git_dir.exists():
+        # Maybe we're in a subdirectory, try to find the git root
+        try:
+            run_git_command(["git", "rev-parse", "--git-dir"], repo_path)
+        except GitCommandError as e:
+            raise GitRepositoryError(f"Not a git repository: {repo_path}") from e
+
+    return repo_path

openhands/sdk/hooks/__init__.py

@@ -0,0 +1,30 @@
+"""
+OpenHands Hooks System - Event-driven hooks for automation and control.
+
+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.conversation_hooks import (
+    HookEventProcessor,
+    create_hook_callback,
+)
+from openhands.sdk.hooks.executor import HookExecutor, HookResult
+from openhands.sdk.hooks.manager import HookManager
+from openhands.sdk.hooks.types import HookDecision, HookEvent, HookEventType
+
+
+__all__ = [
+    "HookConfig",
+    "HookDefinition",
+    "HookMatcher",
+    "HookExecutor",
+    "HookResult",
+    "HookManager",
+    "HookEvent",
+    "HookEventType",
+    "HookDecision",
+    "HookEventProcessor",
+    "create_hook_callback",
+]

openhands/sdk/hooks/config.py

@@ -0,0 +1,180 @@
+"""Hook configuration loading and management."""
+
+import json
+import logging
+import re
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from openhands.sdk.hooks.types import HookEventType
+
+
+logger = logging.getLogger(__name__)
+
+
+class HookType(str, Enum):
+    """Types of hooks that can be executed."""
+
+    COMMAND = "command"  # Shell command executed via subprocess
+    PROMPT = "prompt"  # LLM-based evaluation (future)
+
+
+class HookDefinition(BaseModel):
+    """A single hook definition."""
+
+    type: HookType = HookType.COMMAND
+    command: str
+    timeout: int = 60
+
+
+class HookMatcher(BaseModel):
+    """Matches events to hooks based on patterns.
+
+    Supports exact match, wildcard (*), and regex (auto-detected or /pattern/).
+    """
+
+    matcher: str = "*"
+    hooks: list[HookDefinition] = Field(default_factory=list)
+
+    # Regex metacharacters that indicate a pattern should be treated as regex
+    _REGEX_METACHARACTERS = set("|.*+?[]()^$\\")
+
+    def matches(self, tool_name: str | None) -> bool:
+        """Check if this matcher matches the given tool name."""
+        # Wildcard matches everything
+        if self.matcher == "*" or self.matcher == "":
+            return True
+
+        if tool_name is None:
+            return self.matcher in ("*", "")
+
+        # Check for explicit regex pattern (enclosed in /)
+        is_regex = (
+            self.matcher.startswith("/")
+            and self.matcher.endswith("/")
+            and len(self.matcher) > 2
+        )
+        if is_regex:
+            pattern = self.matcher[1:-1]
+            try:
+                return bool(re.fullmatch(pattern, tool_name))
+            except re.error:
+                return False
+
+        # Auto-detect regex: if matcher contains metacharacters, treat as regex
+        if any(c in self.matcher for c in self._REGEX_METACHARACTERS):
+            try:
+                return bool(re.fullmatch(self.matcher, tool_name))
+            except re.error:
+                # Invalid regex, fall through to exact match
+                pass
+
+        # Exact match
+        return self.matcher == tool_name
+
+
+class HookConfig(BaseModel):
+    """Configuration for all hooks, loaded from .openhands/hooks.json."""
+
+    hooks: dict[str, list[HookMatcher]] = Field(default_factory=dict)
+
+    @classmethod
+    def load(
+        cls, path: str | Path | None = None, working_dir: str | Path | None = None
+    ) -> "HookConfig":
+        """Load config from path or search .openhands/hooks.json locations.
+
+        Args:
+            path: Explicit path to hooks.json file. If provided, working_dir is ignored.
+            working_dir: Project directory for discovering .openhands/hooks.json.
+                Falls back to cwd if not provided.
+        """
+        if path is None:
+            # Search for hooks.json in standard locations
+            base_dir = Path(working_dir) if working_dir else Path.cwd()
+            search_paths = [
+                base_dir / ".openhands" / "hooks.json",
+                Path.home() / ".openhands" / "hooks.json",
+            ]
+            for search_path in search_paths:
+                if search_path.exists():
+                    path = search_path
+                    break
+
+        if path is None:
+            return cls()
+
+        path = Path(path)
+        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()
+
+    @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,
+                        )
+                    )
+
+        return cls(hooks=hooks)
+
+    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, [])
+
+        result: list[HookDefinition] = []
+        for matcher in matchers:
+            if matcher.matches(tool_name):
+                result.extend(matcher.hooks)
+
+        return result
+
+    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}
+
+    def save(self, path: str | Path) -> None:
+        """Save hook configuration to a JSON file."""
+        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)