openhands-agent-server 1.8.1__tar.gz → 1.9.0__tar.gz

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/PKG-INFO

@@ -1,7 +1,11 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.8.1
+Version: 1.9.0
 Summary: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
+Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
+Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk
+Project-URL: Documentation, https://docs.openhands.dev/sdk
+Project-URL: Bug Tracker, https://github.com/OpenHands/software-agent-sdk/issues
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.19
 Requires-Dist: alembic>=1.13

openhands_agent_server-1.9.0/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.1 → openhands_agent_server-1.9.0}/openhands/agent_server/api.py

@@ -28,6 +28,7 @@ from openhands.agent_server.server_details_router import (
     get_server_info,
     server_details_router,
 )
+from openhands.agent_server.skills_router import skills_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
@@ -173,6 +174,7 @@ def _add_api_routes(app: FastAPI, config: Config) -> None:
     api_router.include_router(file_router)
     api_router.include_router(vscode_router)
     api_router.include_router(desktop_router)
+    api_router.include_router(skills_router)
     app.include_router(api_router)
     app.include_router(sockets_router)
 

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/openhands/agent_server/bash_router.py

@@ -21,6 +21,7 @@ from openhands.agent_server.models import (
     BashOutput,
     ExecuteBashRequest,
 )
+from openhands.agent_server.server_details_router import update_last_execution_time
 
 
 bash_router = APIRouter(prefix="/bash", tags=["Bash"])
@@ -84,6 +85,7 @@ async def batch_get_bash_events(
 @bash_router.post("/start_bash_command")
 async def start_bash_command(request: ExecuteBashRequest) -> BashCommand:
     """Execute a bash command in the background"""
+    update_last_execution_time()
     command, _ = await bash_event_service.start_bash_command(request)
     return command
 
@@ -91,6 +93,7 @@ async def start_bash_command(request: ExecuteBashRequest) -> BashCommand:
 @bash_router.post("/execute_bash_command")
 async def execute_bash_command(request: ExecuteBashRequest) -> BashOutput:
     """Execute a bash command and wait for a result"""
+    update_last_execution_time()
     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)

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/openhands/agent_server/config.py

@@ -10,22 +10,37 @@ from openhands.sdk.utils.cipher import Cipher
 
 
 # Environment variable constants
-SESSION_API_KEY_ENV = "SESSION_API_KEY"
+V0_SESSION_API_KEY_ENV = "SESSION_API_KEY"
+V1_SESSION_API_KEY_ENV = "OH_SESSION_API_KEYS_0"
 ENVIRONMENT_VARIABLE_PREFIX = "OH"
 _logger = logging.getLogger(__name__)
 
 
 def _default_session_api_keys():
-    # Legacy fallback for compability with old runtime API
+    """
+    This function exists as a fallback to using this old V0 environment
+    variable. If new V1_SESSION_API_KEYS_0 environment variable exists,
+    it is read automatically by the EnvParser and this function is never
+    called.
+    """
     result = []
-    session_api_key = os.getenv(SESSION_API_KEY_ENV)
+    session_api_key = os.getenv(V0_SESSION_API_KEY_ENV)
     if session_api_key:
         result.append(session_api_key)
     return result
 
 
 def _default_secret_key() -> SecretStr | None:
-    session_api_key = os.getenv(SESSION_API_KEY_ENV)
+    """
+    If the OH_SECRET_KEY environment variable is present, it is read by the EnvParser
+    and this function is never called. Otherwise, we fall back to using the first
+    available session_api_key - which we read from the environment.
+    We check both the V0 and V1 variables for this.
+    """
+    session_api_key = os.getenv(V0_SESSION_API_KEY_ENV)
+    if session_api_key:
+        return SecretStr(session_api_key)
+    session_api_key = os.getenv(V1_SESSION_API_KEY_ENV)
     if session_api_key:
         return SecretStr(session_api_key)
     return None
