openhands-agent-server 1.8.2__py3-none-any.whl

openhands/agent_server/file_router.py

@@ -0,0 +1,121 @@
+from pathlib import Path
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import (
+    APIRouter,
+    File,
+    HTTPException,
+    Path as FastApiPath,
+    UploadFile,
+    status,
+)
+from fastapi.responses import FileResponse
+from starlette.background import BackgroundTask
+
+from openhands.agent_server.bash_service import get_default_bash_event_service
+from openhands.agent_server.config import get_default_config
+from openhands.agent_server.conversation_service import get_default_conversation_service
+from openhands.agent_server.models import ExecuteBashRequest, Success
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+file_router = APIRouter(prefix="/file", tags=["Files"])
+config = get_default_config()
+conversation_service = get_default_conversation_service()
+bash_event_service = get_default_bash_event_service()
+
+
+@file_router.post("/upload/{path:path}")
+async def upload_file(
+    path: Annotated[str, FastApiPath(alias="path", description="Absolute file path.")],
+    file: Annotated[UploadFile, File(...)],
+) -> Success:
+    """Upload a file to the workspace."""
+    logger.info(f"Uploading file: {path}")
+    try:
+        target_path = Path(path)
+        if not target_path.is_absolute():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Path must be absolute",
+            )
+
+        # Ensure target directory exists
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Stream the file to disk to avoid memory issues with large files
+        with open(target_path, "wb") as f:
+            while chunk := await file.read(8192):  # Read in 8KB chunks
+                f.write(chunk)
+
+        logger.info(f"Uploaded file to {target_path}")
+        return Success()
+
+    except Exception as e:
+        logger.error(f"Failed to upload file: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to upload file: {str(e)}",
+        )
+
+
+@file_router.get("/download/{path:path}")
+async def download_file(
+    path: Annotated[str, FastApiPath(description="Absolute file path.")],
+) -> FileResponse:
+    """Download a file from the workspace."""
+    logger.info(f"Downloading file: {path}")
+    try:
+        target_path = Path(path)
+        if not target_path.is_absolute():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Path must be absolute",
+            )
+
+        if not target_path.exists():
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="File not found"
+            )
+
+        if not target_path.is_file():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="Path is not a file"
+            )
+
+        return FileResponse(
+            path=target_path,
+            filename=target_path.name,
+            media_type="application/octet-stream",
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to download file: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to download file: {str(e)}",
+        )
+
+
+@file_router.get("/download-trajectory/{conversation_id}")
+async def download_trajectory(
+    conversation_id: UUID,
+) -> FileResponse:
+    """Download a file from the workspace."""
+    config = get_default_config()
+    temp_file = config.conversations_path / f"{conversation_id.hex}.zip"
+    conversation_dir = config.conversations_path / conversation_id.hex
+    _, task = await bash_event_service.start_bash_command(
+        ExecuteBashRequest(command=f"zip -r {temp_file} {conversation_dir}")
+    )
+    await task
+    return FileResponse(
+        path=temp_file,
+        filename=temp_file.name,
+        media_type="application/octet-stream",
+        background=BackgroundTask(temp_file.unlink),
+    )

openhands/agent_server/git_router.py

@@ -0,0 +1,34 @@
+"""Git router for OpenHands SDK."""
+
+import asyncio
+import logging
+from pathlib import Path
+
+from fastapi import APIRouter
+
+from openhands.sdk.git.git_changes import get_git_changes
+from openhands.sdk.git.git_diff import get_git_diff
+from openhands.sdk.git.models import GitChange, GitDiff
+
+
+git_router = APIRouter(prefix="/git", tags=["Git"])
+logger = logging.getLogger(__name__)
+
+
+@git_router.get("/changes/{path:path}")
+async def git_changes(
+    path: Path,
+) -> list[GitChange]:
+    loop = asyncio.get_running_loop()
+    changes = await loop.run_in_executor(None, get_git_changes, path)
+    return changes
+
+
+# bash event routes
+@git_router.get("/diff/{path:path}")
+async def git_diff(
+    path: Path,
+) -> GitDiff:
+    loop = asyncio.get_running_loop()
+    changes = await loop.run_in_executor(None, get_git_diff, path)
+    return changes

