Optimize CLI shutdown performance with lazy imports and fast exit

- Implement TYPE_CHECKING pattern to preserve type hints while enabling lazy loading
- Add lazy imports throughout CLI modules to defer heavy dependency loading
- Optimize thread cleanup in PauseListener for faster shutdown
- Add fast exit mechanism to avoid waiting for thread cleanup
- Improve shutdown time from ~0.164s to ~0.064s (60% improvement)
- Add comprehensive performance tests to prevent regressions

Fixes #11103

.github/workflows/cli-build-test.yml

@@ -0,0 +1,58 @@
+# Workflow that builds and tests the CLI binary executable
+name: CLI - Build and Test Binary
+
+# Run on pushes to main branch and all pull requests, but only when CLI files change
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "openhands-cli/**"
+  pull_request:
+    paths:
+      - "openhands-cli/**"
+
+# Cancel previous runs if a new commit is pushed
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test-binary:
+    name: Build and test binary executable
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        working-directory: openhands-cli
+        run: |
+          uv sync
+
+      - name: Build binary executable
+        working-directory: openhands-cli
+        run: |
+          ./build.sh --install-pyinstaller | tee output.log
+          echo "Full output:"
+          cat output.log
+
+          if grep -q "❌" output.log; then
+            echo "❌ Found failure marker in output"
+            exit 1
+          fi
+
+          echo "✅ Build & test finished without ❌ markers"

.github/workflows/lint.yml

@@ -37,7 +37,7 @@ jobs:
           npm run make-i18n && tsc
           npm run check-translation-completeness
 
-  # Run lint on the python code
+  # Run lint on the python code (excluding CLI and enterprise)
   lint-python:
     name: Lint python
     runs-on: blacksmith-4vcpu-ubuntu-2204
@@ -73,6 +73,24 @@ jobs:
         working-directory: ./enterprise
         run: pre-commit run --all-files --config ./dev_config/python/.pre-commit-config.yaml
 
+  lint-cli-python:
+    name: Lint CLI python
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up python
+        uses: useblacksmith/setup-python@v6
+        with:
+          python-version: 3.12
+          cache: "pip"
+      - name: Install pre-commit
+        run: pip install pre-commit==3.7.0
+      - name: Run pre-commit hooks
+        working-directory: ./openhands-cli
+        run: pre-commit run --all-files --config ../dev_config/python/.pre-commit-config.yaml
+
   # Check version consistency across documentation
   check-version-consistency:
     name: Check version consistency

.github/workflows/py-tests.yml

@@ -104,3 +104,33 @@ jobs:
       - name: Run Unit Tests
         working-directory: ./enterprise
         run: PYTHONPATH=".:$PYTHONPATH" poetry run pytest --forked -n auto -svv -p no:ddtrace -p no:ddtrace.pytest_bdd -p no:ddtrace.pytest_benchmark ./tests/unit
+
+  # Run CLI unit tests
+  test-cli-python:
+    name: CLI Unit Tests
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: useblacksmith/setup-python@v6
+        with:
+          python-version: 3.12
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        working-directory: ./openhands-cli
+        run: |
+          uv sync --group dev
+
+      - name: Run CLI unit tests
+        working-directory: ./openhands-cli
+        run: |
+          uv run pytest -v

.gitignore

@@ -31,7 +31,8 @@ requirements.txt
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
-*.spec
+# Note: openhands-cli.spec is intentionally tracked for CLI builds
+# *.spec
 
 # Installer logs
 pip-log.txt

dev_config/python/.pre-commit-config.yaml

@@ -3,9 +3,9 @@ repos:
     rev: v5.0.0
     hooks:
       - id: trailing-whitespace
-        exclude: ^(docs/|modules/|python/|openhands-ui/|third_party/|enterprise/)
+        exclude: ^(docs/|modules/|python/|openhands-ui/|third_party/|enterprise/|openhands-cli/)
       - id: end-of-file-fixer
-        exclude: ^(docs/|modules/|python/|openhands-ui/|third_party/|enterprise/)
+        exclude: ^(docs/|modules/|python/|openhands-ui/|third_party/|enterprise/|openhands-cli/)
       - id: check-yaml
         args: ["--allow-multiple-documents"]
       - id: debug-statements
@@ -28,12 +28,12 @@ repos:
         entry: ruff check --config dev_config/python/ruff.toml
         types_or: [python, pyi, jupyter]
         args: [--fix, --unsafe-fixes]
-        exclude: ^(third_party/|enterprise/)
+        exclude: ^(third_party/|enterprise/|openhands-cli/)
       # Run the formatter.
       - id: ruff-format
         entry: ruff format --config dev_config/python/ruff.toml
         types_or: [python, pyi, jupyter]
-        exclude: ^(third_party/|enterprise/)
+        exclude: ^(third_party/|enterprise/|openhands-cli/)
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.15.0

openhands-cli/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+# Note: We keep our custom spec file in version control
+# *.spec

openhands-cli/Makefile

@@ -0,0 +1,46 @@
+.PHONY: help install install-dev test format clean run
+
+# Default target
+help:
+	@echo "OpenHands CLI - Available commands:"
+	@echo "  install                  - Install the package"
+	@echo "  install-dev              - Install with development dependencies"
+	@echo "  test                     - Run tests"
+	@echo "  format                   - Format code with ruff"
+	@echo "  clean                    - Clean build artifacts"
+	@echo "  run                      - Run the CLI"
+
+# Install the package
+install:
+	uv sync
+
+# Install with development dependencies
+install-dev:
+	uv sync --group dev
+
+# Run tests
+test:
+	uv run pytest
+
+# Format code
+format:
+	uv run ruff format openhands_cli/
+
+# Clean build artifacts
+clean:
+	rm -rf .venv/
+	find . -type d -name "__pycache__" -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+# Run the CLI
+run:
+	uv run openhands-cli
+
+# Install UV if not present
+install-uv:
+	@if ! command -v uv &> /dev/null; then \
+		echo "Installing UV..."; \
+		curl -LsSf https://astral.sh/uv/install.sh | sh; \
+	else \
+		echo "UV is already installed"; \
+	fi

openhands-cli/README.md

