openhands 1.3.0__py3-none-any.whl

openhands_cli/acp_impl/utils/__init__.py

@@ -0,0 +1,14 @@
+from openhands_cli.acp_impl.utils.convert import convert_acp_prompt_to_message_content
+from openhands_cli.acp_impl.utils.mcp import (
+    ACPMCPServerType,
+    convert_acp_mcp_servers_to_agent_format,
+)
+from openhands_cli.acp_impl.utils.resources import RESOURCE_SKILL
+
+
+__all__ = [
+    "convert_acp_mcp_servers_to_agent_format",
+    "ACPMCPServerType",
+    "convert_acp_prompt_to_message_content",
+    "RESOURCE_SKILL",
+]

openhands_cli/acp_impl/utils/convert.py

@@ -0,0 +1,103 @@
+"""Utility functions for ACP implementation."""
+
+import base64
+from uuid import uuid4
+
+from acp.schema import (
+    AudioContentBlock as ACPAudioContentBlock,
+    EmbeddedResourceContentBlock as ACPEmbeddedResourceContentBlock,
+    ImageContentBlock as ACPImageContentBlock,
+    ResourceContentBlock as ACPResourceContentBlock,
+    TextContentBlock as ACPTextContentBlock,
+)
+
+from openhands.sdk import ImageContent, TextContent
+from openhands_cli.acp_impl.utils.resources import (
+    ACP_CACHE_DIR,
+    SUPPORTED_IMAGE_MIME_TYPES,
+    _convert_image_to_supported_format,
+    convert_resources_to_content,
+)
+
+
+def _convert_image_block(block: ACPImageContentBlock) -> TextContent | ImageContent:
+    """
+    Convert an ACP image content block to SDK format.
+
+    Handles:
+    1. Supported image formats -> ImageContent
+    2. Unsupported but convertible formats -> ImageContent with converted data
+    3. Unsupported and non-convertible formats -> TextContent with file path
+
+    Args:
+        block: ACP image content block
+
+    Returns:
+        ImageContent if format is supported or convertible, TextContent otherwise
+    """
+    # Handle supported formats directly
+    if block.mimeType in SUPPORTED_IMAGE_MIME_TYPES:
+        return ImageContent(image_urls=[f"data:{block.mimeType};base64,{block.data}"])
+
+    # Try to convert unsupported formats
+    data = base64.b64decode(block.data)
+    converted = _convert_image_to_supported_format(data, block.mimeType)
+
+    if converted is not None:
+        target_mime, converted_data = converted
+        return ImageContent(image_urls=[f"data:{target_mime};base64,{converted_data}"])
+
+    # Conversion failed - save to disk and return explanatory text
+    filename = f"image_{uuid4().hex}"
+    target = ACP_CACHE_DIR / filename
+    target.write_bytes(data)
+    supported = ", ".join(sorted(SUPPORTED_IMAGE_MIME_TYPES))
+
+    return TextContent(
+        text=(
+            "\n[BEGIN USER PROVIDED ADDITIONAL CONTEXT]\n"
+            f"User provided image with unsupported format ({block.mimeType}).\n"
+            "Attempted automatic conversion failed.\n"
+            f"Supported formats: {supported}\n"
+            f"Saved to file: {str(target)}\n"
+            "[END USER PROVIDED ADDITIONAL CONTEXT]\n"
+        )
+    )
+
+
+def convert_acp_prompt_to_message_content(
+    acp_prompt: list[
+        ACPTextContentBlock
+        | ACPImageContentBlock
+        | ACPAudioContentBlock
+        | ACPResourceContentBlock
+        | ACPEmbeddedResourceContentBlock,
+    ],
+) -> list[TextContent | ImageContent]:
+    """
+    Convert ACP prompt to OpenHands message content format.
+
+    Handles various ACP prompt formats:
+    - Simple string
+    - List of content blocks (text/image)
+    - Single ContentBlock object
+
+    Args:
+        prompt: ACP prompt in various formats (string, list, or ContentBlock)
+
+    Returns:
+        List of TextContent and ImageContent objects supported by SDK
+    """
+    message_content: list[TextContent | ImageContent] = []
+    for block in acp_prompt:
+        if isinstance(block, ACPTextContentBlock):
+            message_content.append(TextContent(text=block.text))
+        elif isinstance(block, ACPImageContentBlock):
+            message_content.append(_convert_image_block(block))
+        elif isinstance(
+            block, ACPResourceContentBlock | ACPEmbeddedResourceContentBlock
+        ):
+            # https://agentclientprotocol.com/protocol/content#resource-link
+            # https://agentclientprotocol.com/protocol/content#embedded-resource
+            message_content.append(convert_resources_to_content(block))
+    return message_content

