Merge remote-tracking branch 'upstream/main' into test-verify-agent-clean

Author: tosincarik

.github/workflows/cli-build-binary-and-optionally-release.yml

@@ -7,7 +7,7 @@ on:
     push:
         branches: [main]
         tags:
-            - '*-cli'
+            - '*'
     pull_request:
         branches: ['**']
 

.github/workflows/pypi-release.yml

@@ -22,10 +22,10 @@ jobs:
         runs-on: blacksmith-2vcpu-ubuntu-2404
         permissions:
             id-token: write
-    # Run when manually dispatched for "cli" OR for tag pushes that contain '-cli'
+    # Run when manually dispatched for "cli" OR for any tag pushes
         if: |
             (github.event_name == 'workflow_dispatch' && github.event.inputs.reason == 'cli')
-            || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') && contains(github.ref, '-cli'))
+            || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/'))
         steps:
             - name: Checkout repository
               uses: actions/checkout@v4

.gitignore

@@ -193,3 +193,4 @@ $RECYCLE.BIN/
 *.log
 .coverage
 .pytest_cache/
+software-agent-sdk/

Makefile

@@ -1,4 +1,36 @@
-.PHONY: help install install-dev test format clean run
+SHELL := /usr/bin/env bash
+.SHELLFLAGS := -eu -o pipefail -c
+
+# Colors for output
+ECHO := printf '%b\n'
+GREEN := \033[32m
+YELLOW := \033[33m
+RED := \033[31m
+CYAN := \033[36m
+RESET := \033[0m
+
+.PHONY: help install install-dev test format clean run check-uv-version build
+
+check-uv-version:
+	@$(ECHO) "$(YELLOW)Checking uv version...$(RESET)"
+	@UV_VERSION=$$(uv --version | cut -d' ' -f2); \
+	REQUIRED_VERSION=$(REQUIRED_UV_VERSION); \
+	if [ "$$(printf '%s\n' "$$REQUIRED_VERSION" "$$UV_VERSION" | sort -V | head -n1)" != "$$REQUIRED_VERSION" ]; then \
+		$(ECHO) "$(RED)Error: uv version $$UV_VERSION is less than required $$REQUIRED_VERSION$(RESET)"; \
+		$(ECHO) "$(YELLOW)Please update uv with: uv self update$(RESET)"; \
+		exit 1; \
+	fi; \
+	$(ECHO) "$(GREEN)uv version $$UV_VERSION meets requirements$(RESET)"
+
+build: check-uv-version
+	@$(ECHO) "$(CYAN)Setting up OpenHands V1 development environment...$(RESET)"
+	@$(ECHO) "$(YELLOW)Installing dependencies with uv sync --dev...$(RESET)"
+	@uv sync --dev
+	@$(ECHO) "$(GREEN)Dependencies installed successfully.$(RESET)"
+	@$(ECHO) "$(YELLOW)Setting up pre-commit hooks...$(RESET)"
+	@uv run pre-commit install
+	@$(ECHO) "$(GREEN)Pre-commit hooks installed successfully.$(RESET)"
+	@$(ECHO) "$(GREEN)Build complete! Development environment is ready.$(RESET)"
 
 # Default target
 help:

README.md

@@ -1,19 +1,21 @@
 # OpenHands V1 CLI
 
-A **lightweight, modern CLI** to interact with the OpenHands agent (powered by [OpenHands software-agent-sdk](https://github.com/OpenHands/software-agent-sdk)).
+A **lightweight, modern CLI** to interact with the OpenHands agent (powered by [OpenHands Software Agent SDK](https://github.com/OpenHands/software-agent-sdk)).
 
 ---
 
 ## Quickstart
 
 - Prerequisites: Python 3.12+, curl
 - Install uv (package manager):
+
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   # Restart your shell so "uv" is on PATH, or follow the installer hint
   ```
 
 ### Run the CLI locally
+
 ```bash
 make install
 
@@ -24,6 +26,7 @@ uv run openhands
 ```
 
 ### Build a standalone executable
+
 ```bash
 # Build (installs PyInstaller if needed)
 ./build.sh --install-pyinstaller

build.py

@@ -293,6 +293,70 @@ def test_version() -> bool:
         return False
 
 
+def test_acp_executable() -> bool:
+    """Test the ACP server in the built executable with JSON-RPC messages."""
+    print("🧪 Testing ACP server in the built executable...")
+
+    # Import test utilities
+    from openhands_cli.acp_impl.test_utils import test_jsonrpc_messages
+
+    exe_path = Path("dist/openhands")
+    if not exe_path.exists():
+        exe_path = Path("dist/openhands.exe")
+        if not exe_path.exists():
+            print("❌ Executable not found!")
+            return False
+
+    if os.name != "nt":
+        os.chmod(exe_path, 0o755)
+
+    # JSON-RPC messages to test
+    test_messages = [
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": 1,
+                "clientCapabilities": {
+                    "fs": {"readTextFile": True, "writeTextFile": True},
+                    "terminal": True,
+                    "_meta": {"terminal_output": True, "terminal-auth": True},
+                },
+                "clientInfo": {"name": "zed", "title": "Zed", "version": "0.212.7"},
+            },
+        },
+        {
+            "jsonrpc": "2.0",
+            "id": 2,
+            "method": "session/new",
+            "params": {
+                "cwd": "/tmp",
+                "mcpServers": [],
+            },
+        },
+    ]
+
+    # Run the test
+    success, responses = test_jsonrpc_messages(
+        str(exe_path),
+        ["acp"],
+        test_messages,
+        timeout_per_message=15.0,  # Increased timeout for CI environments
+        verbose=True,
+    )
+
+    # Print summary
+    print(f"\n{'=' * 60}")
+    print("ACP Test Summary:")
+    print(f"  Messages sent: {len(test_messages)}")
+    print(f"  Responses received: {len(responses)}")
+    print(f"  Test result: {'✅ PASSED' if success else '❌ FAILED'}")
+    print(f"{'=' * 60}")
+
+    return success
+
+
 # =================================================
 # SECTION: Main
 # =================================================
@@ -317,7 +381,7 @@ def main() -> int:
     )
 
     parser.add_argument(
-        "--no-build", action="store_true", help="Skip testing the built executable"
+        "--no-build", action="store_true", help="Skip building the executable"
     )
 
     args = parser.parse_args()
@@ -356,6 +420,11 @@ def main() -> int:
             print("❌ Executable test failed, build process failed")
             return 1
 
+        print("\n" + "=" * 60)
+        if not test_acp_executable():
+            print("❌ ACP test failed, build process failed")
+            return 1
+
     print("\n🎉 Build process completed!")
     print("📁 Check the 'dist/' directory for your executable")
 

hooks/rthook_profile_imports.py

@@ -22,7 +22,7 @@
     start_time = time.perf_counter()
 
     if _bootstrap is not None:
-        _orig_find_and_load = _bootstrap._find_and_loadn  # type: ignore
+        _orig_find_and_load = _bootstrap._find_and_load  # type: ignore
 
         def _timed_find_and_load(name, import_):
             preloaded = name in sys.modules  # cache hit?

openhands-cli.spec

@@ -36,6 +36,7 @@ a = Analysis(
         *collect_data_files('openhands.sdk'),
         # Include package metadata for importlib.metadata
         *copy_metadata('fastmcp'),
+        *copy_metadata('agent-client-protocol'),
     ],
     hiddenimports=[
         # Explicitly include modules that might not be detected automatically
@@ -48,6 +49,8 @@ a = Analysis(
         *collect_submodules('tiktoken_ext'),
         *collect_submodules('litellm'),
         *collect_submodules('fastmcp'),
+        # Include Agent Client Protocol (ACP) for 'openhands acp' command
+        *collect_submodules('acp'),
         # Include mcp but exclude CLI parts that require typer
         'mcp.types',
         'mcp.client',

openhands_cli/acp_impl/README.md

@@ -0,0 +1,68 @@
+# ACP Implementation
+
+## What is the Agent Client Protocol (ACP)?
+
+The [Agent Client Protocol (ACP)](https://agentclientprotocol.com/protocol/overview) is a standardized communication protocol that enables code editors and IDEs to interact with AI agents. ACP defines how clients (like code editors) and agents (like OpenHands) communicate through a JSON-RPC 2.0 interface.
+
+For more details about the protocol, see the [ACP documentation](https://agentclientprotocol.com/protocol/overview).
+
+## Development Guide
+
+### Setup with Zed IDE
+
+Follow the documentation at [OpenHands ACP Guide](https://docs.openhands.dev/openhands/usage/run-openhands/acp#zed-ide) for general setup instructions.
+
+#### Option 1: Test with PR Branch
+
+Add this agent configuration to test with the PR branch:
+
+```json
+"OpenHands-uvx": {
+  "command": "uvx",
+  "args": [
+    "--from",
+    "git+https://github.com/OpenHands/OpenHands-CLI.git@xw/acp-simplification",
+    "openhands",
+    "acp"
+  ],
+  "env": {}
+}
+```
+
+#### Option 2: Launch Local Instance
+
+Use this configuration to run your local development version:
+
+```json
+"OpenHands-local": {
+  "command": "uv",
+  "args": [
+    "run",
+    "--project",
+    "/YOUR_LOCAL_PATH/OpenHands-CLI",
+    "openhands",
+    "acp"
+  ],
+  "env": {}
+}
+```
+
+### Debugging
+
+In Zed IDE, open ACP logs before starting a conversation:
+- Press `Cmd+Shift+P`
+- Search for **"dev: open acp log"**
+- This visualizes all events between the ACP server and client
+
+### Testing with JSON-RPC CLI
+
+To reproduce errors or test manually, send JSON-RPC events directly using the test script:
+
+```bash
+uv run python scripts/acp/jsonrpc_cli.py ./dist/openhands acp
+```
+
+This interactive CLI allows you to:
+- Send JSON-RPC messages as single lines
+- View stdout/stderr responses
+- Exit with `:q`, `:quit`, or `:exit`

openhands_cli/acp_impl/__init__.py

@@ -0,0 +1 @@
+"""OpenHands Agent Client Protocol (ACP) Implementation."""