openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/utils/cipher.py

@@ -0,0 +1,68 @@
+"""
+Cipher utility for preventing accidental secret disclosure in serialized data
+
+SECURITY WARNINGS:
+- The secret key is a string for ease of use but should contain at least 256
+  bits of entropy
+"""
+
+import hashlib
+from base64 import b64encode
+
+from cryptography.fernet import Fernet
+from pydantic import SecretStr
+
+
+class Cipher:
+    """
+    Simple encryption utility for preventing accidental secret disclosure.
+    """
+
+    def __init__(self, secret_key: str):
+        self.secret_key = secret_key
+        self._fernet: Fernet | None = None
+
+    def encrypt(self, secret: SecretStr | None) -> str | None:
+        if secret is None:
+            return None
+        secret_value = secret.get_secret_value().encode()
+        fernet = self._get_fernet()
+        result = fernet.encrypt(secret_value).decode()
+        return result
+
+    def decrypt(self, secret: str | None) -> SecretStr | None:
+        """
+        Decrypt a secret value, returning None if decryption fails.
+
+        This handles cases where existing conversations were serialized with different
+        encryption keys or contain invalid encrypted data. A warning is logged when
+        decryption fails and a None is returned. This mimics the case where
+        no cipher was defined so secrets where redacted.
+        """
+        if secret is None:
+            return None
+        try:
+            fernet = self._get_fernet()
+            decrypted = fernet.decrypt(secret.encode()).decode()
+            return SecretStr(decrypted)
+        except Exception as e:
+            # Import here to avoid circular imports
+            from openhands.sdk.logger import get_logger
+
+            logger = get_logger(__name__)
+            logger.warning(
+                f"Failed to decrypt secret value (setting to None): {e}. "
+                "This may occur when loading conversations encrypted with a different "
+                "key or when upgrading from older versions."
+            )
+            return None
+
+    def _get_fernet(self):
+        fernet = self._fernet
+        if fernet is None:
+            secret_key = self.secret_key.encode()
+            # Hash the key to make sure we have a 256 bit value
+            fernet_key = b64encode(hashlib.sha256(secret_key).digest())
+            fernet = Fernet(fernet_key)
+            object.__setattr__(self, "_fernet", fernet)
+        return fernet

openhands/sdk/utils/command.py

@@ -0,0 +1,90 @@
+import shlex
+import subprocess
+import sys
+import threading
+
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+def execute_command(
+    cmd: list[str] | str,
+    env: dict[str, str] | None = None,
+    cwd: str | None = None,
+    timeout: float | None = None,
+    print_output: bool = True,
+) -> subprocess.CompletedProcess:
+    # For string commands, use shell=True to handle shell operators properly
+    if isinstance(cmd, str):
+        cmd_to_run = cmd
+        use_shell = True
+        logger.info("$ %s", cmd)
+    else:
+        cmd_to_run = cmd
+        use_shell = False
+        logger.info("$ %s", " ".join(shlex.quote(c) for c in cmd))
+
+    proc = subprocess.Popen(
+        cmd_to_run,
+        cwd=cwd,
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+        shell=use_shell,
+    )
+    if proc is None:
+        raise RuntimeError("Failed to start process")
+
+    # Read line by line, echo to parent stdout/stderr
+    stdout_lines: list[str] = []
+    stderr_lines: list[str] = []
+    if proc.stdout is None or proc.stderr is None:
+        raise RuntimeError("Failed to capture stdout/stderr")
+
+    def read_stream(stream, lines, output_stream):
+        try:
+            for line in stream:
+                if print_output:
+                    output_stream.write(line)
+                    output_stream.flush()
+                lines.append(line)
+        except Exception as e:
+            logger.error(f"Failed to read stream: {e}")
+
+    # Read stdout and stderr concurrently to avoid deadlock
+    stdout_thread = threading.Thread(
+        target=read_stream, args=(proc.stdout, stdout_lines, sys.stdout)
+    )
+    stderr_thread = threading.Thread(
+        target=read_stream, args=(proc.stderr, stderr_lines, sys.stderr)
+    )
+
+    stdout_thread.start()
+    stderr_thread.start()
+
+    try:
+        proc.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        stdout_thread.join()
+        stderr_thread.join()
+        return subprocess.CompletedProcess(
+            cmd_to_run,
+            -1,  # Indicate timeout with -1 exit code
+            "".join(stdout_lines),
+            "".join(stderr_lines),
+        )
+
+    stdout_thread.join(timeout=timeout)
+    stderr_thread.join(timeout=timeout)
+
+    return subprocess.CompletedProcess(
+        cmd_to_run,
+        proc.returncode,
+        "".join(stdout_lines),
+        "".join(stderr_lines),
+    )