openhands_cli/acp_impl/utils/mcp.py

@@ -0,0 +1,66 @@
+"""Utility functions for MCP in ACP implementation."""
+
+from collections.abc import Sequence
+from typing import Any
+
+from acp.schema import (
+    HttpMcpServer,
+    SseMcpServer,
+    StdioMcpServer,
+)
+
+
+ACPMCPServerType = StdioMcpServer | HttpMcpServer | SseMcpServer
+
+
+def _convert_env_to_dict(env: Sequence[dict[str, str]]) -> dict[str, str]:
+    """
+    Convert environment variables from serialized EnvVariable format to a dictionary.
+
+    When Pydantic models are dumped to dict, EnvVariable objects become dicts
+    with 'name' and 'value' keys.
+
+    Args:
+        env: List of dicts with 'name' and 'value' keys (serialized EnvVariable objects)
+
+    Returns:
+        Dictionary mapping environment variable names to values
+    """
+    env_dict: dict[str, str] = {}
+    for env_var in env:
+        env_dict[env_var["name"]] = env_var["value"]
+    return env_dict
+
+
+def convert_acp_mcp_servers_to_agent_format(
+    mcp_servers: Sequence[ACPMCPServerType],
+) -> dict[str, dict[str, Any]]:
+    """
+    Convert MCP servers from ACP format to Agent format.
+
+    ACP and Agent use different formats for MCP server configurations:
+    - ACP: List of Pydantic server models with 'name' field, env as array of EnvVariable
+    - Agent: Dict keyed by server name, env as dict
+
+    Args:
+        mcp_servers: List of MCP server Pydantic models from ACP
+
+    Returns:
+        Dictionary of MCP servers in Agent format (keyed by name)
+    """
+    converted_servers: dict[str, dict[str, Any]] = {}
+
+    for server in mcp_servers:
+        server_dict = server.model_dump()
+        server_name: str = server_dict["name"]
+        server_config: dict[str, Any] = {
+            k: v for k, v in server_dict.items() if k != "name"
+        }
+
+        # Convert env from array to dict format if present
+        # ACP sends env as array of EnvVariable objects, but Agent expects dict
+        if "env" in server_config:
+            server_config["env"] = _convert_env_to_dict(server_config["env"])
+        converted_servers[server_name] = server_config
+
+    return converted_servers

openhands_cli/acp_impl/utils/resources.py

