openhands 0.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

openhands/tools/execute_bash/definition.py

@@ -1,166 +0,0 @@
-"""Execute bash tool implementation."""
-
-# Import for type annotation
-from typing import TYPE_CHECKING, Literal
-
-from pydantic import Field
-
-from openhands.sdk.llm import ImageContent, TextContent
-from openhands.sdk.tool import ActionBase, ObservationBase, Tool, ToolAnnotations
-from openhands.sdk.utils import maybe_truncate
-from openhands.tools.execute_bash.constants import (
-    MAX_CMD_OUTPUT_SIZE,
-    NO_CHANGE_TIMEOUT_SECONDS,
-)
-from openhands.tools.execute_bash.metadata import CmdOutputMetadata
-
-
-if TYPE_CHECKING:
-    from .impl import BashExecutor
-
-
-class ExecuteBashAction(ActionBase):
-    """Schema for bash command execution."""
-
-    command: str = Field(
-        description="The bash command to execute. Can be empty string to view additional logs when previous exit code is `-1`. Can be `C-c` (Ctrl+C) to interrupt the currently running process. Note: You can only execute one bash command at a time. If you need to run multiple commands sequentially, you can use `&&` or `;` to chain them together."  # noqa
-    )
-    is_input: bool = Field(
-        default=False,
-        description="If True, the command is an input to the running process. If False, the command is a bash command to be executed in the terminal. Default is False.",  # noqa
-    )
-    timeout: float | None = Field(
-        default=None,
-        description=f"Optional. Sets a maximum time limit (in seconds) for running the command. If the command takes longer than this limit, you’ll be asked whether to continue or stop it. If you don’t set a value, the command will instead pause and ask for confirmation when it produces no new output for {NO_CHANGE_TIMEOUT_SECONDS} seconds. Use a higher value if the command is expected to take a long time (like installation or testing), or if it has a known fixed duration (like sleep).",  # noqa
-    )
-
-
-class ExecuteBashObservation(ObservationBase):
-    """A ToolResult that can be rendered as a CLI output."""
-
-    output: str = Field(description="The raw output from the tool.")
-    command: str | None = Field(
-        default=None,
-        description="The bash command that was executed. Can be empty string if the observation is from a previous command that hit soft timeout and is not yet finished.",  # noqa
-    )
-    exit_code: int | None = Field(
-        default=None,
-        description="The exit code of the command. -1 indicates the process hit the soft timeout and is not yet finished.",  # noqa
-    )
-    error: bool = Field(
-        default=False,
-        description="Whether there was an error during command execution.",
-    )
-    timeout: bool = Field(
-        default=False, description="Whether the command execution timed out."
-    )
-    metadata: CmdOutputMetadata = Field(
-        default_factory=CmdOutputMetadata,
-        description="Additional metadata captured from PS1 after command execution.",
-    )
-
-    @property
-    def command_id(self) -> int | None:
-        """Get the command ID from metadata."""
-        return self.metadata.pid
-
-    @property
-    def agent_observation(self) -> list[TextContent | ImageContent]:
-        ret = f"{self.metadata.prefix}{self.output}{self.metadata.suffix}"
-        if self.metadata.working_dir:
-            ret += f"\n[Current working directory: {self.metadata.working_dir}]"
-        if self.metadata.py_interpreter_path:
-            ret += f"\n[Python interpreter: {self.metadata.py_interpreter_path}]"
-        if self.metadata.exit_code != -1:
-            ret += f"\n[Command finished with exit code {self.metadata.exit_code}]"
-        if self.error:
-            ret = f"[There was an error during command execution.]\n{ret}"
-        return [TextContent(text=maybe_truncate(ret, MAX_CMD_OUTPUT_SIZE))]
-
-
-TOOL_DESCRIPTION = """Execute a bash command in the terminal within a persistent shell session.
-
-
-### Command Execution
-* One command at a time: You can only execute one bash command at a time. If you need to run multiple commands sequentially, use `&&` or `;` to chain them together.
-* Persistent session: Commands execute in a persistent shell session where environment variables, virtual environments, and working directory persist between commands.
-* Soft timeout: Commands have a soft timeout of 10 seconds, once that's reached, you have the option to continue or interrupt the command (see section below for details)
-* Shell options: Do NOT use `set -e`, `set -eu`, or `set -euo pipefail` in shell scripts or commands in this environment. The runtime may not support them and can cause unusable shell sessions. If you want to run multi-line bash commands, write the commands to a file and then run it, instead.
-
-### Long-running Commands
-* For commands that may run indefinitely, run them in the background and redirect output to a file, e.g. `python3 app.py > server.log 2>&1 &`.
-* For commands that may run for a long time (e.g. installation or testing commands), or commands that run for a fixed amount of time (e.g. sleep), you should set the "timeout" parameter of your function call to an appropriate value.
-* If a bash command returns exit code `-1`, this means the process hit the soft timeout and is not yet finished. By setting `is_input` to `true`, you can:
-  - Send empty `command` to retrieve additional logs
-  - Send text (set `command` to the text) to STDIN of the running process
-  - Send control commands like `C-c` (Ctrl+C), `C-d` (Ctrl+D), or `C-z` (Ctrl+Z) to interrupt the process
-  - If you do C-c, you can re-start the process with a longer "timeout" parameter to let it run to completion
-
-### Best Practices
-* Directory verification: Before creating new directories or files, first verify the parent directory exists and is the correct location.
-* Directory management: Try to maintain working directory by using absolute paths and avoiding excessive use of `cd`.
-
-### Output Handling
-* Output truncation: If the output exceeds a maximum length, it will be truncated before being returned.
-"""  # noqa
-
-
-execute_bash_tool = Tool(
-    name="execute_bash",
-    input_schema=ExecuteBashAction,
-    output_schema=ExecuteBashObservation,
-    description=TOOL_DESCRIPTION,
-    annotations=ToolAnnotations(
-        title="execute_bash",
-        readOnlyHint=False,
-        destructiveHint=True,
-        idempotentHint=False,
-        openWorldHint=True,
-    ),
-)
-
-
-class BashTool(Tool[ExecuteBashAction, ExecuteBashObservation]):
-    """A Tool subclass that automatically initializes a BashExecutor with auto-detection."""  # noqa: E501
-
-    executor: "BashExecutor"
-
-    def __init__(
-        self,
-        working_dir: str,
-        username: str | None = None,
-        no_change_timeout_seconds: int | None = None,
-        terminal_type: Literal["tmux", "subprocess"] | None = None,
-    ):
-        """Initialize BashTool with executor parameters.
-
-        Args:
-            working_dir: The working directory for bash commands
-            username: Optional username for the bash session
-            no_change_timeout_seconds: Timeout for no output change
-            terminal_type: Force a specific session type:
-                         ('tmux', 'subprocess').
-                         If None, auto-detect based on system capabilities:
-                         - On Windows: PowerShell if available, otherwise subprocess
-                         - On Unix-like: tmux if available, otherwise subprocess
-        """
-        # Import here to avoid circular imports
-        from openhands.tools.execute_bash.impl import BashExecutor
-
-        # Initialize the executor
-        executor = BashExecutor(
-            working_dir=working_dir,
-            username=username,
-            no_change_timeout_seconds=no_change_timeout_seconds,
-            terminal_type=terminal_type,
-        )
-
-        # Initialize the parent Tool with the executor
-        super().__init__(
-            name=execute_bash_tool.name,
-            description=TOOL_DESCRIPTION,
-            input_schema=ExecuteBashAction,
-            output_schema=ExecuteBashObservation,
-            annotations=execute_bash_tool.annotations,
-            executor=executor,
-        )