openhands/agent_server/logging_config.py

@@ -0,0 +1,56 @@
+"""Custom logging configuration for uvicorn to reuse the SDK's root logger."""
+
+import logging
+from typing import Any
+
+from openhands.sdk.logger import ENV_LOG_LEVEL
+
+
+def get_uvicorn_logging_config() -> dict[str, Any]:
+    """
+    Generate uvicorn logging configuration that integrates with SDK's root logger.
+
+    This function creates a logging configuration that:
+    1. Preserves the SDK's root logger configuration
+    2. Routes uvicorn logs through the same handlers
+    3. Keeps access logs separate for better formatting
+    4. Supports both Rich and JSON output based on SDK settings
+    """
+    # Base configuration
+    # Note: We cannot use incremental=True with partial handler definitions
+    # So we set it to False but configure loggers to propagate to root
+    config = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "incremental": False,  # Cannot be True when defining new handlers
+        "formatters": {},
+        "handlers": {},
+        "loggers": {},
+    }
+
+    # Configure uvicorn loggers
+    config["loggers"] = {
+        # Main uvicorn logger - propagate to root
+        "uvicorn": {
+            "handlers": [],  # Use root's handlers via propagation
+            "level": logging.getLevelName(ENV_LOG_LEVEL),
+            "propagate": True,
+        },
+        # Error logger - propagate to root for stack traces
+        "uvicorn.error": {
+            "handlers": [],  # Use root's handlers via propagation
+            "level": logging.getLevelName(ENV_LOG_LEVEL),
+            "propagate": True,
+        },
+        # Access logger - propagate to root
+        "uvicorn.access": {
+            "handlers": [],
+            "level": logging.getLevelName(ENV_LOG_LEVEL),
+            "propagate": True,
+        },
+    }
+
+    return config
+
+
+LOGGING_CONFIG = get_uvicorn_logging_config()

openhands/agent_server/middleware.py

