openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/utils/pydantic_diff.py

@@ -0,0 +1,85 @@
+from collections.abc import Mapping, Sequence
+
+from pydantic import BaseModel
+
+
+def _normalize(x):
+    # Convert Pydantic models to dicts
+    if isinstance(x, BaseModel):
+        return x.model_dump(exclude_none=True)
+    # Recurse mappings and sequences (but not strings/bytes)
+    if isinstance(x, Mapping):
+        return {k: _normalize(v) for k, v in x.items()}
+    if isinstance(x, Sequence) and not isinstance(x, (str, bytes, bytearray)):
+        return [_normalize(v) for v in x]
+    return x
+
+
+def _structured_diff(a, b):
+    a = _normalize(a)
+    b = _normalize(b)
+
+    # Equal after normalization -> no diff
+    if a == b:
+        return {}
+
+    # Dict vs dict: diff by keys
+    if isinstance(a, Mapping) and isinstance(b, Mapping):
+        keys = set(a) | set(b)
+        out = {}
+        for k in sorted(keys, key=lambda x: (str(type(x)), str(x))):
+            ak = a.get(k, ...)
+            bk = b.get(k, ...)
+            if ak is ...:
+                out[k] = ("<missing>", bk)
+            elif bk is ...:
+                out[k] = (ak, "<missing>")
+            else:
+                sub = _structured_diff(ak, bk)
+                out[k] = sub if sub else (ak, bk) if ak != bk else {}
+        # Remove entries that ended up equal (empty dicts)
+        return {k: v for k, v in out.items() if v != {}}
+
+    # List/tuple vs list/tuple: diff by index
+    if (
+        isinstance(a, Sequence)
+        and isinstance(b, Sequence)
+        and not isinstance(a, (str, bytes, bytearray))
+        and not isinstance(b, (str, bytes, bytearray))
+    ):
+        out = {}
+        n = max(len(a), len(b))
+        for i in range(n):
+            ai = a[i] if i < len(a) else ...
+            bi = b[i] if i < len(b) else ...
+            if ai is ...:
+                out[i] = ("<missing>", bi)
+            elif bi is ...:
+                out[i] = (ai, "<missing>")
+            else:
+                sub = _structured_diff(ai, bi)
+                out[i] = sub if sub else (ai, bi) if ai != bi else {}
+        return {k: v for k, v in out.items() if v != {}}
+
+    # Fallback leaf difference
+    return (a, b)
+
+
+def _format_diff(d, indent=0):
+    if not isinstance(d, Mapping):
+        old, new = d
+        return f"{'  ' * indent}{old!r} -> {new!r}"
+    lines = []
+    pad = "  " * indent
+    for key, val in d.items():
+        if isinstance(val, Mapping):
+            lines.append(f"{pad}{key}:")
+            lines.append(_format_diff(val, indent + 1))
+        else:
+            lines.append(f"{pad}{key}: {_format_diff(val, indent + 1).lstrip()}")
+    return "\n".join(lines)
+
+
+def pretty_pydantic_diff(a: BaseModel, b: BaseModel) -> str:
+    diff = _structured_diff(a, b)
+    return "No differences" if not diff else _format_diff(diff)

openhands/sdk/utils/pydantic_secrets.py

@@ -0,0 +1,64 @@
+from pydantic import SecretStr
+
+from openhands.sdk.utils.cipher import Cipher
+
+
+def serialize_secret(v: SecretStr | None, info):
+    """
+    Serialize secret fields with encryption or redaction.
+
+    - If a cipher is provided in context, encrypts the secret value
+    - If expose_secrets flag is True in context, exposes the actual value
+    - Otherwise, lets Pydantic handle default masking (redaction)
+    - This prevents accidental secret disclosure
+    """  # noqa: E501
+    if v is None:
+        return None
+
+    # check if a cipher is supplied
+    if info.context and info.context.get("cipher"):
+        cipher: Cipher = info.context.get("cipher")
+        return cipher.encrypt(v)
+
+    # Check if the 'expose_secrets' flag is in the serialization context
+    if info.context and info.context.get("expose_secrets"):
+        return v.get_secret_value()
+
+    # Let Pydantic handle the default masking
+    return v
+
+
+def validate_secret(v: str | SecretStr | None, info) -> SecretStr | None:
+    """
+    Deserialize secret fields, handling encryption and empty values.
+
+    Accepts both str and SecretStr inputs, always returns SecretStr | None.
+    - Empty secrets are converted to None
+    - Plain strings are converted to SecretStr
+    - If a cipher is provided in context, attempts to decrypt the value
+    - If decryption fails, the cipher returns None and a warning is logged
+    - This gracefully handles conversations encrypted with different keys or were redacted
+    """  # noqa: E501
+    if v is None:
+        return None
+
+    # Handle both SecretStr and string inputs
+    if isinstance(v, SecretStr):
+        secret_value = v.get_secret_value()
+    else:
+        secret_value = v
+
+    # If the secret is empty, whitespace-only or redacted - return None
+    if not secret_value or not secret_value.strip() or secret_value == "**********":
+        return None
+
+    # check if a cipher is supplied
+    if info.context and info.context.get("cipher"):
+        cipher: Cipher = info.context.get("cipher")
+        return cipher.decrypt(secret_value)
+
+    # Always return SecretStr
+    if isinstance(v, SecretStr):
+        return v
+    else:
+        return SecretStr(secret_value)