openhands/tools/execute_bash/impl.py

@@ -1,38 +0,0 @@
-from typing import Literal
-
-from openhands.sdk.tool import ToolExecutor
-from openhands.tools.execute_bash.definition import (
-    ExecuteBashAction,
-    ExecuteBashObservation,
-)
-from openhands.tools.execute_bash.terminal.factory import create_terminal_session
-
-
-class BashExecutor(ToolExecutor):
-    def __init__(
-        self,
-        working_dir: str,
-        username: str | None = None,
-        no_change_timeout_seconds: int | None = None,
-        terminal_type: Literal["tmux", "subprocess"] | None = None,
-    ):
-        """Initialize BashExecutor with auto-detected or specified session type.
-
-        Args:
-            working_dir: Working directory for bash commands
-            username: Optional username for the bash session
-            no_change_timeout_seconds: Timeout for no output change
-            terminal_type: Force a specific session type:
-                         ('tmux', 'subprocess').
-                         If None, auto-detect based on system capabilities
-        """
-        self.session = create_terminal_session(
-            work_dir=working_dir,
-            username=username,
-            no_change_timeout_seconds=no_change_timeout_seconds,
-            terminal_type=terminal_type,
-        )
-        self.session.initialize()
-
-    def __call__(self, action: ExecuteBashAction) -> ExecuteBashObservation:
-        return self.session.execute(action)

