openhands-sdk 1.7.0__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/io/__init__.py

@@ -0,0 +1,6 @@
+from .base import FileStore
+from .local import LocalFileStore
+from .memory import InMemoryFileStore
+
+
+__all__ = ["LocalFileStore", "FileStore", "InMemoryFileStore"]

openhands/sdk/io/base.py

@@ -0,0 +1,48 @@
+from abc import ABC, abstractmethod
+
+
+class FileStore(ABC):
+    """Abstract base class for file storage operations.
+
+    This class defines the interface for file storage backends that can
+    handle basic file operations like reading, writing, listing, and deleting files.
+    """
+
+    @abstractmethod
+    def write(self, path: str, contents: str | bytes) -> None:
+        """Write contents to a file at the specified path.
+
+        Args:
+            path: The file path where contents should be written.
+            contents: The data to write, either as string or bytes.
+        """
+
+    @abstractmethod
+    def read(self, path: str) -> str:
+        """Read and return the contents of a file as a string.
+
+        Args:
+            path: The file path to read from.
+
+        Returns:
+            The file contents as a string.
+        """
+
+    @abstractmethod
+    def list(self, path: str) -> list[str]:
+        """List all files and directories at the specified path.
+
+        Args:
+            path: The directory path to list contents from.
+
+        Returns:
+            A list of file and directory names in the specified path.
+        """
+
+    @abstractmethod
+    def delete(self, path: str) -> None:
+        """Delete the file or directory at the specified path.
+
+        Args:
+            path: The file or directory path to delete.
+        """

openhands/sdk/io/local.py

@@ -0,0 +1,82 @@
+import os
+import shutil
+
+from openhands.sdk.logger import get_logger
+from openhands.sdk.observability.laminar import observe
+
+from .base import FileStore
+
+
+logger = get_logger(__name__)
+
+
+class LocalFileStore(FileStore):
+    root: str
+
+    def __init__(self, root: str):
+        if root.startswith("~"):
+            root = os.path.expanduser(root)
+        root = os.path.abspath(os.path.normpath(root))
+        self.root = root
+        os.makedirs(self.root, exist_ok=True)
+
+    def get_full_path(self, path: str) -> str:
+        # strip leading slash to keep relative under root
+        if path.startswith("/"):
+            path = path[1:]
+        # normalize path separators to handle both Unix (/) and Windows (\) styles
+        normalized_path = path.replace("\\", "/")
+        full = os.path.abspath(
+            os.path.normpath(os.path.join(self.root, normalized_path))
+        )
+        # ensure sandboxing
+        if os.path.commonpath([self.root, full]) != self.root:
+            raise ValueError(f"path escapes filestore root: {path}")
+        return full
+
+    @observe(name="LocalFileStore.write", span_type="TOOL")
+    def write(self, path: str, contents: str | bytes) -> None:
+        full_path = self.get_full_path(path)
+        os.makedirs(os.path.dirname(full_path), exist_ok=True)
+        if isinstance(contents, str):
+            with open(full_path, "w", encoding="utf-8") as f:
+                f.write(contents)
+        else:
+            with open(full_path, "wb") as f:
+                f.write(contents)
+
+    def read(self, path: str) -> str:
+        full_path = self.get_full_path(path)
+        with open(full_path, encoding="utf-8") as f:
+            return f.read()
+
+    @observe(name="LocalFileStore.list", span_type="TOOL")
+    def list(self, path: str) -> list[str]:
+        full_path = self.get_full_path(path)
+        if not os.path.exists(full_path):
+            return []
+
+        # If path is a file, return the file itself (S3-consistent behavior)
+        if os.path.isfile(full_path):
+            return [path]
+
+        # Otherwise it's a directory, return its contents
+        files = [os.path.join(path, f) for f in os.listdir(full_path)]
+        files = [f + "/" if os.path.isdir(self.get_full_path(f)) else f for f in files]
+        return files
+
+    @observe(name="LocalFileStore.delete", span_type="TOOL")
+    def delete(self, path: str) -> None:
+        try:
+            full_path = self.get_full_path(path)
+            if not os.path.exists(full_path):
+                logger.debug(f"Local path does not exist: {full_path}")
+                return
+            if os.path.isfile(full_path):
+                os.remove(full_path)
+                logger.debug(f"Removed local file: {full_path}")
+            elif os.path.isdir(full_path):
+                shutil.rmtree(full_path)
+                logger.debug(f"Removed local directory: {full_path}")
+        except Exception as e:
+            logger.error(f"Error clearing local file store: {str(e)}")

openhands/sdk/io/memory.py

@@ -0,0 +1,54 @@
+import os
+
+from openhands.sdk.io.base import FileStore
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class InMemoryFileStore(FileStore):
+    files: dict[str, str]
+
+    def __init__(self, files: dict[str, str] | None = None) -> None:
+        self.files = {}
+        if files is not None:
+            self.files = files
+
+    def write(self, path: str, contents: str | bytes) -> None:
+        if isinstance(contents, bytes):
+            contents = contents.decode("utf-8")
+        self.files[path] = contents
+
+    def read(self, path: str) -> str:
+        if path not in self.files:
+            raise FileNotFoundError(path)
+        return self.files[path]
+
+    def list(self, path: str) -> list[str]:
+        files = []
+        for file in self.files:
+            if not file.startswith(path):
+                continue
+            suffix = file.removeprefix(path)
+            parts = suffix.split("/")
+            if parts[0] == "":
+                parts.pop(0)
+            if len(parts) == 1:
+                files.append(file)
+            else:
+                dir_path = os.path.join(path, parts[0])
+                if not dir_path.endswith("/"):
+                    dir_path += "/"
+                if dir_path not in files:
+                    files.append(dir_path)
+        return files
+
+    def delete(self, path: str) -> None:
+        try:
+            keys_to_delete = [key for key in self.files.keys() if key.startswith(path)]
+            for key in keys_to_delete:
+                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)}")