@@ -0,0 +1,189 @@
+"""Utility functions for ACP implementation."""
+
+import base64
+import io
+import mimetypes
+from pathlib import Path
+from uuid import uuid4
+
+from acp.schema import (
+    BlobResourceContents as ACPBlobResourceContents,
+    EmbeddedResourceContentBlock as ACPEmbeddedResourceContentBlock,
+    ResourceContentBlock as ACPResourceContentBlock,
+    TextResourceContents as ACPTextResourceContents,
+)
+from PIL import Image
+
+from openhands.sdk import ImageContent, TextContent
+from openhands.sdk.context import Skill
+
+
+RESOURCE_SKILL = Skill(
+    name="user_provided_resources",
+    content=(
+        "You may encounter sections labeled as user-provided additional "
+        "context or resources. "
+        "These blocks contain files or data that the user referenced in their message. "
+        "They may include plain text, images, code snippets, or binary "
+        "content saved to a temporary file. "
+        "Treat these blocks as part of the user’s input. "
+        "Read them carefully and use their contents when forming your "
+        "reasoning or answering the query. "
+        "If a block points to a saved file, assume it contains relevant "
+        "binary data that could not be displayed directly."
+    ),
+    trigger=None,
+)
+
+ACP_CACHE_DIR = Path.home() / ".openhands" / "cache" / "acp"
+ACP_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+# LLM API supported image MIME types (Anthropic/Claude compatible)
+SUPPORTED_IMAGE_MIME_TYPES = {
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+}
+
+
+def _convert_image_to_supported_format(
+    image_data: bytes,
+    source_mime_type: str,  # noqa: ARG001
+) -> tuple[str, str] | None:
+    """
+    Try to convert an unsupported image format to PNG.
+
+    Args:
+        image_data: The raw image bytes
+        source_mime_type: The original MIME type (currently unused but kept for API)
+
+    Returns:
+        A tuple of (mime_type, base64_data) if conversion succeeds, None otherwise
+    """
+    try:
+        # Open the image with Pillow
+        img = Image.open(io.BytesIO(image_data))
+
+        # Convert to RGB if necessary (some formats like RGBA need this for JPEG)
+        # PNG supports transparency, so we'll use PNG as target format
+        if img.mode in ("RGBA", "LA", "P"):
+            # Keep transparency by converting to PNG
+            output_format = "PNG"
+            target_mime = "image/png"
+        else:
+            # For non-transparent images, we can use PNG or JPEG
+            # PNG is lossless, so prefer it
+            output_format = "PNG"
+            target_mime = "image/png"
+
+        # Convert the image to the target format
+        output_buffer = io.BytesIO()
+        img.save(output_buffer, format=output_format)
+        output_buffer.seek(0)
+
+        # Encode to base64
+        converted_data = base64.b64encode(output_buffer.read()).decode("utf-8")
+
+        return target_mime, converted_data
+
+    except Exception:
+        # If conversion fails for any reason, return None
+        # This could happen for corrupted images, unsupported formats, etc.
+        return None
+
+
+def _materialize_embedded_resource(
+    block: ACPEmbeddedResourceContentBlock,
+) -> TextContent | ImageContent:
+    """
+    For:
+    - text resources: return TextContent containing the text.
+    - image blobs: return ImageContent directly (no disk write).
+    - other binary blobs: write to disk and return TextContent explaining the path.
+    """
+    res: ACPTextResourceContents | ACPBlobResourceContents = block.resource
+
+    if isinstance(res, ACPTextResourceContents):
+        return TextContent(
+            text=(
+                "\n[BEGIN USER PROVIDED ADDITIONAL CONTEXT]\n"
+                f"URI: {res.uri}\n"
+                f"mimeType: {res.mimeType}\n"
+                "Content:\n"
+                f"{res.text}\n"
+                "[END USER PROVIDED ADDITIONAL CONTEXT]\n"
+            )
+        )
+
+    elif isinstance(res, ACPBlobResourceContents):
+        mime_type = res.mimeType or ""
+
+        # 1. If it's a supported image type, directly return ImageContent
+        if mime_type in SUPPORTED_IMAGE_MIME_TYPES:
+            data_uri = f"data:{mime_type};base64,{res.blob}"
+            return ImageContent(image_urls=[data_uri])
+
+        # 2. If it's an unsupported image type, try to convert it
+        if mime_type.startswith("image/"):
+            data = base64.b64decode(res.blob)
+            converted = _convert_image_to_supported_format(data, mime_type)
+
+            if converted is not None:
+                # Conversion succeeded, return as ImageContent
+                target_mime, converted_data = converted
+                data_uri = f"data:{target_mime};base64,{converted_data}"
+                return ImageContent(image_urls=[data_uri])
+
+            # Conversion failed, fall through to disk storage
+
+        # 3. For non-images or failed conversions, save to disk
+        data = base64.b64decode(res.blob)
+
+        ext = ""
+        if mime_type:
+            ext = mimetypes.guess_extension(mime_type) or ""
+
+        filename = f"embedded_resource_{uuid4().hex}{ext}"
+        target = ACP_CACHE_DIR / filename
+        target.write_bytes(data)
+
+        # Provide appropriate message based on content type
+        if mime_type.startswith("image/"):
+            description = (
+                f"User provided image with unsupported format ({mime_type}).\n"
+                "Attempted automatic conversion failed.\n"
+                f"Supported formats: {', '.join(sorted(SUPPORTED_IMAGE_MIME_TYPES))}\n"
+            )
+        else:
+            description = "User provided binary context (non-image).\n"
+
+        return TextContent(
+            text=(
+                "\n[BEGIN USER PROVIDED ADDITIONAL CONTEXT]\n"
+                f"{description}"
+                f"Saved to file: {str(target)}\n"
+                "[END USER PROVIDED ADDITIONAL CONTEXT]\n"
+            )
+        )
+
+
+def convert_resources_to_content(
+    resource: ACPResourceContentBlock | ACPEmbeddedResourceContentBlock,
+) -> TextContent | ImageContent:
+    if isinstance(resource, ACPResourceContentBlock):
+        return TextContent(
+            text=(
+                "\n[BEGIN USER PROVIDED ADDITIONAL RESOURCE]\n"
+                f"Type: {resource.type}\n"
+                f"URI: {resource.uri}\n"
+                f"name: {resource.name}\n"
+                f"mimeType: {resource.mimeType}\n"
+                f"size: {resource.size}\n"
+                "[END USER PROVIDED ADDITIONAL RESOURCE]\n"
+            )
+        )
+    elif isinstance(resource, ACPEmbeddedResourceContentBlock):
+        return _materialize_embedded_resource(resource)
+
+    raise ValueError(f"Unexpected resource type: {type(resource)}")