openhands/sdk/utils/truncate.py

@@ -0,0 +1,117 @@
+"""Utility functions for truncating text content."""
+
+import hashlib
+from pathlib import Path
+
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+# Default truncation limits
+DEFAULT_TEXT_CONTENT_LIMIT = 50_000
+
+# Default truncation notice
+DEFAULT_TRUNCATE_NOTICE = (
+    "<response clipped><NOTE>Due to the max output limit, only part of the full "
+    "response has been shown to you.</NOTE>"
+)  # 113 chars
+
+DEFAULT_TRUNCATE_NOTICE_WITH_PERSIST = (
+    "<response clipped><NOTE>Due to the max output limit, only part of the full "
+    "response has been shown to you. The complete output has been saved to "
+    "{file_path} - you can use other tools to view the full content (truncated "
+    "part starts around line {line_num}).</NOTE>"
+)
+
+
+def _save_full_content(content: str, save_dir: str, tool_prefix: str) -> str | None:
+    """Save full content to the specified directory and return the file path."""
+
+    save_dir_path = Path(save_dir)
+    save_dir_path.mkdir(parents=True, exist_ok=True)
+
+    # Generate hash-based filename for deduplication
+    content_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()[:8]
+    filename = f"{tool_prefix}_output_{content_hash}.txt"
+    file_path = save_dir_path / filename
+
+    # Only write if file doesn't exist (deduplication)
+    if not file_path.exists():
+        try:
+            file_path.write_text(content, encoding="utf-8")
+        except Exception as e:
+            logger.debug(f"Failed to save full content to {file_path}: {e}")
+            return None
+
+    return str(file_path)
+
+
+def maybe_truncate(
+    content: str,
+    truncate_after: int | None = None,
+    truncate_notice: str = DEFAULT_TRUNCATE_NOTICE,
+    save_dir: str | None = None,
+    tool_prefix: str = "output",
+) -> str:
+    """
+    Truncate the middle of content if it exceeds the specified length.
+
+    Keeps the head and tail of the content to preserve context at both ends.
+    Optionally saves the full content to a file for later investigation.
+
+    Args:
+        content: The text content to potentially truncate
+        truncate_after: Maximum length before truncation. If None, no truncation occurs
+        truncate_notice: Notice to insert in the middle when content is truncated
+        save_dir: Working directory to save full content file in
+        tool_prefix: Prefix for the saved file (e.g., "bash", "browser", "editor")
+
+    Returns:
+        Original content if under limit, or truncated content with head and tail
+        preserved and reference to saved file if applicable
+    """
+    # 1) Early exits: no truncation requested, or content already within limit
+    if not truncate_after or len(content) <= truncate_after or truncate_after < 0:
+        return content
+
+    # 2) If even the base notice doesn't fit, return a slice of it
+    if len(truncate_notice) >= truncate_after:
+        return truncate_notice[:truncate_after]
+
+    # 3) Calculate proposed head size based on base notice
+    # (for consistent line number calc)
+    available_chars = truncate_after - len(truncate_notice)
+    # Prefer giving the "extra" char to head (ceil split)
+    proposed_head = available_chars // 2 + (available_chars % 2)
+
+    # 4) Optionally save full content, then construct the final notice
+    final_notice = truncate_notice
+    if save_dir:
+        saved_file_path = _save_full_content(content, save_dir, tool_prefix)
+        if saved_file_path:
+            # Calculate line number where truncation happens (using head_chars)
+            head_content_lines = len(content[:proposed_head].splitlines())
+
+            final_notice = DEFAULT_TRUNCATE_NOTICE_WITH_PERSIST.format(
+                file_path=saved_file_path,
+                line_num=head_content_lines + 1,  # +1 to indicate next line
+            )
+
+    # 5) If the final notice (with persist info) alone fills the
+    # budget, return a slice of it
+    if len(final_notice) >= truncate_after:
+        return final_notice[:truncate_after]
+
+    # 6) Allocate remaining budget to head/tail
+    remaining = truncate_after - len(final_notice)
+    head_chars = min(
+        proposed_head, remaining
+    )  # Ensure head_chars doesn't exceed remaining
+    tail_chars = remaining - head_chars  # non-negative due to previous checks
+
+    return (
+        content[:head_chars]
+        + final_notice
+        + (content[-tail_chars:] if tail_chars > 0 else "")
+    )