@@ -77,7 +92,10 @@ class Config(BaseModel):
         description=(
             "List of valid session API keys used to authenticate incoming requests. "
             "Empty list implies the server will be unsecured. Any key in this list "
-            "will be accepted for authentication."
+            "will be accepted for authentication. Multiple keys are supported to "
+            "enable key rotation without service disruption - new keys can be added "
+            "to the list, then clients are updated with the new key, and finally the "
+            "old key is removed from the list. "
         ),
     )
     allow_cors_origins: list[str] = Field(

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/openhands/agent_server/docker/Dockerfile

@@ -91,6 +91,7 @@ EXPOSE ${PORT}
 # It includes additional Docker, VNC, Desktop, and VSCode Web.
 ####################################################################################
 FROM base-image-minimal AS base-image
+ARG USERNAME
 
 USER root
 # --- VSCode Web ---

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/openhands/agent_server/docker/build.py

@@ -204,6 +204,32 @@ def _sanitize_branch(ref: str) -> str:
     return re.sub(r"[^a-zA-Z0-9.-]+", "-", ref).lower()
 
 
+def _truncate_ident(repo: str, tag: str, budget: int) -> str:
+    """
+    Truncate repo+tag to fit budget, prioritizing tag preservation.
+
+    Strategy:
+    1. If both fit: return both
+    2. If tag fits but repo doesn't: truncate repo, keep full tag
+    3. If tag doesn't fit: truncate tag, discard repo
+    4. If no tag: truncate repo
+    """
+    tag_suffix = f"_tag_{tag}" if tag else ""
+    full_ident = repo + tag_suffix
+
+    if len(full_ident) <= budget:
+        return full_ident
+
+    if not tag:
+        return repo[:budget]
+
+    if len(tag_suffix) <= budget:
+        repo_budget = budget - len(tag_suffix)
+        return repo[:repo_budget] + tag_suffix
+
+    return tag_suffix[:budget]
+
+
 def _base_slug(image: str, max_len: int = 64) -> str:
     """
     If the slug is too long, keep the most identifiable parts:
@@ -226,24 +252,21 @@ def _base_slug(image: str, max_len: int = 64) -> str:
 
     # Parse components from the slug form
     if "_tag_" in base_slug:
-        left, tag = base_slug.split("_tag_", 1)
+        left, tag = base_slug.rsplit("_tag_", 1)  # Split on last : (rightmost tag)
     else:
         left, tag = base_slug, ""
 
     parts = left.split("_s_") if left else []
     repo = parts[-1] if parts else left  # last path segment is the repo
 
-    # Reconstruct a compact, identifiable core: "<repo>[_tag_<tag>]"
-    ident = repo + (f"_tag_{tag}" if tag else "")
-
     # Fit within budget, reserving space for the digest suffix
     visible_budget = max_len - len(suffix)
     assert visible_budget > 0, (
         f"max_len too small to fit digest suffix with length {len(suffix)}"
     )
 
-    kept = ident[:visible_budget]
-    return kept + suffix
+    ident = _truncate_ident(repo, tag, visible_budget)
+    return ident + suffix
 
 
 def _git_info() -> tuple[str, str]:

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/openhands/agent_server/env_parser.py

@@ -2,6 +2,7 @@
 We couldn't use pydantic-settings for this as we need complex nested types
 and polymorphism."""
 
+import importlib
 import inspect
 import json
 import os
@@ -278,14 +279,53 @@ class DiscriminatedUnionEnvParser(EnvParser):
     def from_env(self, key: str) -> JsonType:
         kind = os.environ.get(f"{key}_KIND", MISSING)
         if kind is MISSING:
-            return MISSING
-        assert isinstance(kind, str)
+            # If there is exactly one kind, use it directly
+            if len(self.parsers) == 1:
+                kind = next(iter(self.parsers.keys()))
+            else:
+                return MISSING
+        # Type narrowing: kind is str here (from os.environ.get or dict keys)
+        kind = cast(str, kind)
+
+        # If kind contains dots, treat it as a full class name
+        if "." in kind:
+            kind = self._import_and_register_class(kind)
+
+        # Intentionally raise KeyError for invalid KIND - typos should fail early
         parser = self.parsers[kind]
         parser_result = parser.from_env(key)
-        assert isinstance(parser_result, dict)
+        # Type narrowing: discriminated union parsers always return dicts
+        parser_result = cast(dict, parser_result)
         parser_result["kind"] = kind
         return parser_result
 
+    def _import_and_register_class(self, full_class_name: str) -> str:
+        """Import a class from its full module path and register its parser.
+
+        Args:
+            full_class_name: Full class path (e.g., 'mymodule.submodule.MyClass')
+
+        Returns:
+            The unqualified class name (e.g., 'MyClass')
+        """
+        parts = full_class_name.rsplit(".", 1)
+        module_name = parts[0]
+        class_name = parts[1]
+
+        # If class already registered, just return the name
+        if class_name in self.parsers:
+            return class_name
+
+        # Import the module and get the class
+        module = importlib.import_module(module_name)
+        cls = getattr(module, class_name)
+
+        # Create and register the parser for this class
+        parser = get_env_parser(cls, _get_default_parsers())
+        self.parsers[class_name] = parser
+
+        return class_name
+
     def to_env(self, key: str, value: Any, output: IO):
         parser = self.parsers[value.kind]
         parser.to_env(key, value, output)

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/openhands/agent_server/event_service.py

@@ -311,7 +311,21 @@ class EventService:
             with self._conversation.state as state:
                 run = state.execution_status != ConversationExecutionStatus.RUNNING
         if run:
-            loop.run_in_executor(None, self._conversation.run)
+            conversation = self._conversation
+
+            async def _run_with_error_handling():
+                try:
+                    await loop.run_in_executor(None, conversation.run)
+                except Exception:
+                    logger.exception("Error during conversation run from send_message")
+
+            # Fire-and-forget: This task is intentionally not tracked because
+            # send_message() is designed to return immediately after queuing the
+            # message. The conversation run happens in the background and any
+            # errors are logged. Unlike the run() method which is explicitly
+            # awaited, this pattern allows clients to send messages without
+            # blocking on the full conversation execution.
+            loop.create_task(_run_with_error_handling())
 
     async def subscribe_to_events(self, subscriber: Subscriber[Event]) -> UUID:
         subscriber_id = self._pub_sub.subscribe(subscriber)
@@ -319,20 +333,23 @@ class EventService:
         # Send current state to the new subscriber immediately
         if self._conversation:
             state = self._conversation._state
+            # Create state snapshot while holding the lock to ensure consistency.
+            # ConversationStateUpdateEvent inherits from Event which has frozen=True
+            # in its model_config, making the snapshot immutable after creation.
             with state:
-                # Create state update event with current state information
                 state_update_event = (
                     ConversationStateUpdateEvent.from_conversation_state(state)
                 )
 
-                # Send state update directly to the new subscriber
-                try:
-                    await subscriber(state_update_event)
-                except Exception as e:
-                    logger.error(
-                        f"Error sending initial state to subscriber "
-                        f"{subscriber_id}: {e}"
-                    )
+            # Send state update outside the lock - the event is frozen (immutable),
+            # so we don't need to hold the lock during the async send operation.
+            # This prevents potential deadlocks between the sync FIFOLock and async I/O.
+            try:
+                await subscriber(state_update_event)
+            except Exception as e:
+                logger.error(
+                    f"Error sending initial state to subscriber {subscriber_id}: {e}"
+                )
 
         return subscriber_id
 
@@ -425,6 +442,7 @@ class EventService:
             stuck_detection=self.stored.stuck_detection,
             visualizer=None,
             secrets=self.stored.secrets,
+            cipher=self.cipher,
         )
 
         # Set confirmation mode if enabled