openhands/sdk/utils/deprecation.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from datetime import date
+from functools import cache
+from importlib.metadata import PackageNotFoundError, version as get_version
+from typing import Any, TypeVar, cast
+
+from deprecation import (
+    DeprecatedWarning,
+    UnsupportedWarning,
+    deprecated as _deprecated,
+)
+from packaging import version as pkg_version
+
+
+_FuncT = TypeVar("_FuncT", bound=Callable[..., Any])
+
+
+@cache
+def _current_version() -> str:
+    try:
+        return get_version("openhands-sdk")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+def deprecated(
+    *,
+    deprecated_in: str,
+    removed_in: str | date | None,
+    current_version: str | None = None,
+    details: str = "",
+) -> Callable[[_FuncT], _FuncT]:
+    """Return a decorator that deprecates a callable with explicit metadata.
+
+    Use this helper when you can annotate a function, method, or property with
+    `@deprecated(...)`. It transparently forwards to :func:`deprecation.deprecated`
+    while filling in the SDK's current version metadata unless custom values are
+    supplied.
+    """
+
+    base_decorator = _deprecated(
+        deprecated_in=deprecated_in,
+        removed_in=removed_in,
+        current_version=current_version or _current_version(),
+        details=details,
+    )
+
+    def decorator(func: _FuncT) -> _FuncT:
+        return cast(_FuncT, base_decorator(func))
+
+    return decorator
+
+
+def _should_warn(
+    *,
+    deprecated_in: str | None,
+    removed_in: str | date | None,
+    current_version: str | None,
+) -> tuple[bool, bool]:
+    is_deprecated = False
+    is_unsupported = False
+
+    if isinstance(removed_in, date):
+        if date.today() >= removed_in:
+            is_unsupported = True
+        else:
+            is_deprecated = True
+    elif current_version:
+        current = pkg_version.parse(current_version)
+        if removed_in and current >= pkg_version.parse(str(removed_in)):
+            is_unsupported = True
+        elif deprecated_in and current >= pkg_version.parse(deprecated_in):
+            is_deprecated = True
+    else:
+        is_deprecated = True
+
+    return is_deprecated, is_unsupported
+
+
+def warn_deprecated(
+    feature: str,
+    *,
+    deprecated_in: str,
+    removed_in: str | date | None,
+    current_version: str | None = None,
+    details: str = "",
+    stacklevel: int = 2,
+) -> None:
+    """Emit a deprecation warning for dynamic access to a legacy feature.
+
+    Prefer this helper when a decorator is not practical—e.g. attribute accessors,
+    data migrations, or other runtime paths that must conditionally warn. Provide
+    explicit version metadata so the SDK reports consistent messages and upgrades
+    to :class:`deprecation.UnsupportedWarning` after the removal threshold.
+    """
+
+    current_version = current_version or _current_version()
+    is_deprecated, is_unsupported = _should_warn(
+        deprecated_in=deprecated_in,
+        removed_in=removed_in,
+        current_version=current_version,
+    )
+
+    if not (is_deprecated or is_unsupported):
+        return
+
+    warning_cls = UnsupportedWarning if is_unsupported else DeprecatedWarning
+    warning = warning_cls(feature, deprecated_in, removed_in, details)
+    warnings.warn(warning, stacklevel=stacklevel)
+
+
+def warn_cleanup(
+    workaround: str,
+    *,
+    cleanup_by: str | date,
+    current_version: str | None = None,
+    details: str = "",
+    stacklevel: int = 2,
+) -> None:
+    """Emit a warning for temporary workarounds that need cleanup by a deadline.
+
+    Use this helper for temporary code that addresses upstream issues, compatibility
+    shims, or other workarounds that should be removed once external conditions
+    change (e.g., when a library adds support for a feature, or when an API
+    stabilizes). The deprecation check workflow will fail when the cleanup deadline
+    is reached, ensuring the workaround is removed before the specified version or
+    date.
+
+    Args:
+        workaround: Description of the temporary workaround
+        cleanup_by: Version string or date when this workaround must be removed
+        current_version: Override the detected package version (for testing)
+        details: Additional context about why cleanup is needed
+        stacklevel: Stack level for warning emission
+    """
+    current_version = current_version or _current_version()
+
+    should_cleanup = False
+    if isinstance(cleanup_by, date):
+        should_cleanup = date.today() >= cleanup_by
+    else:
+        try:
+            current = pkg_version.parse(current_version)
+            target = pkg_version.parse(str(cleanup_by))
+            should_cleanup = current >= target
+        except pkg_version.InvalidVersion:
+            pass
+
+    if should_cleanup:
+        message = (
+            f"Cleanup required: {workaround}. "
+            f"This workaround was scheduled for removal by {cleanup_by}."
+        )
+        if details:
+            message += f" {details}"
+        warnings.warn(message, UserWarning, stacklevel=stacklevel)
+
+
+__all__ = [
+    "deprecated",
+    "warn_deprecated",
+    "warn_cleanup",
+]