openhands/tools/execute_bash/metadata.py

@@ -1,101 +0,0 @@
-"""Metadata for bash command execution."""
-
-import json
-import re
-import traceback
-
-from pydantic import BaseModel, Field
-
-from openhands.sdk.logger import get_logger
-from openhands.tools.execute_bash.constants import (
-    CMD_OUTPUT_METADATA_PS1_REGEX,
-    CMD_OUTPUT_PS1_BEGIN,
-    CMD_OUTPUT_PS1_END,
-)
-
-
-logger = get_logger(__name__)
-
-
-class CmdOutputMetadata(BaseModel):
-    """Additional metadata captured from PS1"""
-
-    exit_code: int = Field(
-        default=-1, description="The exit code of the last executed command."
-    )
-    pid: int = Field(
-        default=-1, description="The process ID of the last executed command."
-    )
-    username: str | None = Field(
-        default=None, description="The username of the current user."
-    )
-    hostname: str | None = Field(
-        default=None, description="The hostname of the machine."
-    )
-    working_dir: str | None = Field(
-        default=None, description="The current working directory."
-    )
-    py_interpreter_path: str | None = Field(
-        default=None, description="The path to the current Python interpreter, if any."
-    )
-    prefix: str = Field(default="", description="Prefix to add to command output")
-    suffix: str = Field(default="", description="Suffix to add to command output")
-
-    @classmethod
-    def to_ps1_prompt(cls) -> str:
-        """Convert the required metadata into a PS1 prompt."""
-        prompt = CMD_OUTPUT_PS1_BEGIN
-        json_str = json.dumps(
-            {
-                "pid": "$!",
-                "exit_code": "$?",
-                "username": r"\u",
-                "hostname": r"\h",
-                "working_dir": r"$(pwd)",
-                "py_interpreter_path": r'$(command -v python || echo "")',
-            },
-            indent=2,
-        )
-        # Make sure we escape double quotes in the JSON string
-        # So that PS1 will keep them as part of the output
-        prompt += json_str.replace('"', r"\"")
-        prompt += CMD_OUTPUT_PS1_END + "\n"  # Ensure there's a newline at the end
-        return prompt
-
-    @classmethod
-    def matches_ps1_metadata(cls, string: str) -> list[re.Match[str]]:
-        matches = []
-        for match in CMD_OUTPUT_METADATA_PS1_REGEX.finditer(string):
-            try:
-                json.loads(match.group(1).strip())  # Try to parse as JSON
-                matches.append(match)
-            except json.JSONDecodeError:
-                logger.debug(
-                    f"Failed to parse PS1 metadata -  Skipping: [{match.group(1)}]"
-                    + traceback.format_exc()
-                )
-                continue  # Skip if not valid JSON
-        return matches
-
-    @classmethod
-    def from_ps1_match(cls, match: re.Match[str]) -> "CmdOutputMetadata":
-        """Extract the required metadata from a PS1 prompt."""
-        metadata = json.loads(match.group(1))
-        # Create a copy of metadata to avoid modifying the original
-        processed = metadata.copy()
-        # Convert numeric fields
-        if "pid" in metadata:
-            try:
-                processed["pid"] = int(float(str(metadata["pid"])))
-            except (ValueError, TypeError):
-                processed["pid"] = -1
-        if "exit_code" in metadata:
-            try:
-                processed["exit_code"] = int(float(str(metadata["exit_code"])))
-            except (ValueError, TypeError):
-                logger.debug(
-                    f"Failed to parse exit code: {metadata['exit_code']}. "
-                    f"Setting to -1."
-                )
-                processed["exit_code"] = -1
-        return cls(**processed)

openhands/tools/execute_bash/terminal/__init__.py

@@ -1,22 +0,0 @@
-from openhands.tools.execute_bash.terminal.factory import create_terminal_session
-from openhands.tools.execute_bash.terminal.interface import (
-    TerminalInterface,
-    TerminalSessionBase,
-)
-from openhands.tools.execute_bash.terminal.subprocess_terminal import SubprocessTerminal
-from openhands.tools.execute_bash.terminal.terminal_session import (
-    TerminalCommandStatus,
-    TerminalSession,
-)
-from openhands.tools.execute_bash.terminal.tmux_terminal import TmuxTerminal
-
-
-__all__ = [
-    "TerminalInterface",
-    "TerminalSessionBase",
-    "TmuxTerminal",
-    "SubprocessTerminal",
-    "TerminalSession",
-    "TerminalCommandStatus",
-    "create_terminal_session",
-]

