Migrate CLI subprocess shell and refactor BashSession architecture (#109)

Co-authored-by: openhands <[email protected]>

Author: xingyaoww

openhands/tools/execute_bash/__init__.py

@@ -1,3 +1,4 @@
+# Core tool interface
 from openhands.tools.execute_bash.definition import (
     BashTool,
     ExecuteBashAction,
@@ -6,11 +7,24 @@
 )
 from openhands.tools.execute_bash.impl import BashExecutor
 
+# Terminal session architecture - import from sessions package
+from openhands.tools.execute_bash.terminal import (
+    TerminalCommandStatus,
+    TerminalSession,
+    create_terminal_session,
+)
+
 
 __all__ = [
+    # === Core Tool Interface ===
+    "BashTool",
     "execute_bash_tool",
     "ExecuteBashAction",
     "ExecuteBashObservation",
     "BashExecutor",
-    "BashTool",
+    # === Terminal Session Architecture ===
+    "TerminalSession",
+    "TerminalCommandStatus",
+    "TerminalSession",
+    "create_terminal_session",
 ]

openhands/tools/execute_bash/definition.py

@@ -1,5 +1,8 @@
 """Execute bash tool implementation."""
 
+# Import for type annotation
+from typing import TYPE_CHECKING, Literal
+
 from pydantic import Field
 
 from openhands.sdk.tool import ActionBase, ObservationBase, Tool, ToolAnnotations
@@ -11,6 +14,10 @@
 )
 
 
+if TYPE_CHECKING:
+    from .impl import BashExecutor
+
+
 class ExecuteBashAction(ActionBase):
     """Schema for bash command execution."""
 
@@ -114,24 +121,39 @@ def agent_observation(self) -> str:
 
 
 class BashTool(Tool[ExecuteBashAction, ExecuteBashObservation]):
-    """A Tool subclass that automatically initializes a BashExecutor."""
+    """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)
+        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__(

openhands/tools/execute_bash/impl.py

@@ -1,18 +1,37 @@
+from typing import Literal
+
 from openhands.sdk.tool import ToolExecutor
-from openhands.tools.execute_bash.bash_session import BashSession
 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,
     ):
-        self.session = BashSession(working_dir, username=username)
+        """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:

openhands/tools/execute_bash/terminal/__init__.py

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,113 @@
+"""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)