openhands/sdk/utils/github.py

@@ -0,0 +1,44 @@
+"""Utility functions for GitHub integrations."""
+
+import re
+
+
+# Zero-width joiner character (U+200D)
+# We use ZWJ instead of ZWSP (U+200B) because:
+# - ZWJ is semantically more appropriate (joins characters without adding space)
+# - ZWJ has better support in modern renderers
+# - ZWJ is invisible and doesn't affect text rendering or selection
+ZWJ = "\u200d"
+
+
+def sanitize_openhands_mentions(text: str) -> str:
+    """Sanitize @OpenHands mentions in text to prevent self-mention loops.
+
+    This function inserts a zero-width joiner (ZWJ) after the @ symbol in
+    @OpenHands mentions, making them non-clickable in GitHub comments while
+    preserving readability. The original case of the mention is preserved.
+
+    Args:
+        text: The text to sanitize
+
+    Returns:
+        Text with sanitized @OpenHands mentions (e.g., "@OpenHands" -> "@‍OpenHands")
+
+    Examples:
+        >>> sanitize_openhands_mentions("Thanks @OpenHands for the help!")
+        'Thanks @\\u200dOpenHands for the help!'
+        >>> sanitize_openhands_mentions("Check @openhands and @OPENHANDS")
+        'Check @\\u200dopenhands and @\\u200dOPENHANDS'
+        >>> sanitize_openhands_mentions("No mention here")
+        'No mention here'
+    """
+    # Pattern to match @OpenHands mentions at word boundaries
+    # Uses re.IGNORECASE so we don't need [Oo]pen[Hh]ands
+    # Capture group preserves the original case
+    pattern = r"@(OpenHands)\b"
+
+    # Replace @ with @ + ZWJ while preserving the original case
+    # The \1 backreference preserves the matched case
+    sanitized = re.sub(pattern, f"@{ZWJ}\\1", text, flags=re.IGNORECASE)
+
+    return sanitized

openhands/sdk/utils/json.py

@@ -0,0 +1,48 @@
+import json
+from datetime import datetime
+from typing import Any
+
+from litellm.types.utils import ModelResponse
+
+from openhands.sdk.llm.exceptions import LLMResponseError
+from openhands.sdk.llm.utils.metrics import Metrics
+
+
+class OpenHandsJSONEncoder(json.JSONEncoder):
+    """Custom JSON encoder that handles datetime and other OH objects"""
+
+    def default(self, o: object) -> Any:
+        if isinstance(o, datetime):
+            return o.isoformat()
+        if isinstance(o, Metrics):
+            return o.get()
+        if isinstance(o, ModelResponse):
+            return o.model_dump()
+        return super().default(o)
+
+
+# Create a single reusable encoder instance
+_json_encoder = OpenHandsJSONEncoder()
+
+
+def dumps(obj, **kwargs):
+    """Serialize an object to str format"""
+    if not kwargs:
+        return _json_encoder.encode(obj)
+
+    # Create a copy of the kwargs to avoid modifying the original
+    encoder_kwargs = kwargs.copy()
+
+    # If cls is specified, use it; otherwise use our custom encoder
+    if "cls" not in encoder_kwargs:
+        encoder_kwargs["cls"] = OpenHandsJSONEncoder
+
+    return json.dumps(obj, **encoder_kwargs)
+
+
+def loads(json_str, **kwargs):
+    """Create a JSON object from str"""
+    try:
+        return json.loads(json_str, **kwargs)
+    except json.JSONDecodeError:
+        raise LLMResponseError("No valid JSON object found in response.")