openhands/tools/execute_bash/terminal/factory.py

@@ -1,113 +0,0 @@
-"""Factory for creating appropriate terminal sessions based on system capabilities."""
-
-import platform
-import subprocess
-from typing import Literal
-
-from openhands.sdk.logger import get_logger
-from openhands.tools.execute_bash.terminal.terminal_session import TerminalSession
-
-
-logger = get_logger(__name__)
-
-
-def _is_tmux_available() -> bool:
-    """Check if tmux is available on the system."""
-    try:
-        result = subprocess.run(
-            ["tmux", "-V"],
-            capture_output=True,
-            text=True,
-            timeout=5.0,
-        )
-        return result.returncode == 0
-    except (subprocess.TimeoutExpired, FileNotFoundError):
-        return False
-
-
-def _is_powershell_available() -> bool:
-    """Check if PowerShell is available on the system."""
-    if platform.system() == "Windows":
-        # Check for Windows PowerShell
-        powershell_cmd = "powershell"
-    else:
-        # Check for PowerShell Core (pwsh) on non-Windows systems
-        powershell_cmd = "pwsh"
-
-    try:
-        result = subprocess.run(
-            [powershell_cmd, "-Command", "Write-Host 'PowerShell Available'"],
-            capture_output=True,
-            text=True,
-            timeout=5.0,
-        )
-        return result.returncode == 0
-    except (subprocess.TimeoutExpired, FileNotFoundError):
-        return False
-
-
-def create_terminal_session(
-    work_dir: str,
-    username: str | None = None,
-    no_change_timeout_seconds: int | None = None,
-    terminal_type: Literal["tmux", "subprocess"] | None = None,
-) -> TerminalSession:
-    """Create an appropriate terminal session based on system capabilities.
-
-    Args:
-        work_dir: Working directory for the session
-        username: Optional username for the session
-        no_change_timeout_seconds: Timeout for no output change
-        terminal_type: Force a specific session type ('tmux', 'subprocess')
-                     If None, auto-detect based on system capabilities
-
-    Returns:
-        TerminalSession instance
-
-    Raises:
-        RuntimeError: If the requested session type is not available
-    """
-    from openhands.tools.execute_bash.terminal.terminal_session import TerminalSession
-
-    if terminal_type:
-        # Force specific session type
-        if terminal_type == "tmux":
-            if not _is_tmux_available():
-                raise RuntimeError("Tmux is not available on this system")
-            from openhands.tools.execute_bash.terminal.tmux_terminal import TmuxTerminal
-
-            logger.info("Using forced TmuxTerminal")
-            terminal = TmuxTerminal(work_dir, username)
-            return TerminalSession(terminal, no_change_timeout_seconds)
-        elif terminal_type == "subprocess":
-            from openhands.tools.execute_bash.terminal.subprocess_terminal import (
-                SubprocessTerminal,
-            )
-
-            logger.info("Using forced SubprocessTerminal")
-            terminal = SubprocessTerminal(work_dir, username)
-            return TerminalSession(terminal, no_change_timeout_seconds)
-        else:
-            raise ValueError(f"Unknown session type: {terminal_type}")
-
-    # Auto-detect based on system capabilities
-    system = platform.system()
-
-    if system == "Windows":
-        raise NotImplementedError("Windows is not supported yet for OpenHands V1.")
-    else:
-        # On Unix-like systems, prefer tmux if available, otherwise use subprocess
-        if _is_tmux_available():
-            from openhands.tools.execute_bash.terminal.tmux_terminal import TmuxTerminal
-
-            logger.info("Auto-detected: Using TmuxTerminal (tmux available)")
-            terminal = TmuxTerminal(work_dir, username)
-            return TerminalSession(terminal, no_change_timeout_seconds)
-        else:
-            from openhands.tools.execute_bash.terminal.subprocess_terminal import (
-                SubprocessTerminal,
-            )
-
-            logger.info("Auto-detected: Using SubprocessTerminal (tmux not available)")
-            terminal = SubprocessTerminal(work_dir, username)
-            return TerminalSession(terminal, no_change_timeout_seconds)

openhands/tools/execute_bash/terminal/interface.py