@@ -0,0 +1,32 @@
+from urllib.parse import urlparse
+
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.types import ASGIApp
+
+
+class LocalhostCORSMiddleware(CORSMiddleware):
+    """Custom CORS middleware that allows any request from localhost/127.0.0.1 domains,
+    while using standard CORS rules for other origins.
+    """
+
+    def __init__(self, app: ASGIApp, allow_origins: list[str]) -> None:
+        super().__init__(
+            app,
+            allow_origins=allow_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    def is_allowed_origin(self, origin: str) -> bool:
+        if origin and not self.allow_origins and not self.allow_origin_regex:
+            parsed = urlparse(origin)
+            hostname = parsed.hostname or ""
+
+            # Allow any localhost/127.0.0.1 origin regardless of port
+            if hostname in ["localhost", "127.0.0.1"]:
+                return True
+
+        # For missing origin or other origins, use the parent class's logic
+        result: bool = super().is_allowed_origin(origin)
+        return result

openhands/agent_server/models.py

@@ -0,0 +1,307 @@
+from abc import ABC
+from datetime import datetime
+from enum import Enum
+from typing import Any, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, field_validator
+
+from openhands.agent_server.utils import OpenHandsUUID, utc_now
+from openhands.sdk import LLM, AgentBase, Event, ImageContent, Message, TextContent
+from openhands.sdk.conversation.state import (
+    ConversationExecutionStatus,
+    ConversationState,
+)
+from openhands.sdk.llm.utils.metrics import MetricsSnapshot
+from openhands.sdk.secret import SecretSource
+from openhands.sdk.security.analyzer import SecurityAnalyzerBase
+from openhands.sdk.security.confirmation_policy import (
+    ConfirmationPolicyBase,
+    NeverConfirm,
+)
+from openhands.sdk.utils.models import DiscriminatedUnionMixin, OpenHandsModel
+from openhands.sdk.workspace import LocalWorkspace
+
+
+class ConversationSortOrder(str, Enum):
+    """Enum for conversation sorting options."""
+
+    CREATED_AT = "CREATED_AT"
+    UPDATED_AT = "UPDATED_AT"
+    CREATED_AT_DESC = "CREATED_AT_DESC"
+    UPDATED_AT_DESC = "UPDATED_AT_DESC"
+
+
+class EventSortOrder(str, Enum):
+    """Enum for event sorting options."""
+
+    TIMESTAMP = "TIMESTAMP"
+    TIMESTAMP_DESC = "TIMESTAMP_DESC"
+
+
+class SendMessageRequest(BaseModel):
+    """Payload to send a message to the agent.
+
+    This is a simplified version of openhands.sdk.Message.
+    """
+
+    role: Literal["user", "system", "assistant", "tool"] = "user"
+    content: list[TextContent | ImageContent] = Field(default_factory=list)
+    run: bool = Field(
+        default=False,
+        description=("Whether the agent loop should automatically run if not running"),
+    )
+
+    def create_message(self) -> Message:
+        message = Message(role=self.role, content=self.content)
+        return message
+
+
+class StartConversationRequest(BaseModel):
+    """Payload to create a new conversation.
+
+    Contains an Agent configuration along with conversation-specific options.
+    """
+
+    agent: AgentBase
+    workspace: LocalWorkspace = Field(
+        ...,
+        description="Working directory for agent operations and tool execution",
+    )
+    conversation_id: OpenHandsUUID | None = Field(
+        default=None,
+        description=(
+            "Optional conversation ID. If not provided, a random UUID will be "
+            "generated."
+        ),
+    )
+    confirmation_policy: ConfirmationPolicyBase = Field(
+        default=NeverConfirm(),
+        description="Controls when the conversation will prompt the user before "
+        "continuing. Defaults to never.",
+    )
+    initial_message: SendMessageRequest | None = Field(
+        default=None, description="Initial message to pass to the LLM"
+    )
+    max_iterations: int = Field(
+        default=500,
+        ge=1,
+        description="If set, the max number of iterations the agent will run "
+        "before stopping. This is useful to prevent infinite loops.",
+    )
+    stuck_detection: bool = Field(
+        default=True,
+        description="If true, the conversation will use stuck detection to "
+        "prevent infinite loops.",
+    )
+    secrets: dict[str, SecretSource] = Field(
+        default_factory=dict,
+        description="Secrets available in the conversation",
+    )
+    tool_module_qualnames: dict[str, str] = Field(
+        default_factory=dict,
+        description=(
+            "Mapping of tool names to their module qualnames from the client's "
+            "registry. These modules will be dynamically imported on the server "
+            "to register the tools for this conversation."
+        ),
+    )
+
+
+class StoredConversation(StartConversationRequest):
+    """Stored details about a conversation"""
+
+    id: OpenHandsUUID
+    title: str | None = Field(
+        default=None, description="User-defined title for the conversation"
+    )
+    metrics: MetricsSnapshot | None = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+
+
+class ConversationInfo(ConversationState):
+    """Information about a conversation running locally without a Runtime sandbox."""
+
+    # ConversationState already includes id and agent
+    # Add additional metadata fields
+
+    title: str | None = Field(
+        default=None, description="User-defined title for the conversation"
+    )
+    metrics: MetricsSnapshot | None = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+
+
+class ConversationPage(BaseModel):
+    items: list[ConversationInfo]
+    next_page_id: str | None = None
+
+
+class ConversationResponse(BaseModel):
+    conversation_id: str
+    state: ConversationExecutionStatus
+
+
+class ConfirmationResponseRequest(BaseModel):
+    """Payload to accept or reject a pending action."""
+
+    accept: bool
+    reason: str = "User rejected the action."
+
+
+class Success(BaseModel):
+    success: bool = True
+
+
+class EventPage(OpenHandsModel):
+    items: list[Event]
+    next_page_id: str | None = None
+
+
+class UpdateSecretsRequest(BaseModel):
+    """Payload to update secrets in a conversation."""
+
+    secrets: dict[str, SecretSource] = Field(
+        description="Dictionary mapping secret keys to values"
+    )
+
+    @field_validator("secrets", mode="before")
+    @classmethod
+    def convert_string_secrets(cls, v: dict[str, Any]) -> dict[str, Any]:
+        """Convert plain string secrets to StaticSecret objects.
+
+        This validator enables backward compatibility by automatically converting:
+        - Plain strings: "secret-value" → StaticSecret(value=SecretStr("secret-value"))
+        - Dict with value field: {"value": "secret-value"} → StaticSecret dict format
+        - Proper SecretSource objects: passed through unchanged
+        """
+        if not isinstance(v, dict):
+            return v
+
+        converted = {}
+        for key, value in v.items():
+            if isinstance(value, str):
+                # Convert plain string to StaticSecret dict format
+                converted[key] = {
+                    "kind": "StaticSecret",
+                    "value": value,
+                }
+            elif isinstance(value, dict):
+                if "value" in value and "kind" not in value:
+                    # Convert dict with value field to StaticSecret dict format
+                    converted[key] = {
+                        "kind": "StaticSecret",
+                        "value": value["value"],
+                    }
+                else:
+                    # Keep existing SecretSource objects or properly formatted dicts
+                    converted[key] = value
+            else:
+                # Keep other types as-is (will likely fail validation later)
+                converted[key] = value
+
+        return converted
+
+
+class SetConfirmationPolicyRequest(BaseModel):
+    """Payload to set confirmation policy for a conversation."""
+
+    policy: ConfirmationPolicyBase = Field(description="The confirmation policy to set")
+
+
+class SetSecurityAnalyzerRequest(BaseModel):
+    "Payload to set security analyzer for a conversation"
+
+    security_analyzer: SecurityAnalyzerBase | None = Field(
+        description="The security analyzer to set"
+    )
+
+
+class UpdateConversationRequest(BaseModel):
+    """Payload to update conversation metadata."""
+
+    title: str = Field(
+        ..., min_length=1, max_length=200, description="New conversation title"
+    )
+
+
+class GenerateTitleRequest(BaseModel):
+    """Payload to generate a title for a conversation."""
+
+    max_length: int = Field(
+        default=50, ge=1, le=200, description="Maximum length of the generated title"
+    )
+    llm: LLM | None = Field(
+        default=None, description="Optional LLM to use for title generation"
+    )
+
+
+class GenerateTitleResponse(BaseModel):
+    """Response containing the generated conversation title."""
+
+    title: str = Field(description="The generated title for the conversation")
+
+
+class AskAgentRequest(BaseModel):
+    """Payload to ask the agent a simple question."""
+
+    question: str = Field(description="The question to ask the agent")
+
+
+class AskAgentResponse(BaseModel):
+    """Response containing the agent's answer."""
+
+    response: str = Field(description="The agent's response to the question")
+
+
+class BashEventBase(DiscriminatedUnionMixin, ABC):
+    """Base class for all bash event types"""
+
+    id: OpenHandsUUID = Field(default_factory=uuid4)
+    timestamp: datetime = Field(default_factory=utc_now)
+
+
+class ExecuteBashRequest(BaseModel):
+    command: str = Field(description="The bash command to execute")
+    cwd: str | None = Field(default=None, description="The current working directory")
+    timeout: int = Field(
+        default=300,
+        description="The max number of seconds a command may be permitted to run.",
+    )
+
+
+class BashCommand(BashEventBase, ExecuteBashRequest):
+    pass
+
+
+class BashOutput(BashEventBase):
+    """
+    Output of a bash command. A single command may have multiple pieces of output
+    depending on how large the output is.
+    """
+
+    command_id: OpenHandsUUID
+    order: int = Field(
+        default=0, description="The order for this output, sequentially starting with 0"
+    )
+    exit_code: int | None = Field(
+        default=None, description="Exit code None implies the command is still running."
+    )
+    stdout: str | None = Field(
+        default=None, description="The standard output from the command"
+    )
+    stderr: str | None = Field(
+        default=None, description="The error output from the command"
+    )
+
+
+class BashEventSortOrder(Enum):
+    TIMESTAMP = "TIMESTAMP"
+    TIMESTAMP_DESC = "TIMESTAMP_DESC"
+
+
+class BashEventPage(OpenHandsModel):
+    items: list[BashEventBase]
+    next_page_id: str | None = None

openhands/agent_server/openapi.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from openhands.agent_server.api import api
+
+
+def generate_openapi_schema() -> dict[str, Any]:
+    """Generate an OpenAPI schema"""
+    openapi = api.openapi()
+    return openapi
+
+
+if __name__ == "__main__":
+    schema_path = Path(os.environ["SCHEMA_PATH"])
+    schema = generate_openapi_schema()
+    schema_path.write_text(json.dumps(schema, indent=2))
+    print(f"Wrote {schema_path}")

openhands/agent_server/pub_sub.py

@@ -0,0 +1,80 @@
+import asyncio
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TypeVar
+from uuid import UUID, uuid4
+
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+
+class Subscriber[T](ABC):
+    @abstractmethod
+    async def __call__(self, event: T):
+        """Invoke this subscriber"""
+
+    async def close(self):
+        """Clean up this subscriber"""
+
+
+@dataclass
+class PubSub[T]:
+    """A subscription service that extends ConversationCallbackType functionality.
+    This class maintains a dictionary of UUIDs to ConversationCallbackType instances
+    and provides methods to subscribe/unsubscribe callbacks. When invoked, it calls
+    all registered callbacks with proper error handling.
+    """
+
+    _subscribers: dict[UUID, Subscriber[T]] = field(default_factory=dict)
+
+    def subscribe(self, subscriber: Subscriber[T]) -> UUID:
+        """Subscribe a subscriber and return its UUID for later unsubscription.
+        Args:
+            subscriber: The callback function to register
+        Returns:
+            UUID: UUID that can be used to unsubscribe this callback
+        """
+        subscriber_id = uuid4()
+        self._subscribers[subscriber_id] = subscriber
+        logger.debug(f"Subscribed subscriber with ID: {subscriber_id}")
+        return subscriber_id
+
+    def unsubscribe(self, subscriber_id: UUID) -> bool:
+        """Unsubscribe a subscriber by its UUID.
+        Args:
+            subscriber_id: The UUID returned by subscribe()
+        Returns:
+            bool: True if subscriber was found and removed, False otherwise
+        """
+        if subscriber_id in self._subscribers:
+            del self._subscribers[subscriber_id]
+            logger.debug(f"Unsubscribed subscriber with ID: {subscriber_id}")
+            return True
+        else:
+            logger.warning(
+                f"Attempted to unsubscribe unknown subscriber ID: {subscriber_id}"
+            )
+            return False
+
+    async def __call__(self, event: T) -> None:
+        """Invoke all registered callbacks with the given event.
+        Each callback is invoked in its own try/catch block to prevent
+        one failing callback from affecting others.
+        Args:
+            event: The event to pass to all callbacks
+        """
+        for subscriber_id, subscriber in list(self._subscribers.items()):
+            try:
+                await subscriber(event)
+            except Exception as e:
+                logger.error(f"Error in subscriber {subscriber_id}: {e}", exc_info=True)
+
+    async def close(self):
+        await asyncio.gather(
+            *[subscriber.close() for subscriber in self._subscribers.values()]
+        )
+        self._subscribers.clear()

openhands/agent_server/server_details_router.py

@@ -0,0 +1,43 @@
+import time
+from importlib.metadata import version
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+
+server_details_router = APIRouter(prefix="", tags=["Server Details"])
+_start_time = time.time()
+_last_event_time = time.time()
+
+
+class ServerInfo(BaseModel):
+    uptime: float
+    idle_time: float
+    title: str = "OpenHands Agent Server"
+    version: str = version("openhands-agent-server")
+    docs: str = "/docs"
+    redoc: str = "/redoc"
+
+
+def update_last_execution_time():
+    global _last_event_time
+    _last_event_time = time.time()
+
+
+@server_details_router.get("/alive")
+async def alive():
+    return {"status": "ok"}
+
+
+@server_details_router.get("/health")
+async def health() -> str:
+    return "OK"
+
+
+@server_details_router.get("/server_info")
+async def get_server_info() -> ServerInfo:
+    now = time.time()
+    return ServerInfo(
+        uptime=int(now - _start_time),
+        idle_time=int(now - _last_event_time),
+    )