Rename ExecuteBashAction/ExecuteBashObservation to TerminalAction/TerminalObservation (#1193)

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

Author: xingyaoww

examples/01_standalone_sdk/02_custom_tools.py

@@ -26,8 +26,8 @@
 )
 from openhands.tools.file_editor import FileEditorTool
 from openhands.tools.terminal import (
-    BashExecutor,
-    ExecuteBashAction,
+    TerminalAction,
+    TerminalExecutor,
     TerminalTool,
 )
 
@@ -71,8 +71,8 @@ def to_llm_content(self) -> Sequence[TextContent | ImageContent]:
 
 
 class GrepExecutor(ToolExecutor[GrepAction, GrepObservation]):
-    def __init__(self, bash: BashExecutor):
-        self.bash: BashExecutor = bash
+    def __init__(self, terminal: TerminalExecutor):
+        self.terminal: TerminalExecutor = terminal
 
     def __call__(self, action: GrepAction, conversation=None) -> GrepObservation:  # noqa: ARG002
         root = os.path.abspath(action.path)
@@ -86,7 +86,7 @@ def __call__(self, action: GrepAction, conversation=None) -> GrepObservation:  #
         else:
             cmd = f"grep -rHnE {pat} {root_q} 2>/dev/null | head -100"
 
-        result = self.bash(ExecuteBashAction(command=cmd))
+        result = self.terminal(TerminalAction(command=cmd))
 
         matches: list[str] = []
         files: set[str] = set()
@@ -125,21 +125,23 @@ class GrepTool(ToolDefinition[GrepAction, GrepObservation]):
 
     @classmethod
     def create(
-        cls, conv_state, bash_executor: BashExecutor | None = None
+        cls, conv_state, terminal_executor: TerminalExecutor | None = None
     ) -> Sequence[ToolDefinition]:
         """Create GrepTool instance with a GrepExecutor.
 
         Args:
             conv_state: Conversation state to get working directory from.
-            bash_executor: Optional bash executor to reuse. If not provided,
+            terminal_executor: Optional terminal executor to reuse. If not provided,
                          a new one will be created.
 
         Returns:
             A sequence containing a single GrepTool instance.
         """
