openhands-agent-server 1.8.2__tar.gz

openhands_agent_server-1.8.2/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: openhands-agent-server
+Version: 1.8.2
+Summary: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.19
+Requires-Dist: alembic>=1.13
+Requires-Dist: docker<8,>=7.1
+Requires-Dist: fastapi>=0.104
+Requires-Dist: openhands-sdk
+Requires-Dist: pydantic>=2
+Requires-Dist: sqlalchemy>=2
+Requires-Dist: uvicorn>=0.31.1
+Requires-Dist: websockets>=12
+Requires-Dist: wsproto>=1.2.0

openhands_agent_server-1.8.2/openhands/agent_server/__main__.py

@@ -0,0 +1,118 @@
+import argparse
+import atexit
+import faulthandler
+import signal
+from types import FrameType
+
+import uvicorn
+from uvicorn import Config
+
+from openhands.agent_server.logging_config import LOGGING_CONFIG
+from openhands.sdk.logger import DEBUG, get_logger
+
+
+logger = get_logger(__name__)
+
+
+class LoggingServer(uvicorn.Server):
+    """Custom uvicorn Server that logs signal handling events.
+
+    This subclass overrides handle_exit to add structured logging when
+    termination signals are received, ensuring visibility into why the
+    server is shutting down.
+    """
+
+    def handle_exit(self, sig: int, frame: FrameType | None) -> None:
+        """Handle exit signals with logging before delegating to parent."""
+        sig_name = signal.Signals(sig).name
+        logger.info(
+            "Received signal %s (%d), shutting down...",
+            sig_name,
+            sig,
+        )
+        super().handle_exit(sig, frame)
+
+
+def _setup_crash_diagnostics() -> None:
+    """Enable crash diagnostics for debugging unexpected terminations.
+
+    Note: faulthandler outputs tracebacks to stderr in plain text format,
+    not through the structured JSON logger. This is unavoidable because
+    during a segfault, Python's normal logging infrastructure is not
+    available. The plain text traceback is still valuable for debugging.
+    """
+    faulthandler.enable()
+
+    # Register atexit handler to log normal exits
+    @atexit.register
+    def _log_exit() -> None:
+        logger.info("Process exiting via atexit handler")
+
+
+def main() -> None:
+    # Set up crash diagnostics early, before any other initialization
+    _setup_crash_diagnostics()
+
+    parser = argparse.ArgumentParser(description="OpenHands Agent Server App")
+    parser.add_argument(
+        "--host", default="0.0.0.0", help="Host to bind to (default: 0.0.0.0)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=8000, help="Port to bind to (default: 8000)"
+    )
+    parser.add_argument(
+        "--reload",
+        dest="reload",
+        default=False,
+        action="store_true",
+        help="Enable auto-reload (disabled by default)",
+    )
+
+    args = parser.parse_args()
+
+    print(f"🙌 Starting OpenHands Agent Server on {args.host}:{args.port}")
+    print(f"📖 API docs will be available at http://{args.host}:{args.port}/docs")
+    print(f"🔄 Auto-reload: {'enabled' if args.reload else 'disabled'}")
+
+    # Show debug mode status
+    if DEBUG:
+        print("🐛 DEBUG mode: ENABLED (stack traces will be shown)")
+    else:
+        print("🔒 DEBUG mode: DISABLED")
+    print()
+
+    # Configure uvicorn logging based on DEBUG environment variable
+    log_level = "debug" if DEBUG else "info"
+
+    # Create uvicorn config
+    config = Config(
+        "openhands.agent_server.api:api",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+        reload_includes=[
+            "openhands-agent-server",
+            "openhands-sdk",
+            "openhands-tools",
+        ],
+        log_level=log_level,
+        log_config=LOGGING_CONFIG,
+        ws="wsproto",  # Use wsproto instead of deprecated websockets implementation
+    )
+
+    # Use custom LoggingServer to capture signal handling events
+    server = LoggingServer(config)
+
+    try:
+        server.run()
+    except Exception:
+        logger.error("Server crashed with unexpected exception", exc_info=True)
+        raise
+    except BaseException as e:
+        # Catch SystemExit, KeyboardInterrupt, etc. - these are normal termination paths
+        logger.info("Server terminated: %s: %s", type(e).__name__, e)
+        raise
+
+
+if __name__ == "__main__":
+    main()

openhands_agent_server-1.8.2/openhands/agent_server/api.py