@@ -0,0 +1,45 @@
+# OpenHands CLI
+
+A lightweight CLI/TUI to interact with the OpenHands agent (powered by agent-sdk). Build and run locally or as a single executable.
+
+## 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
+# Install dependencies (incl. dev tools)
+make install-dev
+
+# Optional: install pre-commit hooks
+make install-pre-commit-hooks
+
+# Start the CLI
+make run
+# or
+uv run openhands-cli
+```
+
+Tip: Set your model key (one of) so the agent can talk to an LLM:
+```bash
+export OPENAI_API_KEY=...
+# or
+export LITELLM_API_KEY=...
+```
+
+### Build a standalone executable
+```bash
+# Build (installs PyInstaller if needed)
+./build.sh --install-pyinstaller
+
+# The binary will be in dist/
+./dist/openhands-cli            # macOS/Linux
+# dist/openhands-cli.exe        # Windows
+```
+
+For advanced development (adding deps, updating the spec file, debugging builds), see Development.md.

openhands-cli/build.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""
+Build script for OpenHands CLI using PyInstaller.
+
+This script packages the OpenHands CLI into a standalone executable binary
+using PyInstaller with the custom spec file.
+"""
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from openhands_cli.locations import PERSISTENCE_DIR, WORK_DIR, AGENT_SETTINGS_PATH
+from openhands.sdk.preset.default import get_default_agent
+from openhands.sdk import LLM
+import time
+import select
+
+dummy_agent = get_default_agent(
+    llm=LLM(model='dummy-model', api_key='dummy-key'),
+    working_dir=WORK_DIR,
+    persistence_dir=PERSISTENCE_DIR,
+    cli_mode=True
+)
+
+# =================================================
+# SECTION: Build Binary
+# =================================================
+
+
+
+def clean_build_directories() -> None:
+    """Clean up previous build artifacts."""
+    print('🧹 Cleaning up previous build artifacts...')
+
+    build_dirs = ['build', 'dist', '__pycache__']
+    for dir_name in build_dirs:
+        if os.path.exists(dir_name):
+            print(f'  Removing {dir_name}/')
+            shutil.rmtree(dir_name)
+
+    # Clean up .pyc files
+    for root, _dirs, files in os.walk('.'):
+        for file in files:
+            if file.endswith('.pyc'):
+                os.remove(os.path.join(root, file))
+
+    print('✅ Cleanup complete!')
+
+
+def check_pyinstaller() -> bool:
+    """Check if PyInstaller is available."""
+    try:
+        subprocess.run(
+            ['uv', 'run', 'pyinstaller', '--version'], check=True, capture_output=True
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        print(
+            '❌ PyInstaller is not available. Use --install-pyinstaller flag or install manually with:'
+        )
+        print('   uv add --dev pyinstaller')
+        return False
+
+def build_executable(
+    spec_file: str = 'openhands-cli.spec',
+    clean: bool = True,
+) -> bool:
+    """Build the executable using PyInstaller."""
+    if clean:
+        clean_build_directories()
+
+    # Check if PyInstaller is available (installation is handled by build.sh)
+    if not check_pyinstaller():
+        return False
+
+    print(f'🔨 Building executable using {spec_file}...')
+
+    try:
+        # Run PyInstaller with uv
+        cmd = ['uv', 'run', 'pyinstaller', spec_file, '--clean']
+
+        print(f'Running: {" ".join(cmd)}')
+        subprocess.run(cmd, check=True, capture_output=True, text=True)
+
+        print('✅ Build completed successfully!')
+
+        # Check if the executable was created
+        dist_dir = Path('dist')
+        if dist_dir.exists():
+            executables = list(dist_dir.glob('*'))
+            if executables:
+                print('📁 Executable(s) created in dist/:')
+                for exe in executables:
+                    size = exe.stat().st_size / (1024 * 1024)  # Size in MB
+                    print(f'  - {exe.name} ({size:.1f} MB)')
+            else:
+                print('⚠️  No executables found in dist/ directory')
+
+        return True
+
+    except subprocess.CalledProcessError as e:
+        print(f'❌ Build failed: {e}')
+        if e.stdout:
+            print('STDOUT:', e.stdout)
+        if e.stderr:
+            print('STDERR:', e.stderr)
+        return False
+
+
+# =================================================
+# SECTION: Test and profile binary
+# =================================================
+
+WELCOME_MARKERS = ["welcome", "openhands cli", "type /help", "available commands", ">"]
+
+def _is_welcome(line: str) -> bool:
+    s = line.strip().lower()
+    return any(marker in s for marker in WELCOME_MARKERS)
+
+def test_executable() -> bool:
+    """Test the built executable, measuring boot time and total test time."""
+    print('🧪 Testing the built executable...')
+
+    spec_path = os.path.join(PERSISTENCE_DIR, AGENT_SETTINGS_PATH)
+
+    specs_path = Path(os.path.expanduser(spec_path))
+    if specs_path.exists():
+        print(f"⚠️  Using existing settings at {specs_path}")
+    else:
+        print(f"💾 Creating dummy settings at {specs_path}")
+        specs_path.parent.mkdir(parents=True, exist_ok=True)
+        specs_path.write_text(dummy_agent.model_dump_json())
+
+    exe_path = Path('dist/openhands-cli')
+    if not exe_path.exists():
+        exe_path = Path('dist/openhands-cli.exe')
+        if not exe_path.exists():
+            print('❌ Executable not found!')
+            return False
+
+    try:
+        if os.name != 'nt':
+            os.chmod(exe_path, 0o755)
+
+        boot_start = time.time()
+        proc = subprocess.Popen(
+            [str(exe_path)],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+            env={**os.environ},
+        )
+
+        # --- Wait for welcome ---
+        deadline = boot_start + 30
+        saw_welcome = False
+        captured = []
+
+        while time.time() < deadline:
+            if proc.poll() is not None:
+                break
+            rlist, _, _ = select.select([proc.stdout], [], [], 0.2)
+            if not rlist:
+                continue
+            line = proc.stdout.readline()
+            if not line:
+                continue
+            captured.append(line)
+            if _is_welcome(line):
+                saw_welcome = True
+                break
+
+        if not saw_welcome:
+            print("❌ Did not detect welcome prompt")
+            try: proc.kill()
+            except Exception: pass
+            return False
+
+        boot_end = time.time()
+        print(f"⏱️  Boot to welcome: {boot_end - boot_start:.2f} seconds")
+
+        # --- Run /help then /exit ---
+        if proc.stdin is None:
+            print("❌ stdin unavailable")
+            proc.kill()
+            return False
+
+        proc.stdin.write("/help\n/exit\n")
+        proc.stdin.flush()
+        out, _ = proc.communicate(timeout=30)
+
+        total_end = time.time()
+        full_output = ''.join(captured) + (out or '')
+
+        print(f"⏱️  End-to-end test time: {total_end - boot_start:.2f} seconds")
+
+        if "available commands" in full_output.lower():
+            print("✅ Executable starts, welcome detected, and /help works")
+            return True
+        else:
+            print("❌ /help output not found")
+            print("Output preview:", full_output[-500:])
+            return False
+
+    except subprocess.TimeoutExpired:
+        print("❌ Executable test timed out")
+        try: proc.kill()
+        except Exception: pass
+        return False
+    except Exception as e:
+        print(f"❌ Error testing executable: {e}")
+        try: proc.kill()
+        except Exception: pass
+        return False
+
+
+
+# =================================================
+# SECTION: Main
+# =================================================
+
+
+def main() -> int:
+    """Main function."""
+    parser = argparse.ArgumentParser(description='Build OpenHands CLI executable')
+    parser.add_argument(
+        '--spec', default='openhands-cli.spec', help='PyInstaller spec file to use'
+    )
+    parser.add_argument(
+        '--no-clean', action='store_true', help='Skip cleaning build directories'
+    )
+    parser.add_argument(
+        '--no-test', action='store_true', help='Skip testing the built executable'
+    )
+    parser.add_argument(
+        '--install-pyinstaller',
+        action='store_true',
+        help='Install PyInstaller using uv before building',
+    )
+
+    parser.add_argument(
+        '--no-build', action='store_true', help='Skip testing the built executable'
+    )
+
+    args = parser.parse_args()
+
+    print('🚀 OpenHands CLI Build Script')
+    print('=' * 40)
+
+    # Check if spec file exists
+    if not os.path.exists(args.spec):
+        print(f"❌ Spec file '{args.spec}' not found!")
+        return 1
+
+    # Build the executable
+    if not args.no_build and not build_executable(
+        args.spec, clean=not args.no_clean
+    ):
+        return 1
+
+    # Test the executable
+    if not args.no_test:
+        if not test_executable():
+            print('❌ Executable test failed, build process failed')
+            return 1
+
+    print('\n🎉 Build process completed!')
+    print("📁 Check the 'dist/' directory for your executable")
+
+    return 0
+
+
+
+
+if __name__ == '__main__':
+    sys.exit(main())

openhands-cli/build.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+#
+# Shell script wrapper for building OpenHands CLI executable.
+#
+# This script provides a simple interface to build the OpenHands CLI
+# using PyInstaller with uv package management.
+#
+
+set -e  # Exit on any error
+
+echo "🚀 OpenHands CLI Build Script"
+echo "=============================="
+
+# Check if uv is available
+if ! command -v uv &> /dev/null; then
+    echo "❌ uv is required but not found! Please install uv first."
+    exit 1
+fi
+
+# Parse arguments to check for --install-pyinstaller
+INSTALL_PYINSTALLER=false
+PYTHON_ARGS=()
+
+for arg in "$@"; do
+    case $arg in
+        --install-pyinstaller)
+            INSTALL_PYINSTALLER=true
+            PYTHON_ARGS+=("$arg")
+            ;;
+        *)
+            PYTHON_ARGS+=("$arg")
+            ;;
+    esac
+done
+
+# Install PyInstaller if requested
+if [ "$INSTALL_PYINSTALLER" = true ]; then
+    echo "📦 Installing PyInstaller with uv..."
+    if uv add --dev pyinstaller; then
+        echo "✅ PyInstaller installed successfully with uv!"
+    else
+        echo "❌ Failed to install PyInstaller"
+        exit 1
+    fi
+fi
+
+# Run the Python build script using uv
+uv run python build.py "${PYTHON_ARGS[@]}"

openhands-cli/hooks/rthook_profile_imports.py

@@ -0,0 +1,63 @@
+import atexit, os, sys, time
+from collections import defaultdict
+
+ENABLE = os.getenv("IMPORT_PROFILING", "0") not in ("", "0", "false", "False")
+OUT = "dist/import_profiler.csv"
+THRESHOLD_MS = float(os.getenv("IMPORT_PROFILING_THRESHOLD_MS", "0"))
+
+if ENABLE:
+    timings = defaultdict(float)   # module -> total seconds (first load only)
+    counts = defaultdict(int)      # module -> number of first-loads (should be 1)
+    max_dur = defaultdict(float)   # module -> max single load seconds
+
+    try:
+        import importlib._bootstrap as _bootstrap  # type: ignore[attr-defined]
+    except Exception:
+        _bootstrap = None
+
+    start_time = time.perf_counter()
+
+    if _bootstrap is not None:
+        _orig_find_and_load = _bootstrap._find_and_load
+
+        def _timed_find_and_load(name, import_):
+            preloaded = name in sys.modules  # cache hit?
+            t0 = time.perf_counter()
+            try:
+                return _orig_find_and_load(name, import_)
+            finally:
+                if not preloaded:
+                    dt = time.perf_counter() - t0
+                    timings[name] += dt
+                    counts[name] += 1
+                    if dt > max_dur[name]:
+                        max_dur[name] = dt
+
+        _bootstrap._find_and_load = _timed_find_and_load
+
+    @atexit.register
+    def _dump_import_profile():
+        def ms(s): return f"{s*1000:.3f}"
+        items = [
+            (name, counts[name], timings[name], max_dur[name])
+            for name in timings
+            if timings[name]*1000 >= THRESHOLD_MS
+        ]
+        items.sort(key=lambda x: x[2], reverse=True)
+        try:
+            with open(OUT, "w", encoding="utf-8") as f:
+                f.write("module,count,total_ms,max_ms\n")
+                for name, cnt, tot_s, max_s in items:
+                    f.write(f"{name},{cnt},{ms(tot_s)},{ms(max_s)}\n")
+            # brief summary
+            if items:
+                w = max(len(n) for n, *_ in items[:25])
+                sys.stderr.write("\n=== Import Time Profile (first-load only) ===\n")
+                sys.stderr.write(f"{'module'.ljust(w)}  count  total_ms   max_ms\n")
+                for name, cnt, tot_s, max_s in items[:25]:
+                    sys.stderr.write(
+                        f"{name.ljust(w)}  {str(cnt).rjust(5)}  {ms(tot_s).rjust(8)}  {ms(max_s).rjust(7)}\n"
+                    )
+            sys.stderr.write(f"\nImport profile written to: {OUT}\n")
+        except Exception as e:
+            sys.stderr.write(f"[import-profiler] failed to write profile: {e}\n")

openhands-cli/openhands-cli.spec

@@ -0,0 +1,110 @@
+# -*- mode: python ; coding: utf-8 -*-
+"""
+PyInstaller spec file for OpenHands CLI.
+
+This spec file configures PyInstaller to create a standalone executable
+for the OpenHands CLI application.
+"""
+
+from pathlib import Path
+import os
+import sys
+from PyInstaller.utils.hooks import (
+    collect_submodules,
+    collect_data_files,
+    copy_metadata
+)
+
+
+
+# Get the project root directory (current working directory when running PyInstaller)
+project_root = Path.cwd()
+
+a = Analysis(
+    ['openhands_cli/simple_main.py'],
+    pathex=[str(project_root)],
+    binaries=[],
+    datas=[
+        # Include any data files that might be needed
+        # Add more data files here if needed in the future
+        *collect_data_files('tiktoken'),
+        *collect_data_files('tiktoken_ext'),
+        *collect_data_files('litellm'),
+        *collect_data_files('fastmcp'),
+        *collect_data_files('mcp'),
+        # Include Jinja prompt templates required by the agent SDK
+        *collect_data_files('openhands.sdk.agent', includes=['prompts/*.j2']),
+        # Include package metadata for importlib.metadata
+        *copy_metadata('fastmcp'),
+    ],
+    hiddenimports=[
+        # Explicitly include modules that might not be detected automatically
+        *collect_submodules('openhands_cli'),
+        *collect_submodules('prompt_toolkit'),
+        # Include OpenHands SDK submodules explicitly to avoid resolution issues
+        *collect_submodules('openhands.sdk'),
+        *collect_submodules('openhands.tools'),
+        *collect_submodules('tiktoken'),
+        *collect_submodules('tiktoken_ext'),
+        *collect_submodules('litellm'),
+        *collect_submodules('fastmcp'),
+        # Include mcp but exclude CLI parts that require typer
+        'mcp.types',
+        'mcp.client',
+        'mcp.server',
+        'mcp.shared',
+        'openhands.tools.execute_bash',
+        'openhands.tools.str_replace_editor',
+        'openhands.tools.task_tracker',
+    ],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    # runtime_hooks=[str(project_root / "hooks" / "rthook_profile_imports.py")],
+    excludes=[
+        # Exclude unnecessary modules to reduce binary size
+        'tkinter',
+        'matplotlib',
+        'numpy',
+        'scipy',
+        'pandas',
+        'IPython',
+        'jupyter',
+        'notebook',
+        # Exclude mcp CLI parts that cause issues
+        'mcp.cli',
+        'prompt_toolkit.contrib.ssh',
+        'fastmcp.cli',
+        'boto3',
+        'botocore',
+        'posthog',
+        'browser-use',
+        'openhands.tools.browser_use'
+    ],
+    noarchive=False,
+    # IMPORTANT: do not use optimize=2 (-OO) because it strips docstrings used by PLY/bashlex grammar
+    optimize=0,
+)
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    a.binaries,
+    a.datas,
+    [],
+    name='openhands-cli',
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=True,  # Strip debug symbols to reduce size
+    upx=True,    # Use UPX compression if available
+    upx_exclude=[],
+    runtime_tmpdir=None,
+    console=True,  # CLI application needs console
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+    icon=None,  # Add icon path here if you have one
+)

openhands-cli/openhands_cli/__init__.py

@@ -0,0 +1,3 @@
+"""OpenHands CLI package."""
+
+__version__ = "0.1.0"

openhands-cli/openhands_cli/agent_chat.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""
+Agent chat functionality for OpenHands CLI.
+Provides a conversation interface with an AI agent using OpenHands patterns.
+"""
+
+import logging
+import uuid
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from openhands.sdk import Message, TextContent
+    from openhands.sdk.conversation.state import AgentExecutionStatus
+    from prompt_toolkit import PromptSession, print_formatted_text
+    from prompt_toolkit.formatted_text import HTML
+    from openhands_cli.runner import ConversationRunner
+    from openhands_cli.setup import setup_agent
+    from openhands_cli.tui.settings.settings_screen import SettingsScreen
+    from openhands_cli.tui.tui import CommandCompleter, display_help, display_welcome
+    from openhands_cli.user_actions import UserConfirmation, exit_session_confirmation
+
+logger = logging.getLogger(__name__)
+
+
+def _fast_exit():
+    """Perform fast exit to avoid waiting for thread cleanup."""
+    import os
+    import threading
+    
+    # Give threads a brief moment to clean up
+    active_threads = [t for t in threading.enumerate() if t != threading.current_thread()]
+    if active_threads:
+        # Wait briefly for daemon threads to finish
+        import time
+        time.sleep(0.01)
+    
+    # Force exit to avoid waiting for any remaining cleanup
+    os._exit(0)
+
+
+def run_cli_entry() -> None:
+    """Run the agent chat session using the agent SDK.
+
+    Raises:
+        AgentSetupError: If agent setup fails
+        KeyboardInterrupt: If user interrupts the session
+        EOFError: If EOF is encountered
+    """
+    # Import heavy dependencies only when needed
+    from openhands_cli.setup import setup_agent
+    from openhands_cli.tui.settings.settings_screen import SettingsScreen
+    from openhands_cli.tui.tui import display_welcome, CommandCompleter
+    from openhands_cli.runner import ConversationRunner
+    from prompt_toolkit import PromptSession
+
+    conversation = setup_agent()
+    settings_screen = SettingsScreen()
+
+    while not conversation:
+        settings_screen.handle_basic_settings(escapable=False)
+        conversation = setup_agent()
+
+    # Generate session ID
+    session_id = str(uuid.uuid4())[:8]
+
+    display_welcome(session_id)
+
+    # Create prompt session with command completer
+    session = PromptSession(completer=CommandCompleter())
+
+    # Create conversation runner to handle state machine logic
+    runner = ConversationRunner(conversation)
+
+    # Main chat loop
+    while True:
+        try:
+            from prompt_toolkit.formatted_text import HTML
+            
+            # Get user input
+            user_input = session.prompt(
+                HTML("<gold>> </gold>"),
+                multiline=False,
+            )
+
+            if not user_input.strip():
+                continue
+
+            # Handle commands
+            command = user_input.strip().lower()
+
+            # Import SDK components only when needed
+            from openhands.sdk import Message, TextContent
+            
+            message = Message(
+                role="user",
+                content=[TextContent(text=user_input)],
+            )
+
+            if command == "/exit":
+                from openhands_cli.user_actions import UserConfirmation, exit_session_confirmation
+                from prompt_toolkit import print_formatted_text
+                
+                exit_confirmation = exit_session_confirmation()
+                if exit_confirmation == UserConfirmation.ACCEPT:
+                    print_formatted_text(HTML("\n<yellow>Goodbye! 👋</yellow>"))
+                    _fast_exit()
+                    break
+
+            elif command == "/settings":
+                settings_screen = SettingsScreen(conversation)
+                settings_screen.display_settings()
+                continue
+
+            elif command == "/clear":
+                display_welcome(session_id)
+                continue
+            elif command == "/help":
+                from openhands_cli.tui.tui import display_help
+                display_help()
+                continue
+            elif command == "/status":
+                from prompt_toolkit import print_formatted_text
+                
+                print_formatted_text(HTML(f"<grey>Session ID: {session_id}</grey>"))
+                print_formatted_text(HTML("<grey>Status: Active</grey>"))
+                confirmation_status = (
+                    "enabled" if conversation.state.confirmation_mode else "disabled"
+                )
+                print_formatted_text(
+                    HTML(f"<grey>Confirmation mode: {confirmation_status}</grey>")
+                )
+                continue
+            elif command == "/confirm":
+                from prompt_toolkit import print_formatted_text
+                
+                current_mode = runner.confirmation_mode
+                runner.set_confirmation_mode(not current_mode)
+                new_status = "enabled" if not current_mode else "disabled"
+                print_formatted_text(
+                    HTML(f"<yellow>Confirmation mode {new_status}</yellow>")
+                )
+                continue
+            elif command == "/new":
+                from prompt_toolkit import print_formatted_text
+                
+                print_formatted_text(
+                    HTML("<yellow>Starting new conversation...</yellow>")
+                )
+                session_id = str(uuid.uuid4())[:8]
+                display_welcome(session_id)
+                continue
+            elif command == "/resume":
+                from openhands.sdk.conversation.state import AgentExecutionStatus
+                from prompt_toolkit import print_formatted_text
+                
+                if not (
+                    conversation.state.agent_status == AgentExecutionStatus.PAUSED
+                    or conversation.state.agent_status
+                    == AgentExecutionStatus.WAITING_FOR_CONFIRMATION
+                ):
+                    print_formatted_text(
+                        HTML("<red>No paused conversation to resume...</red>")
+                    )
+
+                    continue
+
+                # Resume without new message
+                message = None
+
+            runner.process_message(message)
+
+            print()  # Add spacing
+
+        except KeyboardInterrupt:
+            from openhands_cli.user_actions import UserConfirmation, exit_session_confirmation
+            from prompt_toolkit import print_formatted_text
+            
+            exit_confirmation = exit_session_confirmation()
+            if exit_confirmation == UserConfirmation.ACCEPT:
+                print_formatted_text(HTML("\n<yellow>Goodbye! 👋</yellow>"))
+                _fast_exit()
+                break

openhands-cli/openhands_cli/listeners/__init__.py

@@ -0,0 +1,5 @@
+from openhands_cli.listeners.pause_listener import PauseListener
+
+__all__ = [
+    "PauseListener",
+]

openhands-cli/openhands_cli/listeners/pause_listener.py

@@ -0,0 +1,104 @@
+import threading
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from openhands.sdk import Conversation
+    from prompt_toolkit import HTML, print_formatted_text
+    from prompt_toolkit.input import Input
+    from prompt_toolkit.keys import Keys
+
+
+class PauseListener(threading.Thread):
+    """Background key listener that triggers pause on Ctrl-P.
+
+    Starts and stops around agent run() loops to avoid interfering with user prompts.
+    """
+
+    def __init__(
+        self,
+        on_pause: Callable,
+        input_source=None,  # used to pipe inputs for unit tests
+    ):
+        super().__init__(daemon=True)
+        self.on_pause = on_pause
+        self._stop_event = threading.Event()
+        self._pause_event = threading.Event()
+        
+        # Lazy import to avoid startup cost
+        if input_source is None:
+            from prompt_toolkit.input import create_input
+            self._input = create_input()
+        else:
+            self._input = input_source
+
+    def _detect_pause_key_presses(self) -> bool:
+        from prompt_toolkit.keys import Keys
+        
+        pause_detected = False
+
+        for key_press in self._input.read_keys():
+            pause_detected = pause_detected or key_press.key == Keys.ControlP
+            pause_detected = pause_detected or key_press.key == Keys.ControlC
+            pause_detected = pause_detected or key_press.key == Keys.ControlD
+
+        return pause_detected
+
+    def _execute_pause(self) -> None:
+        from prompt_toolkit import HTML, print_formatted_text
+        
+        self._pause_event.set()  # Mark pause event occurred
+        print_formatted_text(HTML(""))
+        print_formatted_text(
+            HTML("<gold>Pausing agent once step is completed...</gold>")
+        )
+        try:
+            self.on_pause()
+        except Exception:
+            pass
+
+    def run(self) -> None:
+        try:
+            with self._input.raw_mode():
+                # User hasn't paused and pause listener hasn't been shut down
+                while not (self.is_paused() or self.is_stopped()):
+                    if self._detect_pause_key_presses():
+                        self._execute_pause()
+        finally:
+            try:
+                self._input.close()
+            except Exception:
+                pass
+
+    def stop(self) -> None:
+        """Stop the listener and ensure quick shutdown."""
+        self._stop_event.set()
+        
+        # Force close input to break out of read_keys() loop quickly
+        try:
+            if hasattr(self._input, 'close'):
+                self._input.close()
+        except Exception:
+            pass
+
+    def is_stopped(self) -> bool:
+        return self._stop_event.is_set()
+
+    def is_paused(self) -> bool:
+        return self._pause_event.is_set()
+
+
+@contextmanager
+def pause_listener(
+    conversation, input_source=None
+) -> Iterator[PauseListener]:
+    """Ensure PauseListener always starts/stops cleanly."""
+    listener = PauseListener(on_pause=conversation.pause, input_source=input_source)
+    listener.start()
+    try:
+        yield listener
+    finally:
+        listener.stop()
+        # Give the thread a moment to shut down cleanly
+        listener.join(timeout=0.1)

openhands-cli/openhands_cli/locations.py

@@ -0,0 +1,9 @@
+import os
+
+# Configuration directory for storing agent settings and CLI configuration
+PERSISTENCE_DIR = os.path.expanduser("~/.openhands")
+
+# Working directory for agent operations (current directory where CLI is run)
+WORK_DIR = os.getcwd()
+
+AGENT_SETTINGS_PATH = "agent_settings.json"

openhands-cli/openhands_cli/pt_style.py

@@ -0,0 +1,29 @@
+from prompt_toolkit.styles import Style, merge_styles
+from prompt_toolkit.styles.base import BaseStyle
+from prompt_toolkit.styles.defaults import default_ui_style
+
+# Centralized helper for CLI styles so we can safely merge our custom colors
+# with prompt_toolkit's default UI style. This preserves completion menu and
+# fuzzy-match visibility across different terminal themes (e.g., Ubuntu).
+
+COLOR_GOLD = "#FFD700"
+COLOR_GREY = "#808080"
+COLOR_AGENT_BLUE = "#4682B4"  # Steel blue - readable on light/dark backgrounds
+
+
+def get_cli_style() -> BaseStyle:
+    base = default_ui_style()
+    custom = Style.from_dict(
+        {
+            "gold": COLOR_GOLD,
+            "grey": COLOR_GREY,
+            "prompt": f"{COLOR_GOLD} bold",
+            # Ensure good contrast for fuzzy matches on the selected completion row
+            # across terminals/themes (e.g., Ubuntu GNOME, Alacritty, Kitty).
+            # See https://github.com/All-Hands-AI/OpenHands/issues/10330
+            "completion-menu.completion.current fuzzymatch.outside": "fg:#ffffff bg:#888888",
+            "selected": COLOR_GOLD,
+            "risk-high": "#FF0000 bold",  # Red bold for HIGH risk
+        }
+    )
+    return merge_styles([base, custom])

openhands-cli/openhands_cli/runner.py

@@ -0,0 +1,149 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from openhands.sdk import Conversation, Message
+    from openhands.sdk.security.confirmation_policy import AlwaysConfirm, NeverConfirm
+    from openhands.sdk.conversation.state import AgentExecutionStatus
+    from openhands.sdk.event.utils import get_unmatched_actions
+    from prompt_toolkit import HTML, print_formatted_text
+    from openhands_cli.listeners.pause_listener import PauseListener, pause_listener
+    from openhands_cli.user_actions import ask_user_confirmation
+    from openhands_cli.user_actions.types import UserConfirmation
+
+
+class ConversationRunner:
+    """Handles the conversation state machine logic cleanly."""
+
+    def __init__(self, conversation):
+        self.conversation = conversation
+        self.confirmation_mode = False
+
+    def set_confirmation_mode(self, confirmation_mode: bool) -> None:
+        from openhands.sdk.security.confirmation_policy import AlwaysConfirm, NeverConfirm
+        
+        self.confirmation_mode = confirmation_mode
+
+        if confirmation_mode:
+            self.conversation.set_confirmation_policy(AlwaysConfirm())
+        else:
+            self.conversation.set_confirmation_policy(NeverConfirm())
+
+    def _start_listener(self) -> None:
+        from openhands_cli.listeners.pause_listener import PauseListener
+        
+        self.listener = PauseListener(on_pause=self.conversation.pause)
+        self.listener.start()
+
+    def _print_run_status(self) -> None:
+        from openhands.sdk.conversation.state import AgentExecutionStatus
+        from prompt_toolkit import HTML, print_formatted_text
+        
+        print_formatted_text("")
+        if self.conversation.state.agent_status == AgentExecutionStatus.PAUSED:
+            print_formatted_text(
+                HTML(
+                    "<yellow>Resuming paused conversation...</yellow><grey> (Press Ctrl-P to pause)</grey>"
+                )
+            )
+
+        else:
+            print_formatted_text(
+                HTML(
+                    "<yellow>Agent running...</yellow><grey> (Press Ctrl-P to pause)</grey>"
+                )
+            )
+        print_formatted_text("")
+
+    def process_message(self, message) -> None:
+        """Process a user message through the conversation.
+
+        Args:
+            message: The user message to process
+        """
+
+        self._print_run_status()
+
+        # Send message to conversation
+        if message:
+            self.conversation.send_message(message)
+
+        if self.confirmation_mode:
+            self._run_with_confirmation()
+        else:
+            self._run_without_confirmation()
+
+    def _run_without_confirmation(self) -> None:
+        from openhands_cli.listeners.pause_listener import pause_listener
+        
+        with pause_listener(self.conversation):
+            self.conversation.run()
+
+    def _run_with_confirmation(self) -> None:
+        from openhands.sdk.conversation.state import AgentExecutionStatus
+        from openhands_cli.listeners.pause_listener import pause_listener
+        from openhands_cli.user_actions.types import UserConfirmation
+        
+        # If agent was paused, resume with confirmation request
+        if (
+            self.conversation.state.agent_status
+            == AgentExecutionStatus.WAITING_FOR_CONFIRMATION
+        ):
+            user_confirmation = self._handle_confirmation_request()
+            if user_confirmation == UserConfirmation.DEFER:
+                return
+
+        while True:
+            with pause_listener(self.conversation) as listener:
+                self.conversation.run()
+
+                if listener.is_paused():
+                    break
+
+            # In confirmation mode, agent either finishes or waits for user confirmation
+            if self.conversation.state.agent_status == AgentExecutionStatus.FINISHED:
+                break
+
+            elif (
+                self.conversation.state.agent_status
+                == AgentExecutionStatus.WAITING_FOR_CONFIRMATION
+            ):
+                user_confirmation = self._handle_confirmation_request()
+                if user_confirmation == UserConfirmation.DEFER:
+                    return
+
+            else:
+                raise Exception("Infinite loop")
+
+    def _handle_confirmation_request(self):
+        """Handle confirmation request from user.
+
+        Returns:
+            UserConfirmation indicating the user's choice
+        """
+        from openhands.sdk.event.utils import get_unmatched_actions
+        from openhands_cli.user_actions import ask_user_confirmation
+        from openhands_cli.user_actions.types import UserConfirmation
+        from prompt_toolkit import HTML, print_formatted_text
+        
+        pending_actions = get_unmatched_actions(self.conversation.state.events)
+
+        if pending_actions:
+            user_confirmation, reason = ask_user_confirmation(pending_actions)
+            if user_confirmation == UserConfirmation.REJECT:
+                self.conversation.reject_pending_actions(
+                    reason or "User rejected the actions"
+                )
+            elif user_confirmation == UserConfirmation.DEFER:
+                self.conversation.pause()
+            elif user_confirmation == UserConfirmation.ALWAYS_ACCEPT:
+                # Disable confirmation mode when user selects "Always proceed"
+                print_formatted_text(
+                    HTML(
+                        "<yellow>Confirmation mode disabled. Agent will proceed without asking.</yellow>"
+                    )
+                )
+                self.set_confirmation_mode(False)
+
+            return user_confirmation
+
+        return UserConfirmation.ACCEPT

openhands-cli/openhands_cli/setup.py

@@ -0,0 +1,32 @@
+from openhands.sdk import (
+    Agent,
+    Conversation
+)
+from openhands_cli.tui.settings.store import AgentStore
+from prompt_toolkit import HTML, print_formatted_text
+from openhands.tools.execute_bash import BashTool
+from openhands.tools.str_replace_editor import FileEditorTool
+from openhands.tools.task_tracker import TaskTrackerTool
+from openhands.sdk import register_tool
+
+register_tool("BashTool", BashTool)
+register_tool("FileEditorTool", FileEditorTool)
+register_tool("TaskTrackerTool", TaskTrackerTool)
+
+def setup_agent() -> Conversation | None:
+    """
+    Setup the agent with environment variables.
+    """
+
+    agent_store = AgentStore()
+    agent = agent_store.load()
+    if not agent:
+        return None
+
+    # Create agent
+    conversation = Conversation(agent=agent)
+
+    print_formatted_text(
+        HTML(f"<green>✓ Agent initialized with model: {agent.llm.model}</green>")
+    )
+    return conversation

openhands-cli/openhands_cli/simple_main.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+Simple main entry point for OpenHands CLI.
+This is a simplified version that demonstrates the TUI functionality.
+"""
+
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from prompt_toolkit import print_formatted_text
+    from prompt_toolkit.formatted_text import HTML
+
+
+def main() -> None:
+    """Main entry point for the OpenHands CLI.
+
+    Raises:
+        ImportError: If agent chat dependencies are missing
+        Exception: On other error conditions
+    """
+    # Handle --help early to avoid heavy imports
+    if len(sys.argv) > 1 and sys.argv[1] in ('--help', '-h', 'help'):
+        from prompt_toolkit import print_formatted_text
+        from prompt_toolkit.formatted_text import HTML
+        
+        print_formatted_text(HTML("<b>OpenHands CLI</b>"))
+        print_formatted_text(HTML(""))
+        print_formatted_text(HTML("A command-line interface for OpenHands AI agent."))
+        print_formatted_text(HTML(""))
+        print_formatted_text(HTML("<b>Usage:</b>"))
+        print_formatted_text(HTML("  openhands-cli                 Start interactive chat"))
+        print_formatted_text(HTML("  openhands-cli --help          Show this help"))
+        print_formatted_text(HTML(""))
+        print_formatted_text(HTML("<b>Interactive Commands:</b>"))
+        print_formatted_text(HTML("  /help                         Show available commands"))
+        print_formatted_text(HTML("  /settings                     Open settings"))
+        print_formatted_text(HTML("  /exit                         Exit the application"))
+        print_formatted_text(HTML("  /clear                        Clear the screen"))
+        print_formatted_text(HTML("  /status                       Show session status"))
+        print_formatted_text(HTML("  /confirm                      Toggle confirmation mode"))
+        print_formatted_text(HTML("  /new                          Start new conversation"))
+        print_formatted_text(HTML("  /resume                       Resume paused conversation"))
+        print_formatted_text(HTML(""))
+        print_formatted_text(HTML("<b>Keyboard Shortcuts:</b>"))
+        print_formatted_text(HTML("  Ctrl+C                        Exit (with confirmation)"))
+        print_formatted_text(HTML("  Ctrl+P                        Pause agent execution"))
+        return
+
+    try:
+        # Import agent chat only when actually needed
+        from openhands_cli.agent_chat import run_cli_entry
+        
+        # Start agent chat directly by default
+        run_cli_entry()
+
+    except ImportError as e:
+        from prompt_toolkit import print_formatted_text
+        from prompt_toolkit.formatted_text import HTML
+        
+        print_formatted_text(
+            HTML(f"<red>Error: Agent chat requires additional dependencies: {e}</red>")
+        )
+        print_formatted_text(
+            HTML("<yellow>Please ensure the agent SDK is properly installed.</yellow>")
+        )
+        raise
+    except KeyboardInterrupt:
+        from prompt_toolkit import print_formatted_text
+        from prompt_toolkit.formatted_text import HTML
+        
+        print_formatted_text(HTML("\n<yellow>Goodbye! 👋</yellow>"))
+        _fast_exit()
+    except EOFError:
+        from prompt_toolkit import print_formatted_text
+        from prompt_toolkit.formatted_text import HTML
+        
+        print_formatted_text(HTML("\n<yellow>Goodbye! 👋</yellow>"))
+        _fast_exit()
+    except Exception as e:
+        from prompt_toolkit import print_formatted_text
+        from prompt_toolkit.formatted_text import HTML
+        
+        print_formatted_text(HTML(f"<red>Error starting agent chat: {e}</red>"))
+        import traceback
+        traceback.print_exc()
+        raise
+
+
+def _fast_exit():
+    """Perform fast exit to avoid waiting for thread cleanup."""
+    import os
+    import threading
+    
+    # Give threads a brief moment to clean up
+    active_threads = [t for t in threading.enumerate() if t != threading.current_thread()]
+    if active_threads:
+        # Wait briefly for daemon threads to finish
+        import time
+        time.sleep(0.01)
+    
+    # Force exit to avoid waiting for any remaining cleanup
+    os._exit(0)
+
+
+if __name__ == "__main__":
+    main()

openhands-cli/openhands_cli/tui/__init__.py

@@ -0,0 +1,5 @@
+from openhands_cli.tui.tui import DEFAULT_STYLE
+
+__all__ = [
+    "DEFAULT_STYLE",
+]

openhands-cli/openhands_cli/tui/settings/settings_screen.py

@@ -0,0 +1,205 @@
+import os
+from openhands_cli.locations import AGENT_SETTINGS_PATH, PERSISTENCE_DIR, WORK_DIR
+from openhands_cli.tui.settings.store import AgentStore
+from openhands_cli.user_actions.settings_action import (
+    SettingsType,
+    choose_llm_model,
+    choose_llm_provider,
+    prompt_api_key,
+    save_settings_confirmation,
+    settings_type_confirmation,
+    prompt_custom_model,
+    prompt_base_url,
+    choose_memory_condensation,
+)
+from openhands_cli.tui.utils import StepCounter
+from prompt_toolkit import HTML, print_formatted_text
+from openhands.sdk import Conversation, LLM, LocalFileStore
+from openhands.sdk.preset.default import get_default_agent
+from prompt_toolkit.shortcuts import print_container
+from prompt_toolkit.widgets import Frame, TextArea
+
+from openhands_cli.pt_style import COLOR_GREY
+
+class SettingsScreen:
+    def __init__(self, conversation: Conversation | None = None):
+        self.file_store = LocalFileStore(PERSISTENCE_DIR)
+        self.agent_store = AgentStore()
+        self.conversation = conversation
+
+    def display_settings(self) -> None:
+        agent_spec = self.agent_store.load()
+        if not agent_spec:
+            return
+
+        llm = agent_spec.llm
+        advanced_llm_settings = True if llm.base_url else False
+
+        # Prepare labels and values based on settings
+        labels_and_values = []
+        if not advanced_llm_settings:
+            # Attempt to determine provider, fallback if not directly available
+            provider = llm.model.split('/')[0] if '/' in llm.model else 'Unknown'
+
+            labels_and_values.extend(
+                [
+                    ("   LLM Provider", str(provider)),
+                    ("   LLM Model", str(llm.model)),
+                ]
+            )
+        else:
+            labels_and_values.extend(
+                [
+                    ("   Custom Model", llm.model),
+                    ("   Base URL", llm.base_url),
+
+                ]
+            )
+        labels_and_values.extend([
+            ("   API Key", "********" if llm.api_key else "Not Set"),
+            ("   Confirmation Mode", "Enabled" if self.conversation.state.confirmation_policy else "Disabled"),
+            ("   Memory Condensation", "Enabled" if agent_spec.condenser else "Disabled"),
+            ("   Configuration File", os.path.join(PERSISTENCE_DIR, AGENT_SETTINGS_PATH))
+        ])
+
+        # Calculate max widths for alignment
+        # Ensure values are strings for len() calculation
+        str_labels_and_values = [
+            (label, str(value)) for label, value in labels_and_values
+        ]
+        max_label_width = (
+            max(len(label) for label, _ in str_labels_and_values)
+            if str_labels_and_values
+            else 0
+        )
+
+        # Construct the summary text with aligned columns
+        settings_lines = [
+            f"{label + ':':<{max_label_width + 1}} {value:<}"  # Changed value alignment to left (<)
+            for label, value in str_labels_and_values
+        ]
+        settings_text = "\n".join(settings_lines)
+
+        container = Frame(
+            TextArea(
+                text=settings_text,
+                read_only=True,
+                style=COLOR_GREY,
+                wrap_lines=True,
+            ),
+            title="Settings",
+            style=f"fg:{COLOR_GREY}",
+        )
+
+        print_container(container)
+
+        self.configure_settings()
+
+    def configure_settings(self):
+        try:
+            settings_type = settings_type_confirmation()
+        except KeyboardInterrupt:
+            return
+
+        if settings_type == SettingsType.BASIC:
+            self.handle_basic_settings()
+        elif settings_type == SettingsType.ADVANCED:
+            self.handle_advanced_settings()
+
+    def handle_basic_settings(self, escapable=True):
+        step_counter = StepCounter(3)
+        try:
+            provider = choose_llm_provider(step_counter, escapable=escapable)
+            llm_model = choose_llm_model(step_counter, provider, escapable=escapable)
+            api_key = prompt_api_key(
+                step_counter,
+                provider,
+                self.conversation.agent.llm.api_key if self.conversation else None,
+                escapable=escapable
+            )
+            save_settings_confirmation()
+        except KeyboardInterrupt:
+            print_formatted_text(HTML('\n<red>Cancelled settings change.</red>'))
+            return
+
+        # Store the collected settings for persistence
+        self._save_llm_settings(f"{provider}/{llm_model}", api_key)
+
+    def handle_advanced_settings(self, escapable=True):
+        """Handle advanced settings configuration with clean step-by-step flow."""
+        step_counter = StepCounter(4)
+        try:
+            custom_model = prompt_custom_model(step_counter)
+            base_url = prompt_base_url(step_counter)
+            api_key = prompt_api_key(
+                step_counter,
+                custom_model.split('/')[0] if len(custom_model.split('/')) > 1 else '',
+                self.conversation.agent.llm.api_key if self.conversation else None,
+                escapable=escapable
+            )
+            memory_condensation = choose_memory_condensation(step_counter)
+
+            # Confirm save
+            save_settings_confirmation()
+        except KeyboardInterrupt:
+            print_formatted_text(HTML('\n<red>Cancelled settings change.</red>'))
+            return
+
+        # Store the collected settings for persistence
+        self._save_advanced_settings(
+            custom_model,
+            base_url,
+            api_key,
+            memory_condensation
+        )
+
+    def _save_llm_settings(
+        self,
+        model,
+        api_key,
+        base_url: str | None = None
+    ) -> None:
+        llm = LLM(
+            model=model,
+            api_key=api_key,
+            base_url=base_url
+        )
+
+        agent = self.agent_store.load()
+        if not agent:
+            agent = get_default_agent(
+                llm=llm,
+                working_dir=WORK_DIR,
+                cli_mode=True
+            )
+
+        agent = agent.model_copy(update={"llm": llm})
+        self.agent_store.save(agent)
+
+
+    def _save_advanced_settings(
+        self,
+        custom_model: str,
+        base_url: str,
+        api_key: str,
+        memory_condensation: bool
+    ):
+        self._save_llm_settings(
+            custom_model,
+            api_key,
+            base_url=base_url
+        )
+
+        agent_spec = self.agent_store.load()
+        if not agent_spec:
+            return
+
+
+        if not memory_condensation:
+            agent_spec.model_copy(update={"condenser": None})
+
+        self.agent_store.save(agent_spec)
+
+
+
+

openhands-cli/openhands_cli/tui/settings/store.py

@@ -0,0 +1,38 @@
+# openhands_cli/settings/store.py
+from __future__ import annotations
+import os
+from openhands.sdk import LocalFileStore, Agent
+from openhands.sdk.preset.default import get_default_tools
+from openhands_cli.locations import AGENT_SETTINGS_PATH, PERSISTENCE_DIR, WORK_DIR
+from prompt_toolkit import HTML, print_formatted_text
+
+
+class AgentStore:
+    """Single source of truth for persisting/retrieving AgentSpec."""
+    def __init__(self) -> None:
+        self.file_store = LocalFileStore(root=PERSISTENCE_DIR)
+
+    def load(self) -> Agent | None:
+        try:
+            str_spec = self.file_store.read(AGENT_SETTINGS_PATH)
+            agent = Agent.model_validate_json(str_spec)
+
+            # Update tools with most recent working directory
+            updated_tools = get_default_tools(
+                working_dir=WORK_DIR,
+                persistence_dir=PERSISTENCE_DIR,
+                enable_browser=False
+            )
+            agent = agent.model_copy(update={"tools": updated_tools})
+
+            return agent
+        except FileNotFoundError:
+            return None
+        except Exception:
+            print_formatted_text(HTML("\n<red>Agent configuration file is corrupted!</red>"))
+            return None
+
+    def save(self, agent: Agent) -> None:
+        serialized_spec = agent.model_dump_json(context={"expose_secrets": True})
+        self.file_store.write(AGENT_SETTINGS_PATH, serialized_spec)
+

openhands-cli/openhands_cli/tui/tui.py

@@ -0,0 +1,93 @@
+from collections.abc import Generator
+
+from prompt_toolkit import print_formatted_text
+from prompt_toolkit.completion import CompleteEvent, Completer, Completion
+from prompt_toolkit.document import Document
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.shortcuts import clear
+
+from openhands_cli import __version__
+from openhands_cli.pt_style import get_cli_style
+
+DEFAULT_STYLE = get_cli_style()
+
+# Available commands with descriptions
+COMMANDS = {
+    "/exit": "Exit the application",
+    "/help": "Display available commands",
+    "/clear": "Clear the screen",
+    "/status": "Display conversation details",
+    "/confirm": "Toggle confirmation mode on/off",
+    "/new": "Create a new conversation",
+    "/resume": "Resume a paused conversation",
+    "/settings": "Display and modify current settings",
+}
+
+
+class CommandCompleter(Completer):
+    """Custom completer for commands with interactive dropdown."""
+
+    def get_completions(
+        self, document: Document, complete_event: CompleteEvent
+    ) -> Generator[Completion, None, None]:
+        text = document.text_before_cursor.lstrip()
+        if text.startswith("/"):
+            for command, description in COMMANDS.items():
+                if command.startswith(text):
+                    yield Completion(
+                        command,
+                        start_position=-len(text),
+                        display_meta=description,
+                        style="bg:ansidarkgray fg:gold",
+                    )
+
+
+def display_banner(session_id: str) -> None:
+    print_formatted_text(
+        HTML(r"""<gold>
+     ___                    _   _                 _
+    /  _ \ _ __   ___ _ __ | | | | __ _ _ __   __| |___
+    | | | | '_ \ / _ \ '_ \| |_| |/ _` | '_ \ / _` / __|
+    | |_| | |_) |  __/ | | |  _  | (_| | | | | (_| \__ \
+    \___ /| .__/ \___|_| |_|_| |_|\__,_|_| |_|\__,_|___/
+          |_|
+    </gold>"""),
+        style=DEFAULT_STYLE,
+    )
+
+    print_formatted_text(HTML(f"<grey>OpenHands CLI v{__version__}</grey>"))
+
+    print_formatted_text("")
+    print_formatted_text(HTML(f"<grey>Initialized conversation {session_id}</grey>"))
+    print_formatted_text("")
+
+
+def display_help() -> None:
+    """Display help information about available commands."""
+    print_formatted_text("")
+    print_formatted_text(HTML("<gold>🤖 OpenHands CLI Help</gold>"))
+    print_formatted_text(HTML("<grey>Available commands:</grey>"))
+    print_formatted_text("")
+
+    for command, description in COMMANDS.items():
+        print_formatted_text(HTML(f"  <white>{command}</white> - {description}"))
+
+    print_formatted_text("")
+    print_formatted_text(HTML("<grey>Tips:</grey>"))
+    print_formatted_text("  • Type / and press Tab to see command suggestions")
+    print_formatted_text("  • Use arrow keys to navigate through suggestions")
+    print_formatted_text("  • Press Enter to select a command")
+    print_formatted_text("")
+
+
+def display_welcome(session_id: str = "chat") -> None:
+    """Display welcome message."""
+    clear()
+    display_banner(session_id)
+    print_formatted_text(HTML("<gold>Let's start building!</gold>"))
+    print_formatted_text(
+        HTML(
+            "<green>What do you want to build? <grey>Type /help for help</grey></green>"
+        )
+    )
+    print()

openhands-cli/openhands_cli/tui/utils.py

@@ -0,0 +1,14 @@
+class StepCounter:
+    """Automatically manages step numbering for settings flows."""
+
+    def __init__(self, total_steps: int):
+        self.current_step = 0
+        self.total_steps = total_steps
+
+    def next_step(self, prompt: str) -> str:
+        """Get the next step prompt with automatic numbering."""
+        self.current_step += 1
+        return f"(Step {self.current_step}/{self.total_steps}) {prompt}"
+
+    def existing_step(self, prompt: str) -> str:
+        return f"(Step {self.current_step}/{self.total_steps}) {prompt}"

openhands-cli/openhands_cli/user_actions/__init__.py

@@ -0,0 +1,17 @@
+from openhands_cli.user_actions.agent_action import ask_user_confirmation
+from openhands_cli.user_actions.exit_session import (
+    exit_session_confirmation,
+)
+from openhands_cli.user_actions.settings_action import (
+    choose_llm_provider,
+    settings_type_confirmation,
+)
+from openhands_cli.user_actions.types import UserConfirmation
+
+__all__ = [
+    'ask_user_confirmation',
+    'exit_session_confirmation',
+    'UserConfirmation',
+    'settings_type_confirmation',
+    'choose_llm_provider',
+]

openhands-cli/openhands_cli/user_actions/agent_action.py

@@ -0,0 +1,81 @@
+from prompt_toolkit import HTML, print_formatted_text
+
+from openhands_cli.user_actions.types import UserConfirmation
+from openhands_cli.user_actions.utils import cli_confirm, cli_text_input
+
+
+def ask_user_confirmation(pending_actions: list) -> tuple[UserConfirmation, str]:
+    """Ask user to confirm pending actions.
+
+    Args:
+        pending_actions: List of pending actions from the agent
+
+    Returns:
+        Tuple of (UserConfirmation, reason) where reason is provided when rejecting with reason
+    """
+
+    reason = ""
+
+    if not pending_actions:
+        return UserConfirmation.ACCEPT, reason
+
+    print_formatted_text(
+        HTML(
+            f"<yellow>🔍 Agent created {len(pending_actions)} action(s) and is waiting for confirmation:</yellow>"
+        )
+    )
+
+    for i, action in enumerate(pending_actions, 1):
+        tool_name = getattr(action, "tool_name", "[unknown tool]")
+        print("tool name", tool_name)
+        action_content = (
+            str(getattr(action, "action", ""))[:100].replace("\n", " ")
+            or "[unknown action]"
+        )
+        print("action_content", action_content)
+        print_formatted_text(
+            HTML(f"<grey>  {i}. {tool_name}: {action_content}...</grey>")
+        )
+
+    question = "Choose an option:"
+    options = [
+        "Yes, proceed",
+        "No, reject (w/o reason)",
+        "No, reject with reason",
+        "Always proceed (don't ask again)",
+    ]
+
+    try:
+        index = cli_confirm(question, options, escapable=True)
+    except (EOFError, KeyboardInterrupt):
+        print_formatted_text(HTML("\n<red>No input received; pausing agent.</red>"))
+        return UserConfirmation.DEFER, reason
+
+    if index == 0:
+        return UserConfirmation.ACCEPT, reason
+    elif index == 1:
+        return UserConfirmation.REJECT, reason
+    elif index == 2:
+        try:
+            reason_result = cli_text_input(
+                'Please enter your reason for rejecting these actions: '
+            )
+        except Exception:
+            return UserConfirmation.DEFER, ''
+
+        # Support both string return and (reason, cancelled) tuple for tests
+        cancelled = False
+        if isinstance(reason_result, tuple) and len(reason_result) >= 1:
+            reason = reason_result[0] or ''
+            cancelled = bool(reason_result[1]) if len(reason_result) > 1 else False
+        else:
+            reason = str(reason_result or '').strip()
+
+        if cancelled:
+            return UserConfirmation.DEFER, ''
+
+        return UserConfirmation.REJECT, reason
+    elif index == 3:
+        return UserConfirmation.ALWAYS_ACCEPT, reason
+
+    return UserConfirmation.REJECT, reason

openhands-cli/openhands_cli/user_actions/exit_session.py

@@ -0,0 +1,18 @@
+from openhands_cli.user_actions.types import UserConfirmation
+from openhands_cli.user_actions.utils import cli_confirm
+
+
+def exit_session_confirmation() -> UserConfirmation:
+    """
+    Ask user to confirm exiting session.
+    """
+
+    question = "Terminate session?"
+    options = ["Yes, proceed", "No, dismiss"]
+    index = cli_confirm(question, options)  # Blocking UI, not escapable
+
+    options_mapping = {
+        0: UserConfirmation.ACCEPT,  # User accepts termination session
+        1: UserConfirmation.REJECT,  # User does not terminate session
+    }
+    return options_mapping.get(index, UserConfirmation.REJECT)

openhands-cli/openhands_cli/user_actions/settings_action.py

@@ -0,0 +1,157 @@
+from enum import Enum
+
+from openhands_cli.tui.utils import StepCounter
+from prompt_toolkit.completion import FuzzyWordCompleter
+from pydantic import SecretStr
+
+
+from openhands.sdk.llm import (
+    VERIFIED_MODELS,
+    UNVERIFIED_MODELS_EXCLUDING_BEDROCK
+)
+
+from openhands_cli.user_actions.utils import cli_confirm, cli_text_input
+from prompt_toolkit.validation import Validator, ValidationError
+
+
+class NonEmptyValueValidator(Validator):
+    def validate(self, document):
+        text = document.text
+        if not text:
+            raise ValidationError(
+                message="API key cannot be empty. Please enter a valid API key."
+            )
+
+
+class SettingsType(Enum):
+    BASIC = 'basic'
+    ADVANCED = 'advanced'
+
+
+def settings_type_confirmation() -> SettingsType:
+    question = 'Which settings would you like to modify?'
+    choices = [
+        'LLM (Basic)',
+        'LLM (Advanced)',
+        'Go back',
+    ]
+
+    index = cli_confirm(question, choices)
+
+    if choices[index] == 'Go back':
+        raise KeyboardInterrupt
+
+    options_map = {
+        0: SettingsType.BASIC,
+        1: SettingsType.ADVANCED
+    }
+
+    return options_map.get(index)
+
+
+def choose_llm_provider(step_counter: StepCounter, escapable=True) -> str:
+    question = step_counter.next_step('Select LLM Provider (TAB for options, CTRL-c to cancel): ')
+    options = list(VERIFIED_MODELS.keys()).copy() + list(UNVERIFIED_MODELS_EXCLUDING_BEDROCK.keys()).copy()
+    alternate_option = 'Select another provider'
+
+    display_options = options[:4] + [alternate_option]
+
+    index = cli_confirm(question, display_options, escapable=escapable)
+    chosen_option = display_options[index]
+    if display_options[index] != alternate_option:
+        return chosen_option
+
+    question = step_counter.existing_step('Type LLM Provider (TAB to complete, CTRL-c to cancel): ')
+    return cli_text_input(
+        question, escapable=True, completer=FuzzyWordCompleter(options, WORD=True)
+    )
+
+
+def choose_llm_model(step_counter: StepCounter, provider: str, escapable=True) -> str:
+    """Choose LLM model using spec-driven approach. Return (model, deferred)."""
+
+    models = VERIFIED_MODELS.get(provider, []) + UNVERIFIED_MODELS_EXCLUDING_BEDROCK.get(provider, [])
+
+    if provider == 'openhands':
+        question = (
+            step_counter.next_step('Select Available OpenHands Model:\n')
+            + 'LLM usage is billed at the providers’ rates with no markup. Details: https://docs.all-hands.dev/usage/llms/openhands-llms'
+        )
+    else:
+        question = step_counter.next_step('Select LLM Model (TAB for options, CTRL-c to cancel): ')
+    alternate_option = 'Select another model'
+    display_options = models[:4] + [alternate_option]
+    index = cli_confirm(question, display_options, escapable=escapable)
+    chosen_option = display_options[index]
+
+    if chosen_option != alternate_option:
+        return chosen_option
+
+    question = step_counter.existing_step('Type model id (TAB to complete, CTRL-c to cancel): ')
+
+    return cli_text_input(
+        question, escapable=True, completer=FuzzyWordCompleter(models, WORD=True)
+    )
+
+
+
+def prompt_api_key(
+    step_counter: StepCounter,
+    provider: str,
+    existing_api_key: SecretStr | None = None,
+    escapable=True
+) -> str:
+    helper_text = (
+        "\nYou can find your OpenHands LLM API Key in the API Keys tab of OpenHands Cloud: "
+        "https://app.all-hands.dev/settings/api-keys\n"
+        if provider == "openhands"
+        else ""
+    )
+
+    if existing_api_key:
+        masked_key = existing_api_key.get_secret_value()[:3] + '***'
+        question = f'Enter API Key [{masked_key}] (CTRL-c to cancel, ENTER to keep current, type new to change): '
+        # For existing keys, allow empty input to keep current key
+        validator = None
+    else:
+        question = 'Enter API Key (CTRL-c to cancel): '
+        # For new keys, require non-empty input
+        validator = NonEmptyValueValidator()
+
+    question = helper_text + step_counter.next_step(question)
+    return cli_text_input(question, escapable=escapable, validator=validator, is_password=True)
+
+
+# Advanced settings functions
+def prompt_custom_model(step_counter: StepCounter, escapable=True) -> str:
+    """Prompt for custom model name."""
+    question = step_counter.next_step("Custom Model (CTRL-c to cancel): ")
+    return cli_text_input(question, escapable=escapable)
+
+
+def prompt_base_url(step_counter: StepCounter, escapable=True) -> str:
+    """Prompt for base URL."""
+    question = step_counter.next_step("Base URL (CTRL-c to cancel): ")
+    return cli_text_input(question, escapable=escapable, validator=NonEmptyValueValidator())
+
+
+def choose_memory_condensation(step_counter: StepCounter, escapable=True) -> bool:
+    """Choose memory condensation setting."""
+    question = step_counter.next_step("Memory Condensation (CTRL-c to cancel): ")
+    choices = ['Enable', 'Disable']
+
+    index = cli_confirm(question, choices, escapable=escapable)
+    return index == 0  # True for Enable, False for Disable
+
+
+def save_settings_confirmation() -> bool:
+    """Prompt user to confirm saving settings."""
+    question = 'Save new settings? (They will take effect after restart)'
+    discard = 'No, discard'
+    options = ['Yes, save', discard]
+
+    index = cli_confirm(question, options)
+    if options[index] == discard:
+        raise KeyboardInterrupt
+
+    return options[index]

openhands-cli/openhands_cli/user_actions/types.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+
+class UserConfirmation(Enum):
+    ACCEPT = "accept"
+    REJECT = "reject"
+    DEFER = "defer"
+    ALWAYS_ACCEPT = "always_accept"

openhands-cli/openhands_cli/user_actions/utils.py

@@ -0,0 +1,148 @@
+from prompt_toolkit.application import Application
+from prompt_toolkit.completion import Completer
+from prompt_toolkit.input.base import Input
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.key_binding.key_processor import KeyPressEvent
+from prompt_toolkit.layout.containers import HSplit, Window
+from prompt_toolkit.layout.controls import FormattedTextControl
+from prompt_toolkit.layout.dimension import Dimension
+from prompt_toolkit.layout.layout import Layout
+from prompt_toolkit.output.base import Output
+from prompt_toolkit.shortcuts import prompt
+from prompt_toolkit.validation import Validator
+
+from openhands_cli.tui import DEFAULT_STYLE
+
+
+def build_keybindings(
+    choices: list[str], selected: list[int], escapable: bool
+) -> KeyBindings:
+    """Create keybindings for the confirm UI. Split for testability."""
+    kb = KeyBindings()
+
+    @kb.add("up")
+    def _handle_up(event: KeyPressEvent) -> None:
+        selected[0] = (selected[0] - 1) % len(choices)
+
+    @kb.add("down")
+    def _handle_down(event: KeyPressEvent) -> None:
+        selected[0] = (selected[0] + 1) % len(choices)
+
+    @kb.add("enter")
+    def _handle_enter(event: KeyPressEvent) -> None:
+        event.app.exit(result=selected[0])
+
+    if escapable:
+
+        @kb.add("c-c")  # Ctrl+C
+        def _handle_hard_interrupt(event: KeyPressEvent) -> None:
+            event.app.exit(exception=KeyboardInterrupt())
+
+        @kb.add("c-p")  # Ctrl+P
+        def _handle_pause_interrupt(event: KeyPressEvent) -> None:
+            event.app.exit(exception=KeyboardInterrupt())
+
+        @kb.add("escape")  # Escape key
+        def _handle_escape(event: KeyPressEvent) -> None:
+            event.app.exit(exception=KeyboardInterrupt())
+
+    return kb
+
+
+def build_layout(question: str, choices: list[str], selected_ref: list[int]) -> Layout:
+    """Create the layout for the confirm UI. Split for testability."""
+
+    def get_choice_text() -> list[tuple[str, str]]:
+        lines: list[tuple[str, str]] = []
+        lines.append(("class:question", f"{question}\n\n"))
+        for i, choice in enumerate(choices):
+            is_selected = i == selected_ref[0]
+            prefix = "> " if is_selected else "  "
+            style = "class:selected" if is_selected else "class:unselected"
+            lines.append((style, f"{prefix}{choice}\n"))
+        return lines
+
+    content_window = Window(
+        FormattedTextControl(get_choice_text),
+        always_hide_cursor=True,
+        height=Dimension(max=8),
+    )
+    return Layout(HSplit([content_window]))
+
+
+def cli_confirm(
+    question: str = "Are you sure?",
+    choices: list[str] | None = None,
+    initial_selection: int = 0,
+    escapable: bool = False,
+    input: Input | None = None,  # strictly for unit testing
+    output: Output | None = None,  # strictly for unit testing
+) -> int:
+    """Display a confirmation prompt with the given question and choices.
+
+    Returns the index of the selected choice.
+    """
+    if choices is None:
+        choices = ["Yes", "No"]
+    selected = [initial_selection]  # Using list to allow modification in closure
+
+    kb = build_keybindings(choices, selected, escapable)
+    layout = build_layout(question, choices, selected)
+
+    app = Application(
+        layout=layout,
+        key_bindings=kb,
+        style=DEFAULT_STYLE,
+        full_screen=False,
+        input=input,
+        output=output,
+    )
+
+    return int(app.run(in_thread=True))
+
+
+def cli_text_input(
+    question: str,
+    escapable: bool = True,
+    completer: Completer | None = None,
+    validator: Validator = None,
+    is_password: bool = False
+) -> str:
+    """Prompt user to enter text input with optional validation.
+
+    Args:
+        question: The prompt question to display
+        escapable: Whether the user can escape with Ctrl+C or Ctrl+P
+        completer: Optional completer for tab completion
+        validator: Optional callable that takes a string and returns True if valid.
+                  If validation fails, the callable should display error messages
+                  and the user will be reprompted.
+
+    Returns:
+        The validated user input string (stripped of whitespace)
+    """
+
+    kb = KeyBindings()
+
+    if escapable:
+
+        @kb.add('c-c')
+        def _(event: KeyPressEvent) -> None:
+            raise KeyboardInterrupt()
+
+        @kb.add('c-p')
+        def _(event: KeyPressEvent) -> None:
+            raise KeyboardInterrupt()
+
+
+    reason = str(
+        prompt(
+            question,
+            style=DEFAULT_STYLE,
+            key_bindings=kb,
+            completer=completer,
+            is_password=is_password,
+            validator=validator
+        )
+    )
+    return reason.strip()

openhands-cli/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = [ "hatchling>=1.25" ]
+
+[project]
+name = "openhands-cli"
+version = "0.1.0"
+description = "OpenHands CLI - Terminal User Interface for OpenHands AI Agent"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [ { name = "OpenHands Team", email = "contact@all-hands.dev" } ]
+requires-python = ">=3.12"
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "openhands-sdk",
+  "openhands-tools",
+  "prompt-toolkit>=3",
+  "typer>=0.17.4",
+]
+
+# Dev-only tools with uv groups: `uv sync --group dev`
+scripts.openhands-cli = "openhands_cli.simple_main:main"
+
+[dependency-groups]
+# Hatchling wheel target: include the package directory
+dev = [
+  "black>=23",
+  "flake8>=6",
+  "isort>=5",
+  "mypy>=1",
+  "pre-commit>=4.3",
+  "pyinstaller>=6.15",
+  "pytest>=8.4.1",
+  "ruff>=0.11.8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = [ "openhands_cli" ]
+
+# uv source pins for internal packages
+
+[tool.black]
+line-length = 88
+target-version = [ "py312" ]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+format.indent-style = "space"
+format.quote-style = "double"
+format.line-ending = "auto"
+format.skip-magic-trailing-comma = false
+lint.select = [
+  "B",  # flake8-bugbear
+  "C4", # flake8-comprehensions
+  "E",  # pycodestyle errors
+  "F",  # pyflakes
+  "I",  # isort
+  "UP", # pyupgrade
+  "W",  # pycodestyle warnings
+]
+lint.ignore = [
+  "B008", # calls in argument defaults
+  "C901", # too complex
+  "E501", # line too long (black handles)
+]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+ignore_missing_imports = true
+
+[tool.uv.sources]
+openhands-sdk = { git = "https://github.com/All-Hands-AI/agent-sdk.git", subdirectory = "openhands/sdk", rev = "68fed9e285f9e5fd42f8aa2c6932acb7f86bc351" }
+openhands-tools = { git = "https://github.com/All-Hands-AI/agent-sdk.git", subdirectory = "openhands/tools", rev = "68fed9e285f9e5fd42f8aa2c6932acb7f86bc351" }

openhands-cli/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for OpenHands CLI."""

openhands-cli/tests/conftest.py

@@ -0,0 +1,44 @@
+import pytest
+from unittest.mock import patch
+
+# Fixture: mock_verified_models - Simplified model data
+@pytest.fixture
+def mock_verified_models():
+    with (
+        patch("openhands_cli.user_actions.settings_action.VERIFIED_MODELS", {
+            "openai": ["gpt-4o", "gpt-4o-mini"],
+            "anthropic": ["claude-3-5-sonnet", "claude-3-5-haiku"],
+        }),
+        patch("openhands_cli.user_actions.settings_action.UNVERIFIED_MODELS_EXCLUDING_BEDROCK", {
+            "openai": ["gpt-custom"],
+            "anthropic": [],
+            "custom": ["my-model"],
+        }),
+    ):
+        yield
+
+
+# Fixture: mock_cli_interactions - Reusable CLI mock patterns
+@pytest.fixture
+def mock_cli_interactions():
+    class Mocks:
+        def __init__(self):
+            self.p_confirm = patch("openhands_cli.user_actions.settings_action.cli_confirm")
+            self.p_text = patch("openhands_cli.user_actions.settings_action.cli_text_input")
+            self.cli_confirm = None
+            self.cli_text_input = None
+
+        def start(self):
+            self.cli_confirm = self.p_confirm.start()
+            self.cli_text_input = self.p_text.start()
+            return self
+
+        def stop(self):
+            self.p_confirm.stop()
+            self.p_text.stop()
+
+    mocks = Mocks().start()
+    try:
+        yield mocks
+    finally:
+        mocks.stop()

openhands-cli/tests/test_confirmation_mode.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""
+Tests for confirmation mode functionality in OpenHands CLI.
+"""
+
+import os
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+from openhands.sdk import ActionBase
+from openhands.sdk.security.confirmation_policy import AlwaysConfirm, NeverConfirm
+from prompt_toolkit.input.defaults import create_pipe_input
+from prompt_toolkit.output.defaults import DummyOutput
+
+from openhands_cli.runner import ConversationRunner
+from openhands_cli.setup import setup_agent
+from openhands_cli.user_actions import agent_action, ask_user_confirmation, utils
+from openhands_cli.user_actions.types import UserConfirmation
+from tests.utils import _send_keys
+
+
+class MockAction(ActionBase):
+    """Mock action schema for testing."""
+
+    command: str
+
+
+class TestConfirmationMode:
+    """Test suite for confirmation mode functionality."""
+
+    def test_setup_agent_creates_conversation(self) -> None:
+        """Test that setup_agent creates a conversation successfully."""
+        with patch.dict(os.environ, {'LLM_MODEL': 'test-model'}):
+            with (
+                patch('openhands_cli.setup.Agent') as mock_agent_class,
+                patch('openhands_cli.setup.Conversation') as mock_conversation_class,
+                patch('openhands_cli.setup.AgentStore') as mock_agent_store_class,
+                patch('openhands_cli.setup.print_formatted_text') as mock_print,
+                patch('openhands_cli.setup.HTML') as mock_html,
+            ):
+                # Mock AgentStore
+                mock_agent_store_instance = MagicMock()
+                mock_agent_instance = MagicMock()
+                mock_agent_instance.llm.model = 'test-model'
+                mock_agent_store_instance.load.return_value = mock_agent_instance
+                mock_agent_store_class.return_value = mock_agent_store_instance
+
+                # Mock Conversation constructor to return a mock conversation
+                mock_conversation_instance = MagicMock()
+                mock_conversation_class.return_value = mock_conversation_instance
+
+                result = setup_agent()
+
+                # Verify conversation was created and returned
+                assert result == mock_conversation_instance
+                mock_agent_store_class.assert_called_once()
+                mock_agent_store_instance.load.assert_called_once()
+                mock_conversation_class.assert_called_once_with(agent=mock_agent_instance)
+                # Verify print_formatted_text was called
+                mock_print.assert_called_once()
+
+    def test_conversation_runner_set_confirmation_mode(self) -> None:
+        """Test that ConversationRunner can set confirmation mode."""
+
+        mock_conversation = MagicMock()
+        runner = ConversationRunner(mock_conversation)
+
+        # Test enabling confirmation mode
+        runner.set_confirmation_mode(True)
+        assert runner.confirmation_mode is True
+        mock_conversation.set_confirmation_policy.assert_called_with(AlwaysConfirm())
+
+        # Test disabling confirmation mode
+        runner.set_confirmation_mode(False)
+        assert runner.confirmation_mode is False
+        mock_conversation.set_confirmation_policy.assert_called_with(NeverConfirm())
+
+    def test_conversation_runner_initial_state(self) -> None:
+        """Test that ConversationRunner starts with confirmation mode disabled."""
+
+        mock_conversation = MagicMock()
+        runner = ConversationRunner(mock_conversation)
+
+        # Verify initial state
+        assert runner.confirmation_mode is False
+
+    def test_ask_user_confirmation_empty_actions(self) -> None:
+        """Test that ask_user_confirmation returns ACCEPT for empty actions list."""
+        result, reason = ask_user_confirmation([])
+        assert result == UserConfirmation.ACCEPT
+        assert reason == ''
+
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_yes(self, mock_cli_confirm: Any) -> None:
+        """Test that ask_user_confirmation returns ACCEPT when user selects yes."""
+        mock_cli_confirm.return_value = 0  # First option (Yes, proceed)
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'ls -la'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.ACCEPT
+        assert reason == ''
+
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_no(self, mock_cli_confirm: Any) -> None:
+        """Test that ask_user_confirmation returns REJECT when user selects no."""
+        mock_cli_confirm.return_value = 1  # Second option (No, reject)
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'rm -rf /'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.REJECT
+        assert reason == ''
+
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_y_shorthand(self, mock_cli_confirm: Any) -> None:
+        """Test that ask_user_confirmation accepts first option as yes."""
+        mock_cli_confirm.return_value = 0  # First option (Yes, proceed)
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'echo hello'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.ACCEPT
+        assert reason == ''
+
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_n_shorthand(self, mock_cli_confirm: Any) -> None:
+        """Test that ask_user_confirmation accepts second option as no."""
+        mock_cli_confirm.return_value = 1  # Second option (No, reject)
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'dangerous command'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.REJECT
+        assert reason == ''
+
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_invalid_then_yes(
+        self, mock_cli_confirm: Any
+    ) -> None:
+        """Test that ask_user_confirmation handles selection and accepts yes."""
+        mock_cli_confirm.return_value = 0  # First option (Yes, proceed)
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'echo test'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.ACCEPT
+        assert reason == ''
+        assert mock_cli_confirm.call_count == 1
+
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_keyboard_interrupt(
+        self, mock_cli_confirm: Any
+    ) -> None:
+        """Test that ask_user_confirmation handles KeyboardInterrupt gracefully."""
+        mock_cli_confirm.side_effect = KeyboardInterrupt()
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'echo test'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.DEFER
+        assert reason == ''
+
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_eof_error(self, mock_cli_confirm: Any) -> None:
+        """Test that ask_user_confirmation handles EOFError gracefully."""
+        mock_cli_confirm.side_effect = EOFError()
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'echo test'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.DEFER
+        assert reason == ''
+
+    def test_ask_user_confirmation_multiple_actions(self) -> None:
+        """Test that ask_user_confirmation displays multiple actions correctly."""
+        with (
+            patch(
+                'openhands_cli.user_actions.agent_action.cli_confirm'
+            ) as mock_cli_confirm,
+            patch(
+                'openhands_cli.user_actions.agent_action.print_formatted_text'
+            ) as mock_print,
+        ):
+            mock_cli_confirm.return_value = 0  # First option (Yes, proceed)
+
+            mock_action1 = MagicMock()
+            mock_action1.tool_name = 'bash'
+            mock_action1.action = 'ls -la'
+
+            mock_action2 = MagicMock()
+            mock_action2.tool_name = 'str_replace_editor'
+            mock_action2.action = 'create file.txt'
+
+            result, reason = ask_user_confirmation([mock_action1, mock_action2])
+            assert result == UserConfirmation.ACCEPT
+            assert reason == ''
+
+            # Verify that both actions were displayed
+            assert mock_print.call_count >= 3  # Header + 2 actions
+
+    @patch('openhands_cli.user_actions.agent_action.cli_text_input')
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_no_with_reason(
+        self, mock_cli_confirm: Any, mock_cli_text_input: Any
+    ) -> None:
+        """Test that ask_user_confirmation returns REJECT when user selects 'No (with reason)'."""
+        mock_cli_confirm.return_value = 2  # Third option (No, with reason)
+        mock_cli_text_input.return_value = ('This action is too risky', False)
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'rm -rf /'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.REJECT
+        assert reason == 'This action is too risky'
+        mock_cli_text_input.assert_called_once()
+
+    @patch('openhands_cli.user_actions.agent_action.cli_text_input')
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_no_with_reason_cancelled(
+        self, mock_cli_confirm: Any, mock_cli_text_input: Any
+    ) -> None:
+        """Test that ask_user_confirmation falls back to DEFER when reason input is cancelled."""
+        mock_cli_confirm.return_value = 2  # Third option (No, with reason)
+        mock_cli_text_input.return_value = ('', True)  # User cancelled reason input
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'dangerous command'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.DEFER
+        assert reason == ''
+        mock_cli_text_input.assert_called_once()
+
+    def test_user_confirmation_is_escapable_e2e(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """E2E: non-escapable should ignore Ctrl-C/Ctrl-P/Esc; only Enter returns."""
+        real_cli_confirm = utils.cli_confirm
+
+        with create_pipe_input() as pipe:
+            output = DummyOutput()
+
+            def wrapper(
+                question: str,
+                choices: list[str] | None = None,
+                initial_selection: int = 0,
+                escapable: bool = False,
+                **extra: object,
+            ) -> int:
+                # keep original params; inject test IO
+                return real_cli_confirm(
+                    question=question,
+                    choices=choices,
+                    initial_selection=initial_selection,
+                    escapable=escapable,
+                    input=pipe,
+                    output=output,
+                )
+
+            # Patch the symbol the caller uses
+            monkeypatch.setattr(agent_action, 'cli_confirm', wrapper, raising=True)
+
+            with ThreadPoolExecutor(max_workers=1) as ex:
+                fut = ex.submit(
+                    ask_user_confirmation, [MockAction(command='echo hello world')]
+                )
+
+                _send_keys(pipe, '\x03')  # Ctrl-C (ignored)
+                result, reason = fut.result(timeout=2.0)
+                assert result == UserConfirmation.DEFER  # escaped confirmation view
+                assert reason == ''
+
+    @patch('openhands_cli.user_actions.agent_action.cli_confirm')
+    def test_ask_user_confirmation_always_accept(self, mock_cli_confirm: Any) -> None:
+        """Test that ask_user_confirmation returns ALWAYS_ACCEPT when user selects fourth option."""
+        mock_cli_confirm.return_value = 3  # Fourth option (Always proceed)
+
+        mock_action = MagicMock()
+        mock_action.tool_name = 'bash'
+        mock_action.action = 'echo test'
+
+        result, reason = ask_user_confirmation([mock_action])
+        assert result == UserConfirmation.ALWAYS_ACCEPT
+        assert reason == ''
+
+    def test_conversation_runner_handles_always_accept(self) -> None:
+        """Test that ConversationRunner disables confirmation mode when ALWAYS_ACCEPT is returned."""
+        mock_conversation = MagicMock()
+        runner = ConversationRunner(mock_conversation)
+
+        # Enable confirmation mode first
+        runner.set_confirmation_mode(True)
+        assert runner.confirmation_mode is True
+
+        # Mock get_unmatched_actions to return some actions
+        with patch('openhands_cli.runner.get_unmatched_actions') as mock_get_actions:
+            mock_action = MagicMock()
+            mock_action.tool_name = 'bash'
+            mock_action.action = 'echo test'
+            mock_get_actions.return_value = [mock_action]
+
+            # Mock ask_user_confirmation to return ALWAYS_ACCEPT
+            with patch('openhands_cli.runner.ask_user_confirmation') as mock_ask:
+                mock_ask.return_value = (UserConfirmation.ALWAYS_ACCEPT, '')
+
+                # Mock print_formatted_text to avoid output during test
+                with patch('openhands_cli.runner.print_formatted_text'):
+                    result = runner._handle_confirmation_request()
+
+                    # Verify that confirmation mode was disabled
+                    assert result == UserConfirmation.ALWAYS_ACCEPT
+                    assert runner.confirmation_mode is False
+                    mock_conversation.set_confirmation_policy.assert_called_with(NeverConfirm())

openhands-cli/tests/test_conversation_runner.py

@@ -0,0 +1,132 @@
+from typing import Any, Self
+from unittest.mock import patch
+
+import pytest
+from openhands.sdk import Conversation, ConversationCallbackType
+from openhands.sdk.agent.base import AgentBase
+from openhands.sdk.conversation import ConversationState
+from openhands.sdk.llm import LLM
+from pydantic import ConfigDict, SecretStr, model_validator
+from openhands.sdk.conversation.state import AgentExecutionStatus
+
+from openhands_cli.runner import ConversationRunner
+from openhands_cli.user_actions.types import UserConfirmation
+
+
+class FakeLLM(LLM):
+    @model_validator(mode="after")
+    def _set_env_side_effects(self) -> Self:
+        return self
+
+
+def default_config() -> dict[str, Any]:
+    return {
+        "model": "gpt-4o",
+        "api_key": SecretStr("test_key"),
+        "num_retries": 2,
+        "retry_min_wait": 1,
+        "retry_max_wait": 2,
+    }
+
+
+class FakeAgent(AgentBase):
+    model_config = ConfigDict(frozen=False)
+    step_count: int = 0
+    finish_on_step: int | None = None
+
+    def init_state(
+        self, state: ConversationState, on_event: ConversationCallbackType
+    ) -> None:
+        pass
+
+    def step(
+        self, state: ConversationState, on_event: ConversationCallbackType
+    ) -> None:
+        self.step_count += 1
+        if self.step_count == self.finish_on_step:
+            state.agent_status = AgentExecutionStatus.FINISHED
+
+
+@pytest.fixture()
+def agent() -> FakeAgent:
+    llm = LLM(**default_config(), service_id="test-service")
+    return FakeAgent(llm=llm, tools=[])
+
+
+class TestConversationRunner:
+    @pytest.mark.parametrize('agent_status', [AgentExecutionStatus.RUNNING, AgentExecutionStatus.PAUSED])
+    def test_non_confirmation_mode_runs_once(self, agent: FakeAgent, agent_status: AgentExecutionStatus) -> None:
+        """
+        1. Confirmation mode is not on
+        2. Process message resumes paused conversation or continues running conversation
+        """
+
+        convo = Conversation(agent)
+        convo.max_iteration_per_run = 1
+        convo.state.agent_status = agent_status
+        cr = ConversationRunner(convo)
+        cr.set_confirmation_mode(False)
+        cr.process_message(message=None)
+
+        assert agent.step_count == 1
+        assert convo.state.agent_status != AgentExecutionStatus.PAUSED
+
+    @pytest.mark.parametrize(
+        'confirmation, final_status, expected_run_calls',
+        [
+            # Case 1: Agent waiting for confirmation; user DEFERS -> early return, no run()
+            (UserConfirmation.DEFER, AgentExecutionStatus.WAITING_FOR_CONFIRMATION, 0),
+            # Case 2: Agent waiting for confirmation; user ACCEPTS -> run() once, break (finished=True)
+            (UserConfirmation.ACCEPT, AgentExecutionStatus.FINISHED, 1),
+        ],
+    )
+    def test_confirmation_mode_waiting_and_user_decision_controls_run(
+        self,
+        agent: FakeAgent,
+        confirmation: UserConfirmation,
+        final_status: AgentExecutionStatus,
+        expected_run_calls: int,
+    ) -> None:
+        """
+        1. Agent may be paused but is waiting for consent on actions
+        2. If paused, we should have asked for confirmation on action
+        3. If not paused, we should still ask for confirmation on actions
+        4. If deferred no run call to agent should be made
+        5. If accepted, run call to agent should be made
+
+        """
+        if final_status == AgentExecutionStatus.FINISHED:
+            agent.finish_on_step = 1
+        convo = Conversation(agent)
+        convo.state.agent_status = AgentExecutionStatus.WAITING_FOR_CONFIRMATION
+        cr = ConversationRunner(convo)
+        cr.set_confirmation_mode(True)
+        with patch.object(
+            cr, "_handle_confirmation_request", return_value=confirmation
+        ) as mock_confirmation_request:
+            cr.process_message(message=None)
+        mock_confirmation_request.assert_called_once()
+        assert agent.step_count == expected_run_calls
+        assert convo.state.agent_status == final_status
+
+    def test_confirmation_mode_not_waiting__runs_once_when_finished_true(
+        self, agent: FakeAgent
+    ) -> None:
+        """
+        1. Agent was not waiting
+        2. Agent finished without any actions
+        3. Conversation should finished without asking user for instructions
+        """
+        agent.finish_on_step = 1
+        convo = Conversation(agent)
+        convo.state.agent_status = AgentExecutionStatus.PAUSED
+
+        cr = ConversationRunner(convo)
+        cr.set_confirmation_mode(True)
+
+        with patch.object(cr, "_handle_confirmation_request") as _mock_h:
+            cr.process_message(message=None)
+
+        # No confirmation was needed up front; we still expect exactly one run.
+        assert agent.step_count == 1
+        _mock_h.assert_not_called()

openhands-cli/tests/test_directory_separation.py

@@ -0,0 +1,77 @@
+"""Tests to demonstrate the fix for WORK_DIR and PERSISTENCE_DIR separation."""
+
+import os
+from unittest.mock import patch, MagicMock
+from openhands.sdk import Agent, LLM, ToolSpec
+from openhands_cli.locations import WORK_DIR, PERSISTENCE_DIR
+from openhands_cli.tui.settings.store import AgentStore
+from openhands.sdk.preset.default import get_default_tools
+
+
+class TestDirectorySeparation:
+    """Test that WORK_DIR and PERSISTENCE_DIR are properly separated."""
+
+    def test_work_dir_and_persistence_dir_are_different(self):
+        """Test that WORK_DIR and PERSISTENCE_DIR are separate directories."""
+        # WORK_DIR should be the current working directory
+        assert WORK_DIR == os.getcwd()
+
+        # PERSISTENCE_DIR should be ~/.openhands
+        expected_config_dir = os.path.expanduser("~/.openhands")
+        assert PERSISTENCE_DIR == expected_config_dir
+
+        # They should be different
+        assert WORK_DIR != PERSISTENCE_DIR
+
+    def test_agent_store_uses_persistence_dir(self):
+        """Test that AgentStore uses PERSISTENCE_DIR for file storage."""
+        agent_store = AgentStore()
+        assert agent_store.file_store.root == PERSISTENCE_DIR
+
+
+class TestToolSpecFix:
+    """Test that tool specs are replaced with default tools using current directory."""
+
+    def test_tools_replaced_with_default_tools_on_load(self):
+        """Test that entire tools list is replaced with default tools when loading agent."""
+        # Create a mock agent with different tools and working directories
+        original_working_dir = "/some/other/path"
+        mock_agent = Agent(
+            llm=LLM(model="test/model", api_key="test-key"),
+            tools=[
+                ToolSpec(name="BashTool", params={"working_dir": original_working_dir}),
+                ToolSpec(name="FileEditorTool", params={"workspace_root": original_working_dir}),
+                ToolSpec(name="TaskTrackerTool", params={"save_dir": "value"}),
+            ]
+        )
+
+        # Mock the file store to return our test agent
+        with patch('openhands_cli.tui.settings.store.LocalFileStore') as mock_file_store:
+            mock_store_instance = MagicMock()
+            mock_file_store.return_value = mock_store_instance
+            mock_store_instance.read.return_value = mock_agent.model_dump_json()
+
+            agent_store = AgentStore()
+            loaded_agent = agent_store.load()
+
+            # Verify the agent was loaded
+            assert loaded_agent is not None
+
+            # Verify that tools are replaced with default tools
+            assert len(loaded_agent.tools) == 3  # BashTool, FileEditorTool, TaskTrackerTool
+
+            tool_names = [tool.name for tool in loaded_agent.tools]
+            assert "BashTool" in tool_names
+            assert "FileEditorTool" in tool_names
+            assert "TaskTrackerTool" in tool_names
+
+            for tool_spec in loaded_agent.tools:
+                if tool_spec.name == "BashTool":
+                    assert tool_spec.params["working_dir"] == WORK_DIR
+                    assert tool_spec.params["working_dir"] != original_working_dir
+                elif tool_spec.name == "FileEditorTool":
+                    assert tool_spec.params["workspace_root"] == WORK_DIR
+                    assert tool_spec.params["workspace_root"] != original_working_dir
+                elif tool_spec.name == "TaskTrackerTool":
+                    # TaskTrackerTool should use WORK_DIR/.openhands_tasks
+                    assert tool_spec.params["save_dir"] == PERSISTENCE_DIR

openhands-cli/tests/test_exit_session_confirmation.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+Tests for exit_session_confirmation functionality in OpenHands CLI.
+"""
+
+from collections.abc import Iterator
+from concurrent.futures import ThreadPoolExecutor
+from unittest.mock import MagicMock, patch
+
+import pytest
+from prompt_toolkit.input.defaults import create_pipe_input
+from prompt_toolkit.output.defaults import DummyOutput
+
+from openhands_cli.user_actions import (
+    exit_session,
+    exit_session_confirmation,
+    utils,
+)
+from openhands_cli.user_actions.types import UserConfirmation
+from tests.utils import _send_keys
+
+QUESTION = 'Terminate session?'
+OPTIONS = ['Yes, proceed', 'No, dismiss']
+
+
+@pytest.fixture()
+def confirm_patch() -> Iterator[MagicMock]:
+    """Patch cli_confirm once per test and yield the mock."""
+    with patch('openhands_cli.user_actions.exit_session.cli_confirm') as m:
+        yield m
+
+
+def _assert_called_once_with_defaults(mock_cli_confirm: MagicMock) -> None:
+    """Ensure the question/options are correct and 'escapable' is not enabled."""
+    mock_cli_confirm.assert_called_once()
+    args, kwargs = mock_cli_confirm.call_args
+    # Positional args
+    assert args == (QUESTION, OPTIONS)
+    # Should not opt into escapable mode
+    assert 'escapable' not in kwargs or kwargs['escapable'] is False
+
+
+class TestExitSessionConfirmation:
+    """Test suite for exit_session_confirmation functionality."""
+
+    @pytest.mark.parametrize(
+        'index,expected',
+        [
+            (0, UserConfirmation.ACCEPT),  # Yes
+            (1, UserConfirmation.REJECT),  # No
+            (999, UserConfirmation.REJECT),  # Invalid => default reject
+            (-1, UserConfirmation.REJECT),  # Negative => default reject
+        ],
+    )
+    def test_index_mapping(
+        self, confirm_patch: MagicMock, index: int, expected: UserConfirmation
+    ) -> None:
+        """All index-to-result mappings, including invalid/negative, in one place."""
+        confirm_patch.return_value = index
+
+        result = exit_session_confirmation()
+
+        assert isinstance(result, UserConfirmation)
+        assert result == expected
+        _assert_called_once_with_defaults(confirm_patch)
+
+    def test_exit_session_confirmation_non_escapable_e2e(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """E2E: non-escapable should ignore Ctrl-C/Ctrl-P/Esc; only Enter returns."""
+        real_cli_confirm = utils.cli_confirm
+
+        with create_pipe_input() as pipe:
+            output = DummyOutput()
+
+            def wrapper(
+                question: str,
+                choices: list[str] | None = None,
+                initial_selection: int = 0,
+                escapable: bool = False,
+                **extra: object,
+            ) -> int:
+                # keep original params; inject test IO
+                return real_cli_confirm(
+                    question=question,
+                    choices=choices,
+                    initial_selection=initial_selection,
+                    escapable=escapable,
+                    input=pipe,
+                    output=output,
+                )
+
+            # Patch the symbol the caller uses
+            monkeypatch.setattr(exit_session, 'cli_confirm', wrapper, raising=True)
+
+            with ThreadPoolExecutor(max_workers=1) as ex:
+                fut = ex.submit(exit_session_confirmation)
+
+                _send_keys(pipe, '\x03')  # Ctrl-C (ignored)
+                _send_keys(pipe, '\x10')  # Ctrl-P (ignored)
+                _send_keys(pipe, '\x1b')  # Esc   (ignored)
+
+                _send_keys(pipe, '\x1b[B')  # Arrow Down to "No, dismiss"
+                _send_keys(pipe, '\r')  # Enter
+
+                result = fut.result(timeout=2.0)
+                assert result == UserConfirmation.REJECT

openhands-cli/tests/test_main.py

@@ -0,0 +1,89 @@
+"""Tests for main entry point functionality."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from openhands_cli import simple_main
+
+
+class TestMainEntryPoint:
+    """Test the main entry point behavior."""
+
+    @patch('openhands_cli.agent_chat.setup_agent')
+    @patch('openhands_cli.agent_chat.ConversationRunner')
+    @patch('openhands_cli.agent_chat.PromptSession')
+    def test_main_starts_agent_chat_directly(
+        self, mock_prompt_session: MagicMock, mock_runner: MagicMock, mock_setup_agent: MagicMock
+    ) -> None:
+        """Test that main() starts agent chat directly when setup succeeds."""
+        # Mock setup_agent to return a valid conversation
+        mock_conversation = MagicMock()
+        mock_setup_agent.return_value = mock_conversation
+        
+        # Mock prompt session to raise KeyboardInterrupt to exit the loop
+        mock_prompt_session.return_value.prompt.side_effect = KeyboardInterrupt()
+
+        # Should complete without raising an exception (graceful exit)
+        simple_main.main()
+
+        # Should call setup_agent
+        mock_setup_agent.assert_called_once()
+
+    @patch('openhands_cli.simple_main.run_cli_entry')
+    def test_main_handles_import_error(self, mock_run_agent_chat: MagicMock) -> None:
+        """Test that main() handles ImportError gracefully."""
+        mock_run_agent_chat.side_effect = ImportError('Missing dependency')
+
+        # Should raise ImportError (re-raised after handling)
+        with pytest.raises(ImportError) as exc_info:
+            simple_main.main()
+
+        assert str(exc_info.value) == 'Missing dependency'
+
+    @patch('openhands_cli.agent_chat.setup_agent')
+    @patch('openhands_cli.agent_chat.ConversationRunner')
+    @patch('openhands_cli.agent_chat.PromptSession')
+    def test_main_handles_keyboard_interrupt(
+        self, mock_prompt_session: MagicMock, mock_runner: MagicMock, mock_setup_agent: MagicMock
+    ) -> None:
+        """Test that main() handles KeyboardInterrupt gracefully."""
+        # Mock setup_agent to return a valid conversation
+        mock_conversation = MagicMock()
+        mock_setup_agent.return_value = mock_conversation
+        
+        # Mock prompt session to raise KeyboardInterrupt
+        mock_prompt_session.return_value.prompt.side_effect = KeyboardInterrupt()
+
+        # Should complete without raising an exception (graceful exit)
+        simple_main.main()
+
+    @patch('openhands_cli.agent_chat.setup_agent')
+    @patch('openhands_cli.agent_chat.ConversationRunner')
+    @patch('openhands_cli.agent_chat.PromptSession')
+    def test_main_handles_eof_error(
+        self, mock_prompt_session: MagicMock, mock_runner: MagicMock, mock_setup_agent: MagicMock
+    ) -> None:
+        """Test that main() handles EOFError gracefully."""
+        # Mock setup_agent to return a valid conversation
+        mock_conversation = MagicMock()
+        mock_setup_agent.return_value = mock_conversation
+        
+        # Mock prompt session to raise EOFError
+        mock_prompt_session.return_value.prompt.side_effect = EOFError()
+
+        # Should complete without raising an exception (graceful exit)
+        simple_main.main()
+
+    @patch('openhands_cli.simple_main.run_cli_entry')
+    def test_main_handles_general_exception(
+        self, mock_run_agent_chat: MagicMock
+    ) -> None:
+        """Test that main() handles general exceptions."""
+        mock_run_agent_chat.side_effect = Exception('Unexpected error')
+
+        # Should raise Exception (re-raised after handling)
+        with pytest.raises(Exception) as exc_info:
+            simple_main.main()
+
+        assert str(exc_info.value) == 'Unexpected error'

openhands-cli/tests/test_pause_listener.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""
+Tests for pause listener in OpenHands CLI.
+"""
+
+import time
+from unittest.mock import MagicMock
+
+from openhands.sdk import Conversation
+from prompt_toolkit.input.defaults import create_pipe_input
+
+from openhands_cli.listeners.pause_listener import PauseListener, pause_listener
+
+
+class TestPauseListener:
+    """Test suite for PauseListener class."""
+
+    def test_pause_listener_stop(self) -> None:
+        """Test PauseListener stop functionality."""
+        mock_callback = MagicMock()
+        listener = PauseListener(on_pause=mock_callback)
+
+        listener.start()
+
+        # Initially not paused
+        assert not listener.is_paused()
+        assert listener.is_alive()
+
+        # Stop the listener
+        listener.stop()
+
+        # Listner was shutdown not paused
+        assert not listener.is_paused()
+        assert listener.is_stopped()
+
+    def test_pause_listener_context_manager(self) -> None:
+        """Test pause_listener context manager."""
+        mock_conversation = MagicMock(spec=Conversation)
+
+        with create_pipe_input() as pipe:
+            with pause_listener(mock_conversation, pipe) as listener:
+                assert isinstance(listener, PauseListener)
+                assert listener.on_pause == mock_conversation.pause
+                # Listener should be started (daemon thread)
+                assert listener.is_alive()
+                assert not listener.is_paused()
+                pipe.send_text('\x10')  # Ctrl-P
+                time.sleep(0.1)
+                assert listener.is_paused()
+
+            assert listener.is_stopped()
+            assert not listener.is_alive()

openhands-cli/tests/test_performance.py

@@ -0,0 +1,196 @@
+"""
+Performance tests for the OpenHands CLI.
+
+These tests ensure that the CLI startup and shutdown times remain fast.
+"""
+
+import time
+import subprocess
+import sys
+import signal
+import os
+import pytest
+from pathlib import Path
+
+
+class TestCLIPerformance:
+    """Test CLI performance characteristics."""
+
+    def test_help_performance(self):
+        """Test that --help is fast (< 0.5s)."""
+        env = os.environ.copy()
+        env['PYTHONPATH'] = str(Path(__file__).parent.parent)
+        
+        start_time = time.time()
+        result = subprocess.run([
+            sys.executable, '-m', 'openhands_cli.simple_main', '--help'
+        ], capture_output=True, text=True, env=env, timeout=10)
+        help_time = time.time() - start_time
+        
+        assert result.returncode == 0, f"--help failed: {result.stderr}"
+        assert help_time < 0.5, f"--help took {help_time:.3f}s, should be < 0.5s"
+        assert "usage:" in result.stdout.lower(), "Help output should contain usage information"
+
+    def test_import_performance(self):
+        """Test that importing the main module is fast (< 0.1s)."""
+        start_time = time.time()
+        
+        # Import in a subprocess to avoid affecting other tests
+        result = subprocess.run([
+            sys.executable, '-c', 
+            'import openhands_cli.simple_main'
+        ], capture_output=True, text=True, 
+        env={'PYTHONPATH': str(Path(__file__).parent.parent)},
+        timeout=5)
+        
+        import_time = time.time() - start_time
+        
+        assert result.returncode == 0, f"Import failed: {result.stderr}"
+        assert import_time < 0.1, f"Import took {import_time:.3f}s, should be < 0.1s"
+
+    def test_shutdown_performance(self):
+        """Test that CLI shutdown is fast (< 0.2s)."""
+        env = os.environ.copy()
+        env['PYTHONPATH'] = str(Path(__file__).parent.parent)
+        
+        # Start the CLI process
+        proc = subprocess.Popen([
+            sys.executable, '-m', 'openhands_cli.simple_main'
+        ], 
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+        text=True
+        )
+        
+        # Give it a moment to start up
+        time.sleep(0.1)
+        
+        # Send SIGINT to trigger shutdown
+        shutdown_start = time.time()
+        proc.send_signal(signal.SIGINT)
+        
+        try:
+            proc.wait(timeout=5)
+            shutdown_time = time.time() - shutdown_start
+            
+            assert shutdown_time < 0.2, f"Shutdown took {shutdown_time:.3f}s, should be < 0.2s"
+            
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+            pytest.fail("Process didn't shut down within timeout")
+
+    def test_lazy_loading_effectiveness(self):
+        """Test that lazy loading prevents heavy modules from being imported early."""
+        # Test in subprocess to avoid affecting other tests
+        result = subprocess.run([
+            sys.executable, '-c', '''
+import sys
+modules_before = set(sys.modules.keys())
+
+import openhands_cli.simple_main
+
+modules_after = set(sys.modules.keys())
+new_modules = modules_after - modules_before
+
+# Check that heavy modules are not loaded
+heavy_modules = [
+    "openhands.sdk",
+    "prompt_toolkit.application", 
+    "prompt_toolkit.shortcuts",
+]
+
+loaded_heavy = [mod for mod in heavy_modules if any(mod in m for m in new_modules)]
+
+if loaded_heavy:
+    print(f"HEAVY_MODULES_LOADED: {loaded_heavy}")
+    exit(1)
+else:
+    print("LAZY_LOADING_OK")
+    exit(0)
+'''
+        ], capture_output=True, text=True,
+        env={'PYTHONPATH': str(Path(__file__).parent.parent)},
+        timeout=5)
+        
+        assert result.returncode == 0, f"Lazy loading test failed: {result.stdout}"
+        assert "LAZY_LOADING_OK" in result.stdout, "Lazy loading should prevent heavy module imports"
+
+    def test_startup_performance(self):
+        """Test that CLI startup is reasonable (< 1.0s)."""
+        env = os.environ.copy()
+        env['PYTHONPATH'] = str(Path(__file__).parent.parent)
+        
+        start_time = time.time()
+        proc = subprocess.Popen([
+            sys.executable, '-m', 'openhands_cli.simple_main'
+        ], 
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+        text=True
+        )
+        
+        # Give it a moment to start up
+        time.sleep(0.1)
+        startup_time = time.time() - start_time
+        
+        # Clean up
+        proc.send_signal(signal.SIGINT)
+        try:
+            proc.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+        
+        assert startup_time < 1.0, f"Startup took {startup_time:.3f}s, should be < 1.0s"
+
+
+class TestPerformanceRegression:
+    """Test for performance regressions."""
+
+    def test_shutdown_time_regression(self):
+        """Ensure shutdown time doesn't regress beyond acceptable limits."""
+        env = os.environ.copy()
+        env['PYTHONPATH'] = str(Path(__file__).parent.parent)
+        
+        # Test multiple times to get consistent results
+        shutdown_times = []
+        
+        for _ in range(3):
+            proc = subprocess.Popen([
+                sys.executable, '-m', 'openhands_cli.simple_main'
+            ], 
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=env,
+            text=True
+            )
+            
+            time.sleep(0.1)
+            
+            shutdown_start = time.time()
+            proc.send_signal(signal.SIGINT)
+            
+            try:
+                proc.wait(timeout=5)
+                shutdown_time = time.time() - shutdown_start
+                shutdown_times.append(shutdown_time)
+                
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait()
+                pytest.fail("Process didn't shut down within timeout")
+        
+        avg_shutdown_time = sum(shutdown_times) / len(shutdown_times)
+        max_shutdown_time = max(shutdown_times)
+        
+        # Ensure average shutdown time is good
+        assert avg_shutdown_time < 0.15, f"Average shutdown time {avg_shutdown_time:.3f}s should be < 0.15s"
+        
+        # Ensure no single shutdown takes too long
+        assert max_shutdown_time < 0.3, f"Max shutdown time {max_shutdown_time:.3f}s should be < 0.3s"

openhands-cli/tests/test_settings_input.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+Core Settings Logic tests
+"""
+
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+from prompt_toolkit.completion import FuzzyWordCompleter
+from prompt_toolkit.validation import ValidationError
+from pydantic import SecretStr
+
+from openhands_cli.user_actions.settings_action import (
+    NonEmptyValueValidator,
+    SettingsType,
+    choose_llm_model,
+    choose_llm_provider,
+    prompt_api_key,
+    settings_type_confirmation,
+)
+
+
+# -------------------------------
+# Settings type selection
+# -------------------------------
+
+def test_settings_type_selection(mock_cli_interactions: Any) -> None:
+    mocks = mock_cli_interactions
+
+    # Basic
+    mocks.cli_confirm.return_value = 0
+    assert settings_type_confirmation() == SettingsType.BASIC
+
+    # Cancel/Go back
+    mocks.cli_confirm.return_value = 2
+    with pytest.raises(KeyboardInterrupt):
+        settings_type_confirmation()
+
+
+# -------------------------------
+# Provider selection flows
+# -------------------------------
+
+def test_provider_selection_with_predefined_options(mock_verified_models: Any, mock_cli_interactions: Any) -> None:
+    from openhands_cli.tui.utils import StepCounter
+    mocks = mock_cli_interactions
+    # first option among display_options is index 0
+    mocks.cli_confirm.return_value = 0
+    step_counter = StepCounter(1)
+    result = choose_llm_provider(step_counter)
+    assert result == 'openai'
+
+
+def test_provider_selection_with_custom_input(mock_verified_models: Any, mock_cli_interactions: Any) -> None:
+    from openhands_cli.tui.utils import StepCounter
+    mocks = mock_cli_interactions
+    # Due to overlapping provider keys between VERIFIED and UNVERIFIED in fixture,
+    # display_options contains 4 providers (with duplicates) + alternate at index 4
+    mocks.cli_confirm.return_value = 4
+    mocks.cli_text_input.return_value = "my-provider"
+    step_counter = StepCounter(1)
+    result = choose_llm_provider(step_counter)
+    assert result == "my-provider"
+
+    # Verify fuzzy completer passed
+    _, kwargs = mocks.cli_text_input.call_args
+    assert isinstance(kwargs["completer"], FuzzyWordCompleter)
+
+
+# -------------------------------
+# Model selection flows
+# -------------------------------
+
+def test_model_selection_flows(mock_verified_models: Any, mock_cli_interactions: Any) -> None:
+    from openhands_cli.tui.utils import StepCounter
+    mocks = mock_cli_interactions
+
+    # Direct pick from predefined list
+    mocks.cli_confirm.return_value = 0
+    step_counter = StepCounter(1)
+    result = choose_llm_model(step_counter, "openai")
+    assert result in ["gpt-4o"]
+
+    # Choose custom model via input
+    mocks.cli_confirm.return_value = 4  # for provider with >=4 models this would be alt; in our data openai has 3 -> alt index is 3
+    mocks.cli_text_input.return_value = "custom-model"
+    # Adjust to actual alt index produced by code (len(models[:4]) yields 3 + 1 alt -> index 3)
+    mocks.cli_confirm.return_value = 3
+    step_counter2 = StepCounter(1)
+    result2 = choose_llm_model(step_counter2, "openai")
+    assert result2 == "custom-model"
+
+
+# -------------------------------
+# API key validation and prompting
+# -------------------------------
+
+def test_api_key_validation_and_prompting(mock_cli_interactions: Any) -> None:
+    # Validator standalone
+    validator = NonEmptyValueValidator()
+    doc = MagicMock(); doc.text = "sk-abc"
+    validator.validate(doc)
+
+    doc_empty = MagicMock(); doc_empty.text = ""
+    with pytest.raises(ValidationError):
+        validator.validate(doc_empty)
+
+    # Prompting for new key enforces validator
+    from openhands_cli.tui.utils import StepCounter
+    mocks = mock_cli_interactions
+    mocks.cli_text_input.return_value = "sk-new"
+    step_counter = StepCounter(1)
+    new_key = prompt_api_key(step_counter, 'provider')
+    assert new_key == "sk-new"
+    assert mocks.cli_text_input.call_args[1]["validator"] is not None
+
+    # Prompting with existing key shows mask and no validator
+    mocks.cli_text_input.reset_mock()
+    mocks.cli_text_input.return_value = "sk-updated"
+    existing = SecretStr("sk-existing-123")
+    step_counter2 = StepCounter(1)
+    updated = prompt_api_key(step_counter2, 'provider', existing)
+    assert updated == "sk-updated"
+    assert mocks.cli_text_input.call_args[1]["validator"] is None
+    assert "sk-***" in mocks.cli_text_input.call_args[0][0]

openhands-cli/tests/test_settings_workflow.py

@@ -0,0 +1,133 @@
+import json
+from unittest.mock import MagicMock, patch
+from openhands_cli.tui.settings.settings_screen import SettingsScreen
+from pathlib import Path
+
+from openhands.sdk import LLM, Conversation, LocalFileStore
+from openhands.sdk.preset.default import get_default_agent
+from openhands_cli.tui.settings.store import AgentStore
+from openhands_cli.user_actions.settings_action import SettingsType
+from pydantic import SecretStr
+import pytest
+
+def read_json(path: Path) -> dict:
+    with open(path, "r") as f:
+        return json.load(f)
+
+def make_screen_with_conversation(model="openai/gpt-4o-mini", api_key="sk-xyz"):
+    llm = LLM(model=model, api_key=SecretStr(api_key))
+    # Conversation(agent) signature may vary across versions; adapt if needed:
+    from openhands.sdk.agent import Agent
+    agent = Agent(llm=llm, tools=[])
+    conv = Conversation(agent)
+    return SettingsScreen(conversation=conv)
+
+def seed_file(path: Path, model: str = "openai/gpt-4o-mini", api_key: str = "sk-old"):
+    store = AgentStore()
+    store.file_store = LocalFileStore(root=str(path))
+    agent = get_default_agent(
+        llm=LLM(model=model, api_key=SecretStr(api_key)),
+        working_dir=str(path)
+    )
+    store.save(agent)
+
+
+def test_llm_settings_save_and_load(tmp_path: Path):
+    """Test that the settings screen can save basic LLM settings."""
+    screen = SettingsScreen(conversation=None)
+
+    # Mock the spec store to verify settings are saved
+    with patch.object(screen.agent_store, 'save') as mock_save:
+        screen._save_llm_settings(
+            model="openai/gpt-4o-mini",
+            api_key="sk-test-123"
+        )
+
+        # Verify that save was called
+        mock_save.assert_called_once()
+
+        # Get the agent spec that was saved
+        saved_spec = mock_save.call_args[0][0]
+        assert saved_spec.llm.model == "openai/gpt-4o-mini"
+        assert saved_spec.llm.api_key.get_secret_value() == "sk-test-123"
+
+
+def test_first_time_setup_workflow(tmp_path: Path):
+    """Test that the basic settings workflow completes without errors."""
+    screen = SettingsScreen()
+
+    with (
+        patch("openhands_cli.tui.settings.settings_screen.settings_type_confirmation", return_value=SettingsType.BASIC),
+        patch("openhands_cli.tui.settings.settings_screen.choose_llm_provider", return_value="openai"),
+        patch("openhands_cli.tui.settings.settings_screen.choose_llm_model", return_value="gpt-4o-mini"),
+        patch("openhands_cli.tui.settings.settings_screen.prompt_api_key", return_value="sk-first"),
+        patch("openhands_cli.tui.settings.settings_screen.save_settings_confirmation", return_value=True),
+    ):
+        # The workflow should complete without errors
+        screen.configure_settings()
+
+    # Since the current implementation doesn't save to file, we just verify the workflow completed
+    assert True  # If we get here, the workflow completed successfully
+
+
+def test_update_existing_settings_workflow(tmp_path: Path):
+    """Test that the settings update workflow completes without errors."""
+    settings_path = tmp_path / "agent_settings.json"
+    seed_file(settings_path, model="openai/gpt-4o-mini", api_key="sk-old")
+    screen = make_screen_with_conversation(model="openai/gpt-4o-mini", api_key="sk-old")
+
+    with (
+        patch("openhands_cli.tui.settings.settings_screen.settings_type_confirmation", return_value=SettingsType.BASIC),
+        patch("openhands_cli.tui.settings.settings_screen.choose_llm_provider", return_value="anthropic"),
+        patch("openhands_cli.tui.settings.settings_screen.choose_llm_model", return_value="claude-3-5-sonnet"),
+        patch("openhands_cli.tui.settings.settings_screen.prompt_api_key", return_value="sk-updated"),
+        patch("openhands_cli.tui.settings.settings_screen.save_settings_confirmation", return_value=True),
+    ):
+        # The workflow should complete without errors
+        screen.configure_settings()
+
+    # Since the current implementation doesn't save to file, we just verify the workflow completed
+    assert True  # If we get here, the workflow completed successfully
+
+
+@pytest.mark.parametrize(
+    "step_to_cancel",
+    ["type", "provider", "model", "apikey", "save"],
+)
+def test_workflow_cancellation_at_each_step(tmp_path: Path, step_to_cancel: str):
+    screen = make_screen_with_conversation()
+
+    # Base happy-path patches
+    patches = {
+        "settings_type_confirmation": MagicMock(return_value=SettingsType.BASIC),
+        "choose_llm_provider": MagicMock(return_value="openai"),
+        "choose_llm_model": MagicMock(return_value="gpt-4o-mini"),
+        "prompt_api_key": MagicMock(return_value="sk-new"),
+        "save_settings_confirmation": MagicMock(return_value=True),
+    }
+
+    # Turn one step into a cancel
+    if step_to_cancel == "type":
+        patches["settings_type_confirmation"].side_effect = KeyboardInterrupt()
+    elif step_to_cancel == "provider":
+        patches["choose_llm_provider"].side_effect = KeyboardInterrupt()
+    elif step_to_cancel == "model":
+        patches["choose_llm_model"].side_effect = KeyboardInterrupt()
+    elif step_to_cancel == "apikey":
+        patches["prompt_api_key"].side_effect = KeyboardInterrupt()
+    elif step_to_cancel == "save":
+        patches["save_settings_confirmation"].side_effect = KeyboardInterrupt()
+
+    with (
+        patch("openhands_cli.tui.settings.settings_screen.settings_type_confirmation", patches["settings_type_confirmation"]),
+        patch("openhands_cli.tui.settings.settings_screen.choose_llm_provider", patches["choose_llm_provider"]),
+        patch("openhands_cli.tui.settings.settings_screen.choose_llm_model", patches["choose_llm_model"]),
+        patch("openhands_cli.tui.settings.settings_screen.prompt_api_key", patches["prompt_api_key"]),
+        patch("openhands_cli.tui.settings.settings_screen.save_settings_confirmation", patches["save_settings_confirmation"]),
+        patch.object(screen.agent_store, 'save') as mock_save,
+    ):
+        screen.configure_settings()
+
+    # No settings should be saved on cancel
+    mock_save.assert_not_called()
+

openhands-cli/tests/test_tui.py

@@ -0,0 +1,94 @@
+"""Tests for TUI functionality."""
+
+from prompt_toolkit.completion import CompleteEvent
+from prompt_toolkit.document import Document
+
+from openhands_cli.tui.tui import COMMANDS, CommandCompleter
+
+
+class TestCommandCompleter:
+    """Test the CommandCompleter class."""
+
+    def test_command_completion_with_slash(self) -> None:
+        """Test that commands are completed when starting with /."""
+        completer = CommandCompleter()
+        document = Document('/')
+        completions = list(completer.get_completions(document, CompleteEvent()))
+
+        # Should return all available commands
+        assert len(completions) == len(COMMANDS)
+
+        # Check that all commands are included
+        completion_texts = [c.text for c in completions]
+        for command in COMMANDS.keys():
+            assert command in completion_texts
+
+    def test_command_completion_partial_match(self) -> None:
+        """Test that partial command matches work correctly."""
+        completer = CommandCompleter()
+        document = Document('/ex')
+        completions = list(completer.get_completions(document, CompleteEvent()))
+
+        # Should return only /exit
+        assert len(completions) == 1
+        assert completions[0].text == '/exit'
+        # display_meta is a FormattedText object, so we need to check its content
+        # Extract the text from FormattedText
+        meta_text = completions[0].display_meta
+        if hasattr(meta_text, '_formatted_text'):
+            # Extract text from FormattedText
+            text_content = ''.join([item[1] for item in meta_text._formatted_text])
+        else:
+            text_content = str(meta_text)
+        assert COMMANDS['/exit'] in text_content
+
+    def test_command_completion_no_slash(self) -> None:
+        """Test that no completions are returned without /."""
+        completer = CommandCompleter()
+        document = Document('help')
+        completions = list(completer.get_completions(document, CompleteEvent()))
+
+        # Should return no completions
+        assert len(completions) == 0
+
+    def test_command_completion_no_match(self) -> None:
+        """Test that no completions are returned for non-matching commands."""
+        completer = CommandCompleter()
+        document = Document('/nonexistent')
+        completions = list(completer.get_completions(document, CompleteEvent()))
+
+        # Should return no completions
+        assert len(completions) == 0
+
+    def test_command_completion_styling(self) -> None:
+        """Test that completions have proper styling."""
+        completer = CommandCompleter()
+        document = Document('/help')
+        completions = list(completer.get_completions(document, CompleteEvent()))
+
+        assert len(completions) == 1
+        completion = completions[0]
+        assert completion.style == 'bg:ansidarkgray fg:gold'
+        assert completion.start_position == -5  # Length of "/help"
+
+
+def test_commands_dict() -> None:
+    """Test that COMMANDS dictionary contains expected commands."""
+    expected_commands = {
+        '/exit',
+        '/help',
+        '/clear',
+        '/status',
+        '/confirm',
+        '/new',
+        '/resume',
+        '/settings',
+    }
+    assert set(COMMANDS.keys()) == expected_commands
+
+    # Check that all commands have descriptions
+    for command, description in COMMANDS.items():
+        assert isinstance(command, str)
+        assert command.startswith('/')
+        assert isinstance(description, str)
+        assert len(description) > 0

openhands-cli/tests/utils.py

@@ -0,0 +1,9 @@
+import time
+
+from prompt_toolkit.input import PipeInput
+
+
+def _send_keys(pipe: PipeInput, text: str, delay: float = 0.05) -> None:
+    """Helper: small delay then send keys to avoid race with app.run()."""
+    time.sleep(delay)
+    pipe.send_text(text)