Add Windows terminal backend support

.github/workflows/tests.yml

@@ -132,6 +132,60 @@ jobs:
                   path: coverage-tools.dat
                   if-no-files-found: warn
 
+    tools-tests-windows:
+        runs-on: windows-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v5
+              with: {fetch-depth: 0}
+
+            - name: Detect tools changes
+              id: changed
+              uses: tj-actions/changed-files@v47
+              with:
+                  files: |
+                      openhands-tools/**
+                      tests/tools/**
+                      pyproject.toml
+                      uv.lock
+                      .github/workflows/tests.yml
+
+            - name: Install uv
+              if: steps.changed.outputs.any_changed == 'true'
+              uses: astral-sh/setup-uv@v7
+              with:
+                  enable-cache: true
+
+            - name: Install deps
+              if: steps.changed.outputs.any_changed == 'true'
+              run: uv sync --frozen --group dev
+
+            - name: Run Windows terminal tests with coverage
+              if: steps.changed.outputs.any_changed == 'true'
+              run: |
+                  # Clean up any existing coverage file
+                  if (Test-Path .coverage) { Remove-Item .coverage }
+                  $env:CI = "true"
+                  uv run python -m pytest -vvs `
+                    --cov=openhands-tools `
+                    --cov-report=term-missing `
+                    --cov-fail-under=0 `
+                    --cov-config=pyproject.toml `
+                    tests/tools/terminal/test_windows_terminal.py
+                  # Rename coverage file for upload
+                  if (Test-Path .coverage) {
+                    Move-Item .coverage coverage-tools-windows.dat
+                    Write-Host "Windows tools coverage file prepared for upload"
+                  }
+
+            - name: Upload Windows tools coverage
+              if: steps.changed.outputs.any_changed == 'true' && always()
+              uses: actions/upload-artifact@v5
+              with:
+                  name: coverage-tools-windows
+                  path: coverage-tools-windows.dat
+                  if-no-files-found: warn
+
     agent-server-tests:
         runs-on: blacksmith-2vcpu-ubuntu-2404
         steps:
@@ -244,7 +298,7 @@ jobs:
 
     coverage-report:
         runs-on: blacksmith-2vcpu-ubuntu-2404
-        needs: [sdk-tests, tools-tests, agent-server-tests, cross-tests]
+        needs: [sdk-tests, tools-tests, tools-tests-windows, agent-server-tests, cross-tests]
         if: always() && github.event_name == 'pull_request'
         steps:
             - name: Checkout
@@ -274,7 +328,9 @@ jobs:
                     if [[ "$dat_file" == *coverage-sdk.dat ]]; then
                       cp "$dat_file" .coverage.sdk
                     elif [[ "$dat_file" == *coverage-tools.dat ]]; then
-                      cp "$dat_file" .coverage.tools  
+                      cp "$dat_file" .coverage.tools
+                    elif [[ "$dat_file" == *coverage-tools-windows.dat ]]; then
+                      cp "$dat_file" .coverage.tools-windows
                     elif [[ "$dat_file" == *coverage-cross.dat ]]; then
                       cp "$dat_file" .coverage.cross
                     fi

openhands-agent-server/openhands/agent_server/agent-server.spec

@@ -41,6 +41,9 @@ a = Analysis(
         *collect_data_files("openhands.sdk.context.condenser", includes=["prompts/*.j2"]),
         *collect_data_files("openhands.sdk.context.prompts", includes=["templates/*.j2"]),
 
+        # OpenHands Tools terminal templates
+        *collect_data_files("openhands.tools.terminal", includes=["templates/*.j2"]),
+
         # Package metadata for importlib.metadata
         *copy_metadata("fastmcp"),
         *copy_metadata("litellm"),

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

@@ -1,7 +1,9 @@
 """Execute bash tool implementation."""
 
 import os
+import platform
 from collections.abc import Sequence
+from pathlib import Path
 from typing import TYPE_CHECKING, Literal
 
 from pydantic import Field
@@ -200,35 +202,15 @@ def visualize(self) -> Text:
         return text
 
 
-TOOL_DESCRIPTION = """Execute a bash command in the terminal within a persistent shell session.
+def _load_template(template_name: str) -> str:
+    """Load a template file from the templates directory."""
+    template_dir = Path(__file__).parent / "templates"
+    template_path = template_dir / template_name
+    return template_path.read_text(encoding="utf-8")
 
 
-### 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.
-
-### Terminal Reset
-* Terminal reset: If the terminal becomes unresponsive, you can set the "reset" parameter to `true` to create a new terminal session. This will terminate the current session and start fresh.
-* Warning: Resetting the terminal will lose all previously set environment variables, working directory changes, and any running processes. Use this only when the terminal stops responding to commands.
-"""  # noqa
+TOOL_DESCRIPTION_FOR_UNIX = _load_template("unix_description.j2")
+TOOL_DESCRIPTION_FOR_WINDOWS = _load_template("windows_description.j2")
 
 
 class TerminalTool(ToolDefinition[TerminalAction, TerminalObservation]):
@@ -278,12 +260,17 @@ def create(
                 full_output_save_dir=conv_state.env_observation_persistence_dir,
             )
 
+        if platform.system() == "Windows":
+            tool_description = TOOL_DESCRIPTION_FOR_WINDOWS
+        else:
+            tool_description = TOOL_DESCRIPTION_FOR_UNIX
+
         # Initialize the parent ToolDefinition with the executor
         return [
             cls(
                 action_type=TerminalAction,
                 observation_type=TerminalObservation,
-                description=TOOL_DESCRIPTION,
+                description=tool_description,
                 annotations=ToolAnnotations(
                     title="terminal",
                     readOnlyHint=False,

openhands-tools/openhands/tools/terminal/templates/unix_description.j2

@@ -0,0 +1,29 @@
+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.
+
+### Terminal Reset
+* Terminal reset: If the terminal becomes unresponsive, you can set the "reset" parameter to `true` to create a new terminal session. This will terminate the current session and start fresh.
+* Warning: Resetting the terminal will lose all previously set environment variables, working directory changes, and any running processes. Use this only when the terminal stops responding to commands.
+

openhands-tools/openhands/tools/terminal/templates/windows_description.j2

@@ -0,0 +1,31 @@
+Execute a PowerShell command in the terminal within a persistent shell session.
+
+
+### Command Execution
+* One command at a time: You can only execute one PowerShell command at a time. If you need to run multiple commands sequentially, use `;` to chain them together.
+* Bash compatibility: Basic bash commands like `&&` and `||` are automatically converted to PowerShell `;` separator, though conditional execution semantics are not preserved.
+* Persistent session: Commands execute in a persistent PowerShell session where environment variables, modules, 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)
+* PowerShell syntax: Use native PowerShell cmdlets (e.g., `Get-ChildItem`, `Set-Location`) or common aliases (e.g., `ls`, `cd`, `dir`) for best results.
+
+### Long-running Commands
+* For commands that may run indefinitely, run them in the background using PowerShell jobs, e.g. `Start-Job -ScriptBlock { python app.py } | Out-File server.log`.
+* 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. Start-Sleep), you should set the "timeout" parameter of your function call to an appropriate value.
+* If a 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) 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 (use `Test-Path`).
+* Directory management: Try to maintain working directory by using absolute paths and avoiding excessive use of `cd` or `Set-Location`.
+* Path separators: PowerShell handles both forward slashes `/` and backslashes `\\` in paths, but backslashes are native to Windows.
+
+### Output Handling
+* Output truncation: If the output exceeds a maximum length, it will be truncated before being returned.
+
+### Terminal Reset
+* Terminal reset: If the terminal becomes unresponsive, you can set the "reset" parameter to `true` to create a new PowerShell session. This will terminate the current session and start fresh.
+* Warning: Resetting the terminal will lose all previously loaded modules, environment variables, working directory changes, and any running processes. Use this only when the terminal stops responding to commands.
+

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

@@ -1,24 +1,40 @@
+import platform
+
 from openhands.tools.terminal.terminal.factory import create_terminal_session
 from openhands.tools.terminal.terminal.interface import (
     TerminalInterface,
     TerminalSessionBase,
 )
-from openhands.tools.terminal.terminal.subprocess_terminal import (
-    SubprocessTerminal,
-)
 from openhands.tools.terminal.terminal.terminal_session import (
     TerminalCommandStatus,
     TerminalSession,
 )
-from openhands.tools.terminal.terminal.tmux_terminal import TmuxTerminal
 
 
-__all__ = [
-    "TerminalInterface",
-    "TerminalSessionBase",
-    "TmuxTerminal",
-    "SubprocessTerminal",
-    "TerminalSession",
-    "TerminalCommandStatus",
-    "create_terminal_session",
-]
+# Conditionally import platform-specific terminals
+if platform.system() == "Windows":
+    from openhands.tools.terminal.terminal.windows_terminal import WindowsTerminal
+
+    __all__ = [
+        "TerminalInterface",
+        "TerminalSessionBase",
+        "WindowsTerminal",
+        "TerminalSession",
+        "TerminalCommandStatus",
+        "create_terminal_session",
+    ]
+else:
+    from openhands.tools.terminal.terminal.subprocess_terminal import (
+        SubprocessTerminal,
+    )
+    from openhands.tools.terminal.terminal.tmux_terminal import TmuxTerminal
+
+    __all__ = [
+        "TerminalInterface",
+        "TerminalSessionBase",
+        "TmuxTerminal",
+        "SubprocessTerminal",
+        "TerminalSession",
+        "TerminalCommandStatus",
+        "create_terminal_session",
+    ]

openhands-tools/openhands/tools/terminal/terminal/factory.py

@@ -101,7 +101,13 @@ def create_terminal_session(
     system = platform.system()
 
     if system == "Windows":
-        raise NotImplementedError("Windows is not supported yet for OpenHands V1.")
+        from openhands.tools.terminal.terminal.windows_terminal import (
+            WindowsTerminal,
+        )
+
+        logger.info("Auto-detected: Using WindowsTerminal (Windows system)")
+        terminal = WindowsTerminal(work_dir, username)
+        return TerminalSession(terminal, no_change_timeout_seconds)
     else:
         # On Unix-like systems, prefer tmux if available, otherwise use subprocess
         if _is_tmux_available():

openhands-tools/openhands/tools/terminal/terminal/terminal_session.py

@@ -188,6 +188,7 @@ def _handle_completed_command(
         self._ready_for_next_command()
         return TerminalObservation.from_text(
             command=command,
+            exit_code=metadata.exit_code if metadata.exit_code != -1 else None,
             text=command_output,
             metadata=metadata,
         )