@@ -1,189 +0,0 @@
-"""Abstract interface for terminal backends."""
-
-import os
-from abc import ABC, abstractmethod
-
-from openhands.tools.execute_bash.definition import (
-    ExecuteBashAction,
-    ExecuteBashObservation,
-)
-
-
-class TerminalInterface(ABC):
-    """Abstract interface for terminal backends.
-
-    This interface abstracts the low-level terminal operations, allowing
-    different backends (tmux, subprocess, PowerShell) to be used with
-    the same high-level session controller logic.
-    """
-
-    def __init__(
-        self,
-        work_dir: str,
-        username: str | None = None,
-    ):
-        """Initialize the terminal interface.
-
-        Args:
-            work_dir: Working directory for the terminal
-            username: Optional username for the terminal session
-        """
-        self.work_dir = work_dir
-        self.username = username
-        self._initialized = False
-        self._closed = False
-
-    @abstractmethod
-    def initialize(self) -> None:
-        """Initialize the terminal backend.
-
-        This should set up the terminal session, configure the shell,
-        and prepare it for command execution.
-        """
-        pass
-
-    @abstractmethod
-    def close(self) -> None:
-        """Clean up the terminal backend.
-
-        This should properly terminate the terminal session and
-        clean up any resources.
-        """
-        pass
-
-    @abstractmethod
-    def send_keys(self, text: str, enter: bool = True) -> None:
-        """Send text/keys to the terminal.
-
-        Args:
-            text: Text or key sequence to send
-            enter: Whether to send Enter key after the text
-        """
-        pass
-
-    @abstractmethod
-    def read_screen(self) -> str:
-        """Read the current terminal screen content.
-
-        Returns:
-            Current visible content of the terminal screen
-        """
-        pass
-
-    @abstractmethod
-    def clear_screen(self) -> None:
-        """Clear the terminal screen and history."""
-        pass
-
-    @abstractmethod
-    def interrupt(self) -> bool:
-        """Send interrupt signal (Ctrl+C) to the terminal.
-
-        Returns:
-            True if interrupt was sent successfully, False otherwise
-        """
-        pass
-
-    @abstractmethod
-    def is_running(self) -> bool:
-        """Check if a command is currently running in the terminal.
-
-        Returns:
-            True if a command is running, False otherwise
-        """
-        pass
-
-    @property
-    def initialized(self) -> bool:
-        """Check if the terminal is initialized."""
-        return self._initialized
-
-    @property
-    def closed(self) -> bool:
-        """Check if the terminal is closed."""
-        return self._closed
-
-    def is_powershell(self) -> bool:
-        """Check if this is a PowerShell terminal.
-
-        Returns:
-            True if this is a PowerShell terminal, False otherwise
-        """
-        return False
-
-
-class TerminalSessionBase(ABC):
-    """Abstract base class for terminal sessions.
-
-    This class defines the common interface for all terminal session implementations,
-    including tmux-based, subprocess-based, and PowerShell-based sessions.
-    """
-
-    def __init__(
-        self,
-        work_dir: str,
-        username: str | None = None,
-        no_change_timeout_seconds: int | None = None,
-    ):
-        """Initialize the terminal session.
-
-        Args:
-            work_dir: Working directory for the session
-            username: Optional username for the session
-            no_change_timeout_seconds: Timeout for no output change
-        """
-        self.work_dir = work_dir
-        self.username = username
-        self.no_change_timeout_seconds = no_change_timeout_seconds
-        self._initialized = False
-        self._closed = False
-        self._cwd = os.path.abspath(work_dir)
-
-    @abstractmethod
-    def initialize(self) -> None:
-        """Initialize the terminal session."""
-        pass
-
-    @abstractmethod
-    def execute(self, action: ExecuteBashAction) -> ExecuteBashObservation:
-        """Execute a command in the terminal session.
-
-        Args:
-            action: The bash action to execute
-
-        Returns:
-            ExecuteBashObservation with the command result
-        """
-        pass
-
-    @abstractmethod
-    def close(self) -> None:
-        """Clean up the terminal session."""
-        pass
-
-    @abstractmethod
-    def interrupt(self) -> bool:
-        """Interrupt the currently running command (equivalent to Ctrl+C).
-
-        Returns:
-            True if interrupt was successful, False otherwise
-        """
-        pass
-
-    @abstractmethod
-    def is_running(self) -> bool:
-        """Check if a command is currently running.
-
-        Returns:
-            True if a command is running, False otherwise
-        """
-        pass
-
-    @property
-    def cwd(self) -> str:
-        """Get the current working directory."""
-        return self._cwd
-
-    def __del__(self) -> None:
-        """Ensure the session is closed when the object is destroyed."""
-        self.close()