openhands/sdk/llm/__init__.py

@@ -0,0 +1,45 @@
+from openhands.sdk.llm.llm import LLM
+from openhands.sdk.llm.llm_registry import LLMRegistry, RegistryEvent
+from openhands.sdk.llm.llm_response import LLMResponse
+from openhands.sdk.llm.message import (
+    ImageContent,
+    Message,
+    MessageToolCall,
+    ReasoningItemModel,
+    RedactedThinkingBlock,
+    TextContent,
+    ThinkingBlock,
+    content_to_str,
+)
+from openhands.sdk.llm.router import RouterLLM
+from openhands.sdk.llm.streaming import LLMStreamChunk, TokenCallbackType
+from openhands.sdk.llm.utils.metrics import Metrics, MetricsSnapshot
+from openhands.sdk.llm.utils.unverified_models import (
+    UNVERIFIED_MODELS_EXCLUDING_BEDROCK,
+    get_unverified_models,
+)
+from openhands.sdk.llm.utils.verified_models import VERIFIED_MODELS
+
+
+__all__ = [
+    "LLMResponse",
+    "LLM",
+    "LLMRegistry",
+    "RouterLLM",
+    "RegistryEvent",
+    "Message",
+    "MessageToolCall",
+    "TextContent",
+    "ImageContent",
+    "ThinkingBlock",
+    "RedactedThinkingBlock",
+    "ReasoningItemModel",
+    "content_to_str",
+    "LLMStreamChunk",
+    "TokenCallbackType",
+    "Metrics",
+    "MetricsSnapshot",
+    "VERIFIED_MODELS",
+    "UNVERIFIED_MODELS_EXCLUDING_BEDROCK",
+    "get_unverified_models",
+]

openhands/sdk/llm/exceptions/__init__.py

@@ -0,0 +1,45 @@
+from .classifier import is_context_window_exceeded, looks_like_auth_error
+from .mapping import map_provider_exception
+from .types import (
+    FunctionCallConversionError,
+    FunctionCallNotExistsError,
+    FunctionCallValidationError,
+    LLMAuthenticationError,
+    LLMBadRequestError,
+    LLMContextWindowExceedError,
+    LLMError,
+    LLMMalformedActionError,
+    LLMNoActionError,
+    LLMNoResponseError,
+    LLMRateLimitError,
+    LLMResponseError,
+    LLMServiceUnavailableError,
+    LLMTimeoutError,
+    OperationCancelled,
+    UserCancelledError,
+)
+
+
+__all__ = [
+    # Types
+    "LLMError",
+    "LLMMalformedActionError",
+    "LLMNoActionError",
+    "LLMResponseError",
+    "FunctionCallConversionError",
+    "FunctionCallValidationError",
+    "FunctionCallNotExistsError",
+    "LLMNoResponseError",
+    "LLMContextWindowExceedError",
+    "LLMAuthenticationError",
+    "LLMRateLimitError",
+    "LLMTimeoutError",
+    "LLMServiceUnavailableError",
+    "LLMBadRequestError",
+    "UserCancelledError",
+    "OperationCancelled",
+    # Helpers
+    "is_context_window_exceeded",
+    "looks_like_auth_error",
+    "map_provider_exception",
+]

openhands/sdk/llm/exceptions/classifier.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from litellm.exceptions import BadRequestError, ContextWindowExceededError, OpenAIError
+
+from .types import LLMContextWindowExceedError
+
+
+# Minimal, provider-agnostic context-window detection
+LONG_PROMPT_PATTERNS: list[str] = [
+    "contextwindowexceedederror",
+    "prompt is too long",
+    "input length and `max_tokens` exceed context limit",
+    "please reduce the length of",
+    "the request exceeds the available context size",
+    "context length exceeded",
+    "input exceeds the context window",
+]
+
+
+def is_context_window_exceeded(exception: Exception) -> bool:
+    if isinstance(exception, (ContextWindowExceededError, LLMContextWindowExceedError)):
+        return True
+
+    if not isinstance(exception, (BadRequestError, OpenAIError)):
+        return False
+
+    s = str(exception).lower()
+    return any(p in s for p in LONG_PROMPT_PATTERNS)
+
+
+AUTH_PATTERNS: list[str] = [
+    "invalid api key",
+    "unauthorized",
+    "missing api key",
+    "invalid authentication",
+    "access denied",
+]
+
+
+def looks_like_auth_error(exception: Exception) -> bool:
+    if not isinstance(exception, (BadRequestError, OpenAIError)):
+        return False
+    s = str(exception).lower()
+    if any(p in s for p in AUTH_PATTERNS):
+        return True
+    # Some providers include explicit status codes in message text
+    for code in ("status 401", "status 403"):
+        if code in s:
+            return True
+    return False