-        if bash_executor is None:
-            bash_executor = BashExecutor(working_dir=conv_state.workspace.working_dir)
-        grep_executor = GrepExecutor(bash_executor)
+        if terminal_executor is None:
+            terminal_executor = TerminalExecutor(
+                working_dir=conv_state.workspace.working_dir
+            )
+        grep_executor = GrepExecutor(terminal_executor)
 
         return [
             cls(
@@ -170,14 +172,14 @@ def create(
 def _make_bash_and_grep_tools(conv_state) -> list[ToolDefinition]:
     """Create terminal and custom grep tools sharing one executor."""
 
-    bash_executor = BashExecutor(working_dir=conv_state.workspace.working_dir)
-    # bash_tool = terminal_tool.set_executor(executor=bash_executor)
-    bash_tool = TerminalTool.create(conv_state, executor=bash_executor)[0]
+    terminal_executor = TerminalExecutor(working_dir=conv_state.workspace.working_dir)
+    # terminal_tool = terminal_tool.set_executor(executor=terminal_executor)
+    terminal_tool = TerminalTool.create(conv_state, executor=terminal_executor)[0]
 
-    # Use the GrepTool.create() method with shared bash_executor
-    grep_tool = GrepTool.create(conv_state, bash_executor=bash_executor)[0]
+    # Use the GrepTool.create() method with shared terminal_executor
+    grep_tool = GrepTool.create(conv_state, terminal_executor=terminal_executor)[0]
 
-    return [bash_tool, grep_tool]
+    return [terminal_tool, grep_tool]
 
 
 register_tool("BashAndGrepToolSet", _make_bash_and_grep_tools)

openhands-sdk/openhands/sdk/tool/tool.py

@@ -165,11 +165,11 @@ def create(cls, conv_state=None, **params):
                     return [cls(name="finish", ..., executor=FinishExecutor())]
 
         Complex tool with initialization parameters:
-            class TerminalTool(ToolDefinition[ExecuteBashAction,
-                ExecuteBashObservation]):
+            class TerminalTool(ToolDefinition[TerminalAction,
+                TerminalObservation]):
                 @classmethod
                 def create(cls, conv_state, **params):
-                    executor = BashExecutor(
+                    executor = TerminalExecutor(
                         working_dir=conv_state.workspace.working_dir,
                         **params,
                     )

openhands-tools/openhands/tools/terminal/README.md

@@ -43,18 +43,20 @@ If bash cannot be found in PATH, the tool will raise a clear error asking you to
 
 ```python
 from openhands.sdk import Conversation
-from openhands.tools.terminal.definition import TerminalTool, ExecuteBashAction
+from openhands.tools.terminal.definition import TerminalTool, TerminalAction
 
 conversation = Conversation()
 tools = TerminalTool.create(conv_state=conversation.state)
 terminal = tools[0]
 
 # Execute a command
-action = ExecuteBashAction(command="echo 'Hello, World!'")
+action = TerminalAction(command="echo 'Hello, World!'")
 result = terminal.executor(action)
 print(result.text)
 ```
 
+**Note:** `TerminalAction` and `TerminalObservation` replace the deprecated `ExecuteBashAction` and `ExecuteBashObservation` (which will be removed in version 1.5.0).
+
 ### With Custom Shell on Nix/macOS
 
 ```python

openhands-tools/openhands/tools/terminal/__init__.py

@@ -2,9 +2,11 @@
 from openhands.tools.terminal.definition import (
     ExecuteBashAction,
     ExecuteBashObservation,
+    TerminalAction,
+    TerminalObservation,
     TerminalTool,
 )
-from openhands.tools.terminal.impl import BashExecutor
+from openhands.tools.terminal.impl import BashExecutor, TerminalExecutor
 
 # Terminal session architecture - import from sessions package
 from openhands.tools.terminal.terminal import (
@@ -17,6 +19,10 @@
 __all__ = [
     # === Core Tool Interface ===
     "TerminalTool",
+    "TerminalAction",
+    "TerminalObservation",
+    "TerminalExecutor",
+    # === Deprecated Aliases (backward compatibility) ===
     "ExecuteBashAction",
     "ExecuteBashObservation",
     "BashExecutor",

openhands-tools/openhands/tools/terminal/definition.py

@@ -28,7 +28,7 @@
 from openhands.tools.terminal.metadata import CmdOutputMetadata
 
 
-class ExecuteBashAction(Action):
+class TerminalAction(Action):
     """Schema for bash command execution."""
 
     command: str = Field(
@@ -78,7 +78,7 @@ def visualize(self) -> Text:
         return content
 
 
-class ExecuteBashObservation(Observation):
+class TerminalObservation(Observation):
     """A ToolResult that can be rendered as a CLI output."""
 
     command: str | None = Field(
@@ -109,7 +109,7 @@ def to_llm_content(self) -> Sequence[TextContent | ImageContent]:
         if self.is_error:
             llm_content.append(TextContent(text=self.ERROR_MESSAGE_HEADER))
 
-        # ExecuteBashObservation always has content as a single TextContent
+        # TerminalObservation always has content as a single TextContent
         content_text = self.text
 
         ret = f"{self.metadata.prefix}{content_text}{self.metadata.suffix}"
@@ -132,7 +132,7 @@ def visualize(self) -> Text:
             text.append("❌ ", style="red bold")
             text.append(self.ERROR_MESSAGE_HEADER, style="bold red")
 
-        # ExecuteBashObservation always has content as a single TextContent
+        # TerminalObservation always has content as a single TextContent
         content_text = self.text
 
         if content_text:
@@ -219,8 +219,8 @@ def visualize(self) -> Text:
 """  # noqa
 
 
-class TerminalTool(ToolDefinition[ExecuteBashAction, ExecuteBashObservation]):
-    """A ToolDefinition subclass that automatically initializes a BashExecutor with auto-detection."""  # noqa: E501
+class TerminalTool(ToolDefinition[TerminalAction, TerminalObservation]):
+    """A ToolDefinition subclass that automatically initializes a TerminalExecutor with auto-detection."""  # noqa: E501
 
     @classmethod
     def create(
@@ -249,15 +249,15 @@ def create(
                        If None, will auto-detect bash from PATH.
         """
         # Import here to avoid circular imports
-        from openhands.tools.terminal.impl import BashExecutor
+        from openhands.tools.terminal.impl import TerminalExecutor
 
         working_dir = conv_state.workspace.working_dir
         if not os.path.isdir(working_dir):
             raise ValueError(f"working_dir '{working_dir}' is not a valid directory")
 
         # Initialize the executor
         if executor is None:
-            executor = BashExecutor(
+            executor = TerminalExecutor(
                 working_dir=working_dir,
                 username=username,
                 no_change_timeout_seconds=no_change_timeout_seconds,
@@ -268,8 +268,8 @@ def create(
         # Initialize the parent ToolDefinition with the executor
         return [
             cls(
-                action_type=ExecuteBashAction,
-                observation_type=ExecuteBashObservation,
+                action_type=TerminalAction,
+                observation_type=TerminalObservation,
                 description=TOOL_DESCRIPTION,
                 annotations=ToolAnnotations(
                     title="terminal",
@@ -285,3 +285,50 @@ def create(
 
 # Automatically register the tool when this module is imported
 register_tool(TerminalTool.name, TerminalTool)
+
+
+# Deprecated aliases for backward compatibility
+class ExecuteBashAction(TerminalAction):
+    """Deprecated: Use TerminalAction instead.
+
+    This class is deprecated and will be removed in version 1.5.0.
+    Please use TerminalAction instead.
+    """
+
+    def __init__(self, **data):  # type: ignore[no-untyped-def]
+        from openhands.sdk.utils.deprecation import warn_deprecated
+
+        warn_deprecated(
+            "ExecuteBashAction",
+            deprecated_in="1.2.0",
+            removed_in="1.5.0",
+            details=(
+                "Use TerminalAction instead. ExecuteBashAction is an "
+                "alias for TerminalAction and will be removed in version 1.5.0."
+            ),
+            stacklevel=3,
+        )
+        super().__init__(**data)
+
+
+class ExecuteBashObservation(TerminalObservation):
+    """Deprecated: Use TerminalObservation instead.
+
+    This class is deprecated and will be removed in version 1.5.0.
+    Please use TerminalObservation instead.
+    """
+
+    def __init__(self, **data):  # type: ignore[no-untyped-def]
+        from openhands.sdk.utils.deprecation import warn_deprecated
+
+        warn_deprecated(
+            "ExecuteBashObservation",
+            deprecated_in="1.2.0",
+            removed_in="1.5.0",
+            details=(
+                "Use TerminalObservation instead. ExecuteBashObservation is an "
+                "alias for TerminalObservation and will be removed in version 1.5.0."
+            ),
+            stacklevel=3,
+        )
+        super().__init__(**data)