openhands/sdk/utils/visualize.py

@@ -0,0 +1,58 @@
+from rich.text import Text
+
+
+def display_dict(d) -> Text:
+    """Create a Rich Text representation of a dictionary.
+
+    This function is deprecated. Use display_json instead.
+    """
+    return display_json(d)
+
+
+def display_json(data) -> Text:
+    """Create a Rich Text representation of JSON data.
+
+    Handles dictionaries, lists, strings, numbers, booleans, and None values.
+    """
+    content = Text()
+
+    if isinstance(data, dict):
+        for field_name, field_value in data.items():
+            if field_value is None:
+                continue  # skip None fields
+            content.append(f"\n  {field_name}: ", style="bold")
+            if isinstance(field_value, str):
+                # Handle multiline strings with proper indentation
+                if "\n" in field_value:
+                    content.append("\n")
+                    for line in field_value.split("\n"):
+                        content.append(f"    {line}\n")
+                else:
+                    content.append(f'"{field_value}"')
+            elif isinstance(field_value, (list, dict)):
+                content.append(str(field_value))
+            else:
+                content.append(str(field_value))
+    elif isinstance(data, list):
+        content.append(f"[List with {len(data)} items]\n")
+        for i, item in enumerate(data):
+            content.append(f"  [{i}]: ", style="bold")
+            if isinstance(item, str):
+                content.append(f'"{item}"\n')
+            else:
+                content.append(f"{item}\n")
+    elif isinstance(data, str):
+        # Handle multiline strings with proper indentation
+        if "\n" in data:
+            content.append("String:\n")
+            for line in data.split("\n"):
+                content.append(f"  {line}\n")
+        else:
+            content.append(f'"{data}"')
+    elif data is None:
+        content.append("null")
+    else:
+        # Handle numbers, booleans, and other JSON primitives
+        content.append(str(data))
+
+    return content

openhands/sdk/workspace/__init__.py

@@ -0,0 +1,17 @@
+from .base import BaseWorkspace
+from .local import LocalWorkspace
+from .models import CommandResult, FileOperationResult, PlatformType, TargetType
+from .remote import RemoteWorkspace
+from .workspace import Workspace
+
+
+__all__ = [
+    "BaseWorkspace",
+    "CommandResult",
+    "FileOperationResult",
+    "LocalWorkspace",
+    "PlatformType",
+    "RemoteWorkspace",
+    "TargetType",
+    "Workspace",
+]

openhands/sdk/workspace/base.py