@@ -0,0 +1,331 @@
+import asyncio
+import traceback
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import APIRouter, Depends, FastAPI, HTTPException
+from fastapi.responses import JSONResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.requests import Request
+
+from openhands.agent_server.bash_router import bash_router
+from openhands.agent_server.config import (
+    Config,
+    get_default_config,
+)
+from openhands.agent_server.conversation_router import conversation_router
+from openhands.agent_server.conversation_service import (
+    get_default_conversation_service,
+)
+from openhands.agent_server.dependencies import create_session_api_key_dependency
+from openhands.agent_server.desktop_router import desktop_router
+from openhands.agent_server.desktop_service import get_desktop_service
+from openhands.agent_server.event_router import event_router
+from openhands.agent_server.file_router import file_router
+from openhands.agent_server.git_router import git_router
+from openhands.agent_server.middleware import LocalhostCORSMiddleware
+from openhands.agent_server.server_details_router import (
+    get_server_info,
+    server_details_router,
+)
+from openhands.agent_server.sockets import sockets_router
+from openhands.agent_server.tool_preload_service import get_tool_preload_service
+from openhands.agent_server.tool_router import tool_router
+from openhands.agent_server.vscode_router import vscode_router
+from openhands.agent_server.vscode_service import get_vscode_service
+from openhands.sdk.logger import DEBUG, get_logger
+
+
+logger = get_logger(__name__)
+
+
+@asynccontextmanager
+async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
+    service = get_default_conversation_service()
+    vscode_service = get_vscode_service()
+    desktop_service = get_desktop_service()
+    tool_preload_service = get_tool_preload_service()
+
+    # Define async functions for starting each service
+    async def start_vscode_service():
+        if vscode_service is not None:
+            vscode_started = await vscode_service.start()
+            if vscode_started:
+                logger.info("VSCode service started successfully")
+            else:
+                logger.warning(
+                    "VSCode service failed to start, continuing without VSCode"
+                )
+        else:
+            logger.info("VSCode service is disabled")
+
+    async def start_desktop_service():
+        if desktop_service is not None:
+            desktop_started = await desktop_service.start()
+            if desktop_started:
+                logger.info("Desktop service started successfully")
+            else:
+                logger.warning(
+                    "Desktop service failed to start, continuing without desktop"
+                )
+        else:
+            logger.info("Desktop service is disabled")
+
+    async def start_tool_preload_service():
+        if tool_preload_service is not None:
+            tool_preload_started = await tool_preload_service.start()
+            if tool_preload_started:
+                logger.info("Tool preload service started successfully")
+            else:
+                logger.warning("Tool preload service failed to start - skipping")
+        else:
+            logger.info("Tool preload service is disabled")
+
+    # Start all services concurrently
+    await asyncio.gather(
+        start_vscode_service(),
+        start_desktop_service(),
+        start_tool_preload_service(),
+        return_exceptions=True,
+    )
+
+    async with service:
+        # Store the initialized service in app state for dependency injection
+        api.state.conversation_service = service
+        try:
+            yield
+        finally:
+            # Define async functions for stopping each service
+            async def stop_vscode_service():
+                if vscode_service is not None:
+                    await vscode_service.stop()
+
+            async def stop_desktop_service():
+                if desktop_service is not None:
+                    await desktop_service.stop()
+
+            async def stop_tool_preload_service():
+                if tool_preload_service is not None:
+                    await tool_preload_service.stop()
+
+            # Stop all services concurrently
+            await asyncio.gather(
+                stop_vscode_service(),
+                stop_desktop_service(),
+                stop_tool_preload_service(),
+                return_exceptions=True,
+            )
+
+
+def _create_fastapi_instance() -> FastAPI:
+    """Create the basic FastAPI application instance.
+
+    Returns:
+        Basic FastAPI application with title, description, and lifespan.
+    """
+    return FastAPI(
+        title="OpenHands Agent Server",
+        description=(
+            "OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent"
+        ),
+        lifespan=api_lifespan,
+    )
+
+
+def _find_http_exception(exc: BaseExceptionGroup) -> HTTPException | None:
+    """Helper function to find HTTPException in ExceptionGroup.
+
+    Args:
+        exc: BaseExceptionGroup to search for HTTPException.
+
+    Returns:
+        HTTPException if found, None otherwise.
+    """
+    for inner_exc in exc.exceptions:
+        if isinstance(inner_exc, HTTPException):
+            return inner_exc
+        # Recursively search nested ExceptionGroups
+        if isinstance(inner_exc, BaseExceptionGroup):
+            found = _find_http_exception(inner_exc)
+            if found:
+                return found
+    return None
+
+
+def _add_api_routes(app: FastAPI, config: Config) -> None:
+    """Add all API routes to the FastAPI application.
+
+    Args:
+        app: FastAPI application instance to add routes to.
+    """
+    app.include_router(server_details_router)
+
+    dependencies = []
+    if config.session_api_keys:
+        dependencies.append(Depends(create_session_api_key_dependency(config)))
+
+    api_router = APIRouter(prefix="/api", dependencies=dependencies)
+    api_router.include_router(event_router)
+    api_router.include_router(conversation_router)
+    api_router.include_router(tool_router)
+    api_router.include_router(bash_router)
+    api_router.include_router(git_router)
+    api_router.include_router(file_router)
+    api_router.include_router(vscode_router)
+    api_router.include_router(desktop_router)
+    app.include_router(api_router)
+    app.include_router(sockets_router)
+
+
+def _setup_static_files(app: FastAPI, config: Config) -> None:
+    """Set up static file serving and root redirect if configured.
+
+    Args:
+        app: FastAPI application instance.
+        config: Configuration object containing static files settings.
+    """
+    # Only proceed if static files are configured and directory exists
+    if not (
+        config.static_files_path
+        and config.static_files_path.exists()
+        and config.static_files_path.is_dir()
+    ):
+        # Map the root path to server info if there are no static files
+        app.get("/")(get_server_info)
+        return
+
+    # Mount static files directory
+    app.mount(
+        "/static",
+        StaticFiles(directory=str(config.static_files_path)),
+        name="static",
+    )
+
+    # Add root redirect to static files
+    @app.get("/", tags=["Server Details"])
+    async def root_redirect():
+        """Redirect root endpoint to static files directory."""
+        # Check if index.html exists in the static directory
+        # We know static_files_path is not None here due to the outer condition
+        assert config.static_files_path is not None
+        index_path = config.static_files_path / "index.html"
+        if index_path.exists():
+            return RedirectResponse(url="/static/index.html", status_code=302)
+        else:
+            return RedirectResponse(url="/static/", status_code=302)
+
+
+def _add_exception_handlers(api: FastAPI) -> None:
+    """Add exception handlers to the FastAPI application."""
+
+    @api.exception_handler(Exception)
+    async def _unhandled_exception_handler(
+        request: Request, exc: Exception
+    ) -> JSONResponse:
+        """Handle unhandled exceptions."""
+        # Always log that we're in the exception handler for debugging
+        logger.debug(
+            "Exception handler called for %s %s with %s: %s",
+            request.method,
+            request.url.path,
+            type(exc).__name__,
+            str(exc),
+        )
+
+        content = {
+            "detail": "Internal Server Error",
+            "exception": str(exc),
+        }
+        # In DEBUG mode, include stack trace in response
+        if DEBUG:
+            content["traceback"] = traceback.format_exc()
+        # Check if this is an HTTPException that should be handled directly
+        if isinstance(exc, HTTPException):
+            return await _http_exception_handler(request, exc)
+
+        # Check if this is a BaseExceptionGroup with HTTPExceptions
+        if isinstance(exc, BaseExceptionGroup):
+            http_exc = _find_http_exception(exc)
+            if http_exc:
+                return await _http_exception_handler(request, http_exc)
+            # If no HTTPException found, treat as unhandled exception
+            logger.error(
+                "Unhandled ExceptionGroup on %s %s",
+                request.method,
+                request.url.path,
+                exc_info=(type(exc), exc, exc.__traceback__),
+            )
+            return JSONResponse(status_code=500, content=content)
+
+        # Logs full stack trace for any unhandled error that FastAPI would
+        # turn into a 500
+        logger.error(
+            "Unhandled exception on %s %s",
+            request.method,
+            request.url.path,
+            exc_info=(type(exc), exc, exc.__traceback__),
+        )
+        return JSONResponse(status_code=500, content=content)
+
+    @api.exception_handler(HTTPException)
+    async def _http_exception_handler(
+        request: Request, exc: HTTPException
+    ) -> JSONResponse:
+        """Handle HTTPExceptions with appropriate logging."""
+        # Log 4xx errors at info level (expected client errors like auth failures)
+        if 400 <= exc.status_code < 500:
+            logger.info(
+                "HTTPException %d on %s %s: %s",
+                exc.status_code,
+                request.method,
+                request.url.path,
+                exc.detail,
+            )
+        # Log 5xx errors at error level with full traceback (server errors)
+        elif exc.status_code >= 500:
+            logger.error(
+                "HTTPException %d on %s %s: %s",
+                exc.status_code,
+                request.method,
+                request.url.path,
+                exc.detail,
+                exc_info=(type(exc), exc, exc.__traceback__),
+            )
+            content = {
+                "detail": "Internal Server Error",
+                "exception": str(exc),
+            }
+            if DEBUG:
+                content["traceback"] = traceback.format_exc()
+            # Don't leak internal details to clients for 5xx errors in production
+            return JSONResponse(
+                status_code=exc.status_code,
+                content=content,
+            )
+
+        # Return clean JSON response for all non-5xx HTTP exceptions
+        return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+
+def create_app(config: Config | None = None) -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Args:
+        config: Configuration object. If None, uses default config.
+
+    Returns:
+        Configured FastAPI application.
+    """
+    if config is None:
+        config = get_default_config()
+    app = _create_fastapi_instance()
+    _add_api_routes(app, config)
+    _setup_static_files(app, config)
+    app.add_middleware(LocalhostCORSMiddleware, allow_origins=config.allow_cors_origins)
+    _add_exception_handlers(app)
+
+    return app
+
+
+# Create the default app instance
+api = create_app()

openhands_agent_server-1.8.2/openhands/agent_server/bash_router.py

@@ -0,0 +1,105 @@
+"""Bash router for OpenHands SDK."""
+
+import logging
+from datetime import datetime
+from typing import Annotated, Literal, cast
+from uuid import UUID
+
+from fastapi import (
+    APIRouter,
+    HTTPException,
+    Query,
+    status,
+)
+
+from openhands.agent_server.bash_service import get_default_bash_event_service
+from openhands.agent_server.models import (
+    BashCommand,
+    BashEventBase,
+    BashEventPage,
+    BashEventSortOrder,
+    BashOutput,
+    ExecuteBashRequest,
+)
+
+
+bash_router = APIRouter(prefix="/bash", tags=["Bash"])
+bash_event_service = get_default_bash_event_service()
+logger = logging.getLogger(__name__)
+
+
+# bash event routes
+@bash_router.get("/bash_events/search")
+async def search_bash_events(
+    kind__eq: Literal["BashCommand", "BashOutput"] | None = None,
+    command_id__eq: UUID | None = None,
+    timestamp__gte: datetime | None = None,
+    timestamp__lt: datetime | None = None,
+    sort_order: BashEventSortOrder = BashEventSortOrder.TIMESTAMP,
+    page_id: Annotated[
+        str | None,
+        Query(title="Optional next_page_id from the previously returned page"),
+    ] = None,
+    limit: Annotated[
+        int,
+        Query(title="The max number of results in the page", gt=0, lte=100),
+    ] = 100,
+) -> BashEventPage:
+    """Search / List bash event events"""
+    assert limit > 0
+    assert limit <= 100
+
+    return await bash_event_service.search_bash_events(
+        kind__eq=kind__eq,
+        command_id__eq=command_id__eq,
+        timestamp__gte=timestamp__gte,
+        timestamp__lt=timestamp__lt,
+        sort_order=sort_order,
+        page_id=page_id,
+        limit=limit,
+    )
+
+
+@bash_router.get(
+    "/bash_events/{event_id}", responses={404: {"description": "Item not found"}}
+)
+async def get_bash_event(event_id: str) -> BashEventBase:
+    """Get a bash event event given an id"""
+    event = await bash_event_service.get_bash_event(event_id)
+    if event is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND)
+    return event
+
+
+@bash_router.get("/bash_events/")
+async def batch_get_bash_events(
+    event_ids: list[str],
+) -> list[BashEventBase | None]:
+    """Get a batch of bash event events given their ids, returning null for any
+    missing item."""
+    events = await bash_event_service.batch_get_bash_events(event_ids)
+    return events
+
+
+@bash_router.post("/start_bash_command")
+async def start_bash_command(request: ExecuteBashRequest) -> BashCommand:
+    """Execute a bash command in the background"""
+    command, _ = await bash_event_service.start_bash_command(request)
+    return command
+
+
+@bash_router.post("/execute_bash_command")
+async def execute_bash_command(request: ExecuteBashRequest) -> BashOutput:
+    """Execute a bash command and wait for a result"""
+    command, task = await bash_event_service.start_bash_command(request)
+    await task
+    page = await bash_event_service.search_bash_events(command_id__eq=command.id)
+    result = cast(BashOutput, page.items[-1])
+    return result
+
+
+@bash_router.delete("/bash_events")
+async def clear_all_bash_events() -> dict[str, int]:
+    """Clear all bash events from storage"""
+    count = await bash_event_service.clear_all_events()
+    return {"cleared_count": count}