openhands_cli/agent_chat.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""
+Agent chat functionality for OpenHands CLI.
+Provides a conversation interface with an AI agent using OpenHands patterns.
+"""
+
+import sys
+import uuid
+from datetime import datetime
+
+from prompt_toolkit import print_formatted_text
+from prompt_toolkit.formatted_text import HTML
+
+from openhands.sdk import (
+    Message,
+    TextContent,
+)
+from openhands.sdk.conversation.state import ConversationExecutionStatus
+from openhands_cli.runner import ConversationRunner
+from openhands_cli.setup import (
+    MissingAgentSpec,
+    setup_conversation,
+    verify_agent_exists_or_setup_agent,
+)
+from openhands_cli.tui.settings.mcp_screen import MCPScreen
+from openhands_cli.tui.settings.settings_screen import SettingsScreen
+from openhands_cli.tui.status import display_status
+from openhands_cli.tui.tui import (
+    display_help,
+    display_welcome,
+)
+from openhands_cli.user_actions import UserConfirmation, exit_session_confirmation
+from openhands_cli.user_actions.utils import get_session_prompter
+
+
+def _restore_tty() -> None:
+    """
+    Ensure terminal modes are reset in case prompt_toolkit cleanup didn't run.
+    - Turn off application cursor keys (DECCKM): ESC[?1l
+    - Turn off bracketed paste: ESC[?2004l
+    """
+    try:
+        sys.stdout.write("\x1b[?1l\x1b[?2004l")
+        sys.stdout.flush()
+    except Exception:
+        pass
+
+
+def _print_exit_hint(conversation_id: str) -> None:
+    """Print a resume hint with the current conversation ID."""
+    print_formatted_text(
+        HTML(f"<grey>Conversation ID:</grey> <yellow>{conversation_id}</yellow>")
+    )
+    print_formatted_text(
+        HTML(
+            f"<grey>Hint:</grey> run <gold>openhands --resume {conversation_id}</gold> "
+            "to resume this conversation."
+        )
+    )
+
+
+def run_cli_entry(
+    resume_conversation_id: str | None = None,
+    queued_inputs: list[str] | None = None,
+) -> 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
+    """
+
+    # Normalize queued_inputs to a local copy to prevent mutating the caller's list
+    pending_inputs = list(queued_inputs) if queued_inputs else []
+
+    conversation_id = uuid.uuid4()
+    if resume_conversation_id:
+        try:
+            conversation_id = uuid.UUID(resume_conversation_id)
+        except ValueError:
+            print_formatted_text(
+                HTML(
+                    f"<yellow>Warning: '{resume_conversation_id}' is not a valid "
+                    f"UUID.</yellow>"
+                )
+            )
+            return
+
+    try:
+        initialized_agent = verify_agent_exists_or_setup_agent()
+    except MissingAgentSpec:
+        print_formatted_text(
+            HTML("\n<yellow>Setup is required to use OpenHands CLI.</yellow>")
+        )
+        print_formatted_text(HTML("\n<yellow>Goodbye! 👋</yellow>"))
+        return
+
+    display_welcome(conversation_id, bool(resume_conversation_id))
+
+    # Track session start time for uptime calculation
+    session_start_time = datetime.now()
+
+    # Create conversation runner to handle state machine logic
+    runner = None
+    conversation = None
+    session = get_session_prompter()
+
+    # Main chat loop
+    while True:
+        try:
+            # Get user input
+            if pending_inputs:
+                user_input = pending_inputs.pop(0)
+            else:
+                user_input = session.prompt(
+                    HTML("<gold>> </gold>"),
+                    multiline=False,
+                )
+
+            if not user_input.strip():
+                continue
+
+            # Handle commands
+            command = user_input.strip().lower()
+
+            message = Message(
+                role="user",
+                content=[TextContent(text=user_input)],
+            )
+
+            if command == "/exit":
+                exit_confirmation = exit_session_confirmation()
+                if exit_confirmation == UserConfirmation.ACCEPT:
+                    print_formatted_text(HTML("\n<yellow>Goodbye! 👋</yellow>"))
+                    _print_exit_hint(str(conversation_id))
+                    break
+
+            elif command == "/settings":
+                settings_screen = SettingsScreen(
+                    runner.conversation if runner else None
+                )
+                settings_screen.display_settings()
+                continue
+
+            elif command == "/mcp":
+                mcp_screen = MCPScreen()
+                mcp_screen.display_mcp_info(initialized_agent)
+                continue
+
+            elif command == "/clear":
+                display_welcome(conversation_id)
+                continue
+
+            elif command == "/new":
+                try:
+                    # Start a fresh conversation (no resume ID = new conversation)
+                    conversation_id = uuid.uuid4()
+                    runner = None
+                    conversation = None
+                    display_welcome(conversation_id, resume=False)
+                    print_formatted_text(
+                        HTML("<green>✓ Started fresh conversation</green>")
+                    )
+                    continue
+                except Exception as e:
+                    print_formatted_text(
+                        HTML(f"<red>Error starting fresh conversation: {e}</red>")
+                    )
+                    continue
+
+            elif command == "/help":
+                display_help()
+                continue
+
+            elif command == "/status":
+                if conversation is not None:
+                    display_status(conversation, session_start_time=session_start_time)
+                else:
+                    print_formatted_text(
+                        HTML("<yellow>No active conversation</yellow>")
+                    )
+                continue
+
+            elif command == "/confirm":
+                if runner is not None:
+                    runner.toggle_confirmation_mode()
+                    new_status = (
+                        "enabled" if runner.is_confirmation_mode_active else "disabled"
+                    )
+                else:
+                    new_status = "disabled (no active conversation)"
+                print_formatted_text(
+                    HTML(f"<yellow>Confirmation mode {new_status}</yellow>")
+                )
+                continue
+
+            elif command == "/resume":
+                if not runner:
+                    print_formatted_text(
+                        HTML("<yellow>No active conversation running...</yellow>")
+                    )
+                    continue
+
+                conversation = runner.conversation
+                if not (
+                    conversation.state.execution_status
+                    == ConversationExecutionStatus.PAUSED
+                    or conversation.state.execution_status
+                    == ConversationExecutionStatus.WAITING_FOR_CONFIRMATION
+                ):
+                    print_formatted_text(
+                        HTML("<red>No paused conversation to resume...</red>")
+                    )
+                    continue
+
+                # Resume without new message
+                message = None
+
+            if not runner or not conversation:
+                conversation = setup_conversation(conversation_id)
+                runner = ConversationRunner(conversation)
+            runner.process_message(message)
+
+            print()  # Add spacing
+
+        except KeyboardInterrupt:
+            exit_confirmation = exit_session_confirmation()
+            if exit_confirmation == UserConfirmation.ACCEPT:
+                print_formatted_text(HTML("\n<yellow>Goodbye! 👋</yellow>"))
+                _print_exit_hint(str(conversation_id))
+                break
+
+    # Clean up terminal state
+    _restore_tty()

openhands_cli/argparsers/main_parser.py

@@ -0,0 +1,78 @@
+"""Main argument parser for OpenHands CLI."""
+
+import argparse
+
+from openhands_cli import __version__
+
+
+def create_main_parser() -> argparse.ArgumentParser:
+    """Create the main argument parser with CLI as default and serve as subcommand.
+
+    Returns:
+        The configured argument parser
+    """
+    parser = argparse.ArgumentParser(
+        description="OpenHands CLI - Terminal User Interface for OpenHands AI Agent",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+            By default, OpenHands runs in CLI mode (terminal interface).
+            Use 'serve' subcommand to launch the GUI server instead.
+
+            Examples:
+                openhands                           # Start CLI mode
+                openhands --resume conversation-id  # Resume a conversation in CLI mode
+                openhands serve                     # Launch GUI server
+                openhands serve --gpu               # Launch GUI server with GPU support
+                openhands acp                       # Start as Agent-Client Protocol
+                                                      server for clients like Zed IDE
+        """,
+    )
+
+    # Version argument
+    parser.add_argument(
+        "--version",
+        "-v",
+        action="version",
+        version=f"OpenHands CLI {__version__}",
+        help="Show the version number and exit",
+    )
+
+    parser.add_argument(
+        "-t",
+        "--task",
+        type=str,
+        help="Initial task text to seed the conversation with",
+    )
+
+    parser.add_argument(
+        "-f",
+        "--file",
+        type=str,
+        help="Path to a file whose contents will seed the initial conversation",
+    )
+
+    # CLI arguments at top level (default mode)
+    parser.add_argument("--resume", type=str, help="Conversation ID to resume")
+
+    # Subcommands
+    subparsers = parser.add_subparsers(dest="command", help="Additional commands")
+
+    # Add serve subcommand
+    serve_parser = subparsers.add_parser(
+        "serve", help="Launch the OpenHands GUI server using Docker (web interface)"
+    )
+    serve_parser.add_argument(
+        "--mount-cwd",
+        action="store_true",
+        help="Mount the current working directory in the Docker container",
+    )
+    serve_parser.add_argument(
+        "--gpu", action="store_true", help="Enable GPU support in the Docker container"
+    )
+
+    # Add ACP subcommand
+    subparsers.add_parser(
+        "acp", help="Start OpenHands as an Agent Client Protocol (ACP) agent"
+    )
+
+    return parser