@@ -0,0 +1,158 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Annotated, Any
+
+from pydantic import BeforeValidator, Field
+
+from openhands.sdk.git.models import GitChange, GitDiff
+from openhands.sdk.logger import get_logger
+from openhands.sdk.utils.models import DiscriminatedUnionMixin
+from openhands.sdk.workspace.models import CommandResult, FileOperationResult
+
+
+logger = get_logger(__name__)
+
+
+def _convert_path_to_str(v: str | Path) -> str:
+    """Convert Path objects to string for working_dir."""
+    if isinstance(v, Path):
+        return str(v)
+    return v
+
+
+class BaseWorkspace(DiscriminatedUnionMixin, ABC):
+    """Abstract base class for workspace implementations.
+
+    Workspaces provide a sandboxed environment where agents can execute commands,
+    read/write files, and perform other operations. All workspace implementations
+    support the context manager protocol for safe resource management.
+
+    Example:
+        >>> with workspace:
+        ...     result = workspace.execute_command("echo 'hello'")
+        ...     content = workspace.read_file("example.txt")
+    """
+
+    working_dir: Annotated[
+        str,
+        BeforeValidator(_convert_path_to_str),
+        Field(
+            description=(
+                "The working directory for agent operations and tool execution. "
+                "Accepts both string paths and Path objects. "
+                "Path objects are automatically converted to strings."
+            )
+        ),
+    ]
+
+    def __enter__(self) -> "BaseWorkspace":
+        """Enter the workspace context.
+
+        Returns:
+            Self for use in with statements
+        """
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit the workspace context and cleanup resources.
+
+        Default implementation performs no cleanup. Subclasses should override
+        to add cleanup logic (e.g., stopping containers, closing connections).
+
+        Args:
+            exc_type: Exception type if an exception occurred
+            exc_val: Exception value if an exception occurred
+            exc_tb: Exception traceback if an exception occurred
+        """
+        pass
+
+    @abstractmethod
+    def execute_command(
+        self,
+        command: str,
+        cwd: str | Path | None = None,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        """Execute a bash command on the system.
+
+        Args:
+            command: The bash command to execute
+            cwd: Working directory for the command (optional)
+            timeout: Timeout in seconds (defaults to 30.0)
+
+        Returns:
+            CommandResult: Result containing stdout, stderr, exit_code, and other
+                metadata
+
+        Raises:
+            Exception: If command execution fails
+        """
+        ...
+
+    @abstractmethod
+    def file_upload(
+        self,
+        source_path: str | Path,
+        destination_path: str | Path,
+    ) -> FileOperationResult:
+        """Upload a file to the system.
+
+        Args:
+            source_path: Path to the source file
+            destination_path: Path where the file should be uploaded
+
+        Returns:
+            FileOperationResult: Result containing success status and metadata
+
+        Raises:
+            Exception: If file upload fails
+        """
+        ...
+
+    @abstractmethod
+    def file_download(
+        self,
+        source_path: str | Path,
+        destination_path: str | Path,
+    ) -> FileOperationResult:
+        """Download a file from the system.
+
+        Args:
+            source_path: Path to the source file on the system
+            destination_path: Path where the file should be downloaded
+
+        Returns:
+            FileOperationResult: Result containing success status and metadata
+
+        Raises:
+            Exception: If file download fails
+        """
+        ...
+
+    @abstractmethod
+    def git_changes(self, path: str | Path) -> list[GitChange]:
+        """Get the git changes for the repository at the path given.
+
+        Args:
+            path: Path to the git repository
+
+        Returns:
+            list[GitChange]: List of changes
+
+        Raises:
+            Exception: If path is not a git repository or getting changes failed
+        """
+
+    @abstractmethod
+    def git_diff(self, path: str | Path) -> GitDiff:
+        """Get the git diff for the file at the path given.
+
+        Args:
+            path: Path to the file
+
+        Returns:
+            GitDiff: Git diff
+
+        Raises:
+            Exception: If path is not a git repository or getting diff failed
+        """

openhands/sdk/workspace/local.py

@@ -0,0 +1,189 @@
+import shutil
+from pathlib import Path
+from typing import Any
+
+from openhands.sdk.git.git_changes import get_git_changes
+from openhands.sdk.git.git_diff import get_git_diff
+from openhands.sdk.git.models import GitChange, GitDiff
+from openhands.sdk.logger import get_logger
+from openhands.sdk.utils.command import execute_command
+from openhands.sdk.workspace.base import BaseWorkspace
+from openhands.sdk.workspace.models import CommandResult, FileOperationResult
+
+
+logger = get_logger(__name__)
+
+
+class LocalWorkspace(BaseWorkspace):
+    """Local workspace implementation that operates on the host filesystem.
+
+    LocalWorkspace provides direct access to the local filesystem and command execution
+    environment. It's suitable for development and testing scenarios where the agent
+    should operate directly on the host system.
+
+    Example:
+        >>> workspace = LocalWorkspace(working_dir="/path/to/project")
+        >>> with workspace:
+        ...     result = workspace.execute_command("ls -la")
+        ...     content = workspace.read_file("README.md")
+    """
+
+    def __init__(self, *, working_dir: str | Path, **kwargs: Any):
+        # Accept Path in signature for ergonomics and type checkers,
+        # but normalize to str for the underlying model field.
+        super().__init__(working_dir=str(working_dir), **kwargs)
+
+    def execute_command(
+        self,
+        command: str,
+        cwd: str | Path | None = None,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        """Execute a bash command locally.
+
+        Uses the shared shell execution utility to run commands with proper
+        timeout handling, output streaming, and error management.
+
+        Args:
+            command: The bash command to execute
+            cwd: Working directory (optional)
+            timeout: Timeout in seconds
+
+        Returns:
+            CommandResult: Result with stdout, stderr, exit_code, command, and
+                timeout_occurred
+        """
+        logger.debug(f"Executing local bash command: {command} in {cwd}")
+        result = execute_command(
+            command,
+            cwd=str(cwd) if cwd is not None else str(self.working_dir),
+            timeout=timeout,
+            print_output=True,
+        )
+        return CommandResult(
+            command=command,
+            exit_code=result.returncode,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            timeout_occurred=result.returncode == -1,
+        )
+
+    def file_upload(
+        self,
+        source_path: str | Path,
+        destination_path: str | Path,
+    ) -> FileOperationResult:
+        """Upload (copy) a file locally.
+
+        For local systems, file upload is implemented as a file copy operation
+        using shutil.copy2 to preserve metadata.
+
+        Args:
+            source_path: Path to the source file
+            destination_path: Path where the file should be copied
+
+        Returns:
+            FileOperationResult: Result with success status and file information
+        """
+        source = Path(source_path)
+        destination = Path(destination_path)
+
+        logger.debug(f"Local file upload: {source} -> {destination}")
+
+        try:
+            # Ensure destination directory exists
+            destination.parent.mkdir(parents=True, exist_ok=True)
+
+            # Copy the file with metadata preservation
+            shutil.copy2(source, destination)
+
+            return FileOperationResult(
+                success=True,
+                source_path=str(source),
+                destination_path=str(destination),
+                file_size=destination.stat().st_size,
+            )
+
+        except Exception as e:
+            logger.error(f"Local file upload failed: {e}")
+            return FileOperationResult(
+                success=False,
+                source_path=str(source),
+                destination_path=str(destination),
+                error=str(e),
+            )
+
+    def file_download(
+        self,
+        source_path: str | Path,
+        destination_path: str | Path,
+    ) -> FileOperationResult:
+        """Download (copy) a file locally.
+
+        For local systems, file download is implemented as a file copy operation
+        using shutil.copy2 to preserve metadata.
+
+        Args:
+            source_path: Path to the source file
+            destination_path: Path where the file should be copied
+
+        Returns:
+            FileOperationResult: Result with success status and file information
+        """
+        source = Path(source_path)
+        destination = Path(destination_path)
+
+        logger.debug(f"Local file download: {source} -> {destination}")
+
+        try:
+            # Ensure destination directory exists
+            destination.parent.mkdir(parents=True, exist_ok=True)
+
+            # Copy the file with metadata preservation
+            shutil.copy2(source, destination)
+
+            return FileOperationResult(
+                success=True,
+                source_path=str(source),
+                destination_path=str(destination),
+                file_size=destination.stat().st_size,
+            )
+
+        except Exception as e:
+            logger.error(f"Local file download failed: {e}")
+            return FileOperationResult(
+                success=False,
+                source_path=str(source),
+                destination_path=str(destination),
+                error=str(e),
+            )
+
+    def git_changes(self, path: str | Path) -> list[GitChange]:
+        """Get the git changes for the repository at the path given.
+
+        Args:
+            path: Path to the git repository
+
+        Returns:
+            list[GitChange]: List of changes
+
+        Raises:
+            Exception: If path is not a git repository or getting changes failed
+        """
+        path = Path(self.working_dir) / path
+        return get_git_changes(path)
+
+    def git_diff(self, path: str | Path) -> GitDiff:
+        """Get the git diff for the file at the path given.
+
+        Args:
+            path: Path to the file
+
+        Returns:
+            GitDiff: Git diff
+
+        Raises:
+            Exception: If path is not a git repository or getting diff failed
+        """
+        path = Path(self.working_dir) / path
+        return get_git_diff(path)