@@ -496,8 +514,8 @@ class EventService:
             async def _run_and_publish():
                 try:
                     await loop.run_in_executor(None, conversation.run)
-                except Exception as e:
-                    logger.error(f"Error during conversation run: {e}")
+                except Exception:
+                    logger.exception("Error during conversation run")
                 finally:
                     # Clear task reference and publish state update
                     self._run_task = None
@@ -629,11 +647,18 @@ class EventService:
             return
 
         state = self._conversation._state
+        # Create state snapshot while holding the lock to ensure consistency.
+        # ConversationStateUpdateEvent inherits from Event which has frozen=True
+        # in its model_config, making the snapshot immutable after creation.
         with state:
             state_update_event = ConversationStateUpdateEvent.from_conversation_state(
                 state
             )
-            await self._pub_sub(state_update_event)
+        # Publish outside the lock - the event is frozen (immutable).
+        # Note: _pub_sub iterates through subscribers sequentially. If any subscriber
+        # is slow, it will delay subsequent subscribers. For high-throughput scenarios,
+        # consider using asyncio.gather() for concurrent notification in the future.
+        await self._pub_sub(state_update_event)
 
     async def __aenter__(self):
         await self.start()

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/openhands/agent_server/file_router.py

@@ -17,6 +17,7 @@ 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.agent_server.server_details_router import update_last_execution_time
 from openhands.sdk.logger import get_logger
 
 
@@ -33,6 +34,7 @@ async def upload_file(
     file: Annotated[UploadFile, File(...)],
 ) -> Success:
     """Upload a file to the workspace."""
+    update_last_execution_time()
     logger.info(f"Uploading file: {path}")
     try:
         target_path = Path(path)
@@ -66,6 +68,7 @@ async def download_file(
     path: Annotated[str, FastApiPath(description="Absolute file path.")],
 ) -> FileResponse:
     """Download a file from the workspace."""
+    update_last_execution_time()
     logger.info(f"Downloading file: {path}")
     try:
         target_path = Path(path)

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/openhands/agent_server/git_router.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 from fastapi import APIRouter
 
+from openhands.agent_server.server_details_router import update_last_execution_time
 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
@@ -19,16 +20,17 @@ logger = logging.getLogger(__name__)
 async def git_changes(
     path: Path,
 ) -> list[GitChange]:
+    update_last_execution_time()
     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:
+    update_last_execution_time()
     loop = asyncio.get_running_loop()
     changes = await loop.run_in_executor(None, get_git_diff, path)
     return changes

openhands_agent_server-1.9.0/openhands/agent_server/logging_config.py

@@ -0,0 +1,114 @@
+"""Custom logging configuration for uvicorn to reuse the SDK's root logger."""
+
+import logging
+from typing import Any
+
+from pythonjsonlogger.json import JsonFormatter
+
+from openhands.sdk.logger import ENV_JSON, ENV_LOG_LEVEL, IN_CI
+
+
+class UvicornAccessJsonFormatter(JsonFormatter):
+    """JSON formatter for uvicorn access logs that extracts HTTP fields.
+
+    Uvicorn access logs pass structured data in record.args as a tuple:
+    (client_addr, method, full_path, http_version, status_code)
+
+    This formatter extracts these into separate JSON fields for better
+    querying and analysis in log aggregation systems like Datadog.
+    """
+
+    def add_fields(
+        self,
+        log_data: dict[str, Any],
+        record: logging.LogRecord,
+        message_dict: dict[str, Any],
+    ) -> None:
+        super().add_fields(log_data, record, message_dict)
+
+        # Extract HTTP fields from uvicorn access log args
+        # record.args is a tuple for uvicorn access logs:
+        # (client_addr, method, full_path, http_version, status_code)
+        args = record.args
+        if isinstance(args, tuple) and len(args) >= 5:
+            client_addr, method, full_path, http_version, status_code = args[:5]
+            log_data["http.client_ip"] = client_addr
+            log_data["http.method"] = method
+            log_data["http.url"] = full_path
+            log_data["http.version"] = http_version
+            # status_code from uvicorn is typically an int, but handle edge cases
+            if isinstance(status_code, int):
+                log_data["http.status_code"] = status_code
+            elif isinstance(status_code, str) and status_code.isdigit():
+                log_data["http.status_code"] = int(status_code)
+            else:
+                log_data["http.status_code"] = status_code
+
+
+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. Uses JSON formatter for access logs when LOG_JSON=true or in CI
+    4. Extracts HTTP fields into structured JSON attributes
+    """
+    use_json = ENV_JSON or IN_CI
+    log_level = logging.getLevelName(ENV_LOG_LEVEL)
+
+    # Base configuration
+    config: dict[str, Any] = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "incremental": False,
+        "formatters": {},
+        "handlers": {},
+        "loggers": {
+            # Common logger configurations - propagate to root
+            "uvicorn": {
+                "handlers": [],
+                "level": log_level,
+                "propagate": True,
+            },
+            "uvicorn.error": {
+                "handlers": [],
+                "level": log_level,
+                "propagate": True,
+            },
+        },
+    }
+
+    if use_json:
+        # Define JSON formatter for access logs with HTTP field extraction
+        config["formatters"]["access_json"] = {
+            "()": UvicornAccessJsonFormatter,
+            "fmt": "%(asctime)s %(levelname)s %(name)s %(message)s",
+        }
+
+        # Define handler for access logs
+        config["handlers"]["access_json"] = {
+            "class": "logging.StreamHandler",
+            "formatter": "access_json",
+            "stream": "ext://sys.stderr",
+        }
+
+        # Access logger uses dedicated JSON handler with HTTP field extraction
+        config["loggers"]["uvicorn.access"] = {
+            "handlers": ["access_json"],
+            "level": log_level,
+            "propagate": False,  # Don't double-log
+        }
+    else:
+        # Non-JSON mode: propagate access logs to root (uses Rich handler)
+        config["loggers"]["uvicorn.access"] = {
+            "handlers": [],
+            "level": log_level,
+            "propagate": True,
+        }
+
+    return config
+
+
+LOGGING_CONFIG = get_uvicorn_logging_config()

{openhands_agent_server-1.8.1 → openhands_agent_server-1.9.0}/openhands/agent_server/middleware.py

@@ -1,3 +1,4 @@
+import os
 from urllib.parse import urlparse
 
 from fastapi.middleware.cors import CORSMiddleware
@@ -5,8 +6,10 @@ 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.
+    """Custom CORS middleware that allows any request from localhost/127.0.0.1 domains.
+
+    Also allows the DOCKER_HOST_ADDR IP, while using standard CORS rules for
+    other origins.
     """
 
     def __init__(self, app: ASGIApp, allow_origins: list[str]) -> None:
@@ -27,6 +30,11 @@ class LocalhostCORSMiddleware(CORSMiddleware):
             if hostname in ["localhost", "127.0.0.1"]:
                 return True
 
+            # Also allow DOCKER_HOST_ADDR if set (for remote browser access)
+            docker_host_addr = os.environ.get("DOCKER_HOST_ADDR")
+            if docker_host_addr and hostname == docker_host_addr:
+                return True
+
         # For missing origin or other origins, use the parent class's logic
         result: bool = super().is_allowed_origin(origin)
         return result