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

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/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/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/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
@@ -277,15 +278,65 @@ class DiscriminatedUnionEnvParser(EnvParser):
 
     def from_env(self, key: str) -> JsonType:
         kind = os.environ.get(f"{key}_KIND", MISSING)
+        kind_missing = False
         if kind is MISSING:
-            return MISSING
-        assert isinstance(kind, str)
+            kind_missing = True
+            # If there are other fields and 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)
+
+        # A kind was defined without other fields
+        if parser_result is MISSING:
+            # If the kind was not defined, the entry is MISSING
+            if kind_missing:
+                return MISSING
+            # Only a kind was defined
+            parser_result = {}
+
+        # 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/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
 
@@ -497,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
@@ -630,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/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/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/logging_config.py

@@ -3,7 +3,46 @@
 import logging
 from typing import Any
 
-from openhands.sdk.logger import ENV_LOG_LEVEL
+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]:
@@ -13,42 +52,61 @@ def get_uvicorn_logging_config() -> dict[str, Any]:
     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
+    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
-    # Note: We cannot use incremental=True with partial handler definitions
-    # So we set it to False but configure loggers to propagate to root
-    config = {
+    config: dict[str, Any] = {
         "version": 1,
         "disable_existing_loggers": False,
-        "incremental": False,  # Cannot be True when defining new handlers
+        "incremental": False,
         "formatters": {},
         "handlers": {},
-        "loggers": {},
+        "loggers": {
+            # Common logger configurations - propagate to root
+            "uvicorn": {
+                "handlers": [],
+                "level": log_level,
+                "propagate": True,
+            },
+            "uvicorn.error": {
+                "handlers": [],
+                "level": log_level,
+                "propagate": True,
+            },
+        },
     }
 
-    # 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": {
+    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": logging.getLevelName(ENV_LOG_LEVEL),
+            "level": log_level,
             "propagate": True,
-        },
-    }
+        }
 
     return config
 

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

openhands/agent_server/skills_router.py

@@ -0,0 +1,181 @@
+"""Skills router for OpenHands Agent Server.
+
+This module defines the HTTP API endpoints for skill operations.
+Business logic is delegated to skills_service.py.
+"""
+
+from typing import Literal
+
+from fastapi import APIRouter
+from pydantic import BaseModel, Field
+
+from openhands.agent_server.skills_service import (
+    ExposedUrlData,
+    load_all_skills,
+    sync_public_skills,
+)
+
+
+skills_router = APIRouter(prefix="/skills", tags=["Skills"])
+
+
+class ExposedUrl(BaseModel):
+    """Represents an exposed URL from the sandbox."""
+
+    name: str
+    url: str
+    port: int
+
+
+class OrgConfig(BaseModel):
+    """Configuration for loading organization-level skills."""
+
+    repository: str = Field(description="Selected repository (e.g., 'owner/repo')")
+    provider: str = Field(
+        description="Git provider type: github, gitlab, azure, bitbucket"
+    )
+    org_repo_url: str = Field(
+        description="Pre-authenticated Git URL for the organization repository. "
+        "Contains sensitive credentials - handle with care and avoid logging."
+    )
+    org_name: str = Field(description="Organization name")
+
+
+class SandboxConfig(BaseModel):
+    """Configuration for loading sandbox-specific skills."""
+
+    exposed_urls: list[ExposedUrl] = Field(
+        default_factory=list,
+        description="List of exposed URLs from the sandbox",
+    )
+
+
+class SkillsRequest(BaseModel):
+    """Request body for loading skills."""
+
+    load_public: bool = Field(
+        default=True, description="Load public skills from OpenHands/skills repo"
+    )
+    load_user: bool = Field(
+        default=True, description="Load user skills from ~/.openhands/skills/"
+    )
+    load_project: bool = Field(
+        default=True, description="Load project skills from workspace"
+    )
+    load_org: bool = Field(default=True, description="Load organization-level skills")
+    project_dir: str | None = Field(
+        default=None, description="Workspace directory path for project skills"
+    )
+    org_config: OrgConfig | None = Field(
+        default=None, description="Organization skills configuration"
+    )
+    sandbox_config: SandboxConfig | None = Field(
+        default=None, description="Sandbox skills configuration"
+    )
+
+
+class SkillInfo(BaseModel):
+    """Skill information returned by the API."""
+
+    name: str
+    type: Literal["repo", "knowledge", "agentskills"]
+    content: str
+    triggers: list[str] = Field(default_factory=list)
+    source: str | None = None
+    description: str | None = None
+    is_agentskills_format: bool = False
+
+
+class SkillsResponse(BaseModel):
+    """Response containing all available skills."""
+
+    skills: list[SkillInfo]
+    sources: dict[str, int] = Field(
+        default_factory=dict,
+        description="Count of skills loaded from each source",
+    )
+
+
+class SyncResponse(BaseModel):
+    """Response from skill sync operation."""
+
+    status: Literal["success", "error"]
+    message: str
+
+
+@skills_router.post("", response_model=SkillsResponse)
+def get_skills(request: SkillsRequest) -> SkillsResponse:
+    """Load and merge skills from all configured sources.
+
+    Skills are loaded from multiple sources and merged with the following
+    precedence (later overrides earlier for duplicate names):
+    1. Sandbox skills (lowest) - Exposed URLs from sandbox
+    2. Public skills - From GitHub OpenHands/skills repository
+    3. User skills - From ~/.openhands/skills/
+    4. Organization skills - From {org}/.openhands or equivalent
+    5. Project skills (highest) - From {workspace}/.openhands/skills/
+
+    Args:
+        request: SkillsRequest containing configuration for which sources to load.
+
+    Returns:
+        SkillsResponse containing merged skills and source counts.
+    """
+    # Convert Pydantic models to service data types
+    sandbox_urls = None
+    if request.sandbox_config and request.sandbox_config.exposed_urls:
+        sandbox_urls = [
+            ExposedUrlData(name=url.name, url=url.url, port=url.port)
+            for url in request.sandbox_config.exposed_urls
+        ]
+
+    org_repo_url = None
+    org_name = None
+    if request.org_config:
+        org_repo_url = request.org_config.org_repo_url
+        org_name = request.org_config.org_name
+
+    # Call the service
+    result = load_all_skills(
+        load_public=request.load_public,
+        load_user=request.load_user,
+        load_project=request.load_project,
+        load_org=request.load_org,
+        project_dir=request.project_dir,
+        org_repo_url=org_repo_url,
+        org_name=org_name,
+        sandbox_exposed_urls=sandbox_urls,
+    )
+
+    # Convert Skill objects to SkillInfo for response
+    skills_info = [
+        SkillInfo(
+            name=info.name,
+            type=info.type,
+            content=info.content,
+            triggers=info.triggers,
+            source=info.source,
+            description=info.description,
+            is_agentskills_format=info.is_agentskills_format,
+        )
+        for info in (skill.to_skill_info() for skill in result.skills)
+    ]
+
+    return SkillsResponse(skills=skills_info, sources=result.sources)
+
+
+@skills_router.post("/sync", response_model=SyncResponse)
+def sync_skills() -> SyncResponse:
+    """Force refresh of public skills from GitHub repository.
+
+    This triggers a git pull on the cached skills repository to get
+    the latest skills from the OpenHands/skills repository.
+
+    Returns:
+        SyncResponse indicating success or failure.
+    """
+    success, message = sync_public_skills()
+    return SyncResponse(
+        status="success" if success else "error",
+        message=message,
+    )

openhands/agent_server/skills_service.py

@@ -0,0 +1,401 @@
+"""Skills service for OpenHands Agent Server.
+
+This module contains the business logic for skill loading and management,
+keeping the router clean and focused on HTTP concerns.
+
+Skill Sources:
+- Public skills: GitHub OpenHands/skills repository
+- User skills: ~/.openhands/skills/ and ~/.openhands/microagents/
+- Project skills: {workspace}/.openhands/skills/, .cursorrules, agents.md
+- Organization skills: {org}/.openhands or {org}/openhands-config
+- Sandbox skills: Exposed URLs from sandbox environment
+
+Precedence (later overrides earlier):
+sandbox < public < user < org < project
+"""
+
+import os
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from openhands.sdk.context.skills import (
+    Skill,
+    load_project_skills,
+    load_public_skills,
+    load_user_skills,
+)
+from openhands.sdk.context.skills.skill import (
+    PUBLIC_SKILLS_BRANCH,
+    PUBLIC_SKILLS_REPO,
+    load_skills_from_dir,
+)
+from openhands.sdk.context.skills.utils import (
+    get_skills_cache_dir,
+    update_skills_repository,
+)
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+# Content template for sandbox work hosts skill
+WORK_HOSTS_SKILL_CONTENT = (
+    "The user has access to the following hosts for accessing "
+    "a web application, each of which has a corresponding port:\n{hosts}"
+)
+
+# Prefix for sandbox URLs that should be exposed as work_hosts skill.
+# URLs with names starting with this prefix represent web applications
+# or services running in the sandbox that the agent should be aware of.
+SANDBOX_WORKER_URL_PREFIX = "WORKER_"
+
+
+@dataclass
+class ExposedUrlData:
+    """Internal representation of an exposed URL from the sandbox."""
+
+    name: str
+    url: str
+    port: int
+
+
+@dataclass
+class SkillLoadResult:
+    """Result of loading skills from all sources."""
+
+    skills: list[Skill]
+    sources: dict[str, int]
+
+
+def load_org_skills_from_url(
+    org_repo_url: str,
+    org_name: str,
+    working_dir: str | Path | None = None,
+) -> list[Skill]:
+    """Load skills from an organization repository.
+
+    This function clones an organization-level skills repository to a temporary
+    directory, loads skills from the skills/ and microagents/ directories, and
+    then cleans up the temporary directory.
+
+    The org_repo_url should be a pre-authenticated Git URL (e.g., containing
+    credentials or tokens) as provided by the app-server.
+
+    Note:
+        This is a blocking I/O operation that may take up to 120 seconds due to
+        the git clone timeout. When called from FastAPI endpoints defined with
+        `def` (not `async def`), FastAPI automatically runs this in a thread
+        pool to avoid blocking the event loop. Do not call this function
+        directly from async code without wrapping it in asyncio.to_thread().
+
+    Args:
+        org_repo_url: Pre-authenticated Git URL for the organization repository.
+            This should be a full Git URL that includes authentication.
+        org_name: Name of the organization (used for temp directory naming).
+        working_dir: Optional working directory for git operations. If None,
+            uses a subdirectory of the system temp directory.
+
+    Returns:
+        List of Skill objects loaded from the organization repository.
+        Returns empty list if the repository doesn't exist or loading fails.
+    """
+    all_skills: list[Skill] = []
+
+    # Determine the temporary directory for cloning
+    if working_dir:
+        base_dir = Path(working_dir) if isinstance(working_dir, str) else working_dir
+        temp_dir = base_dir / f"_org_skills_{org_name}"
+    else:
+        temp_dir = Path(tempfile.gettempdir()) / f"openhands_org_skills_{org_name}"
+
+    try:
+        # Clean up any existing temp directory
+        if temp_dir.exists():
+            shutil.rmtree(temp_dir)
+
+        # Clone the organization repository (shallow clone for efficiency)
+        logger.info(f"Cloning organization skills repository for {org_name}")
+        try:
+            subprocess.run(
+                [
+                    "git",
+                    "clone",
+                    "--depth",
+                    "1",
+                    org_repo_url,
+                    str(temp_dir),
+                ],
+                check=True,
+                capture_output=True,
+                timeout=120,
+                env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
+            )
+        except subprocess.CalledProcessError:
+            # Repository doesn't exist or access denied - this is expected.
+            # Note: We intentionally don't log stderr as it may contain credentials.
+            logger.debug(
+                f"Organization repository not found or access denied for {org_name}"
+            )
+            return all_skills
+        except subprocess.TimeoutExpired:
+            logger.warning(
+                f"Git clone timed out for organization repository {org_name}"
+            )
+            return all_skills
+
+        logger.debug(f"Successfully cloned org repository to {temp_dir}")
+
+        # Load skills from skills/ directory (preferred)
+        skills_dir = temp_dir / "skills"
+        if skills_dir.exists():
+            try:
+                repo_skills, knowledge_skills, agent_skills = load_skills_from_dir(
+                    skills_dir
+                )
+                for skills_dict in [repo_skills, knowledge_skills, agent_skills]:
+                    all_skills.extend(skills_dict.values())
+                logger.debug(
+                    f"Loaded {len(all_skills)} skills from org skills/ directory"
+                )
+            except Exception as e:
+                logger.warning(f"Failed to load skills from {skills_dir}: {e}")
+
+        # Load skills from microagents/ directory (legacy support)
+        microagents_dir = temp_dir / "microagents"
+        if microagents_dir.exists():
+            seen_names = {s.name for s in all_skills}
+            try:
+                repo_skills, knowledge_skills, agent_skills = load_skills_from_dir(
+                    microagents_dir
+                )
+                for skills_dict in [repo_skills, knowledge_skills, agent_skills]:
+                    for name, skill in skills_dict.items():
+                        if name not in seen_names:
+                            all_skills.append(skill)
+                            seen_names.add(name)
+                        else:
+                            logger.debug(
+                                f"Skipping duplicate org skill '{name}' "
+                                "from microagents/"
+                            )
+            except Exception as e:
+                logger.warning(f"Failed to load skills from {microagents_dir}: {e}")
+
+        logger.info(
+            f"Loaded {len(all_skills)} organization skills for {org_name}: "
+            f"{[s.name for s in all_skills]}"
+        )
+
+    except Exception as e:
+        logger.warning(f"Failed to load organization skills for {org_name}: {e}")
+
+    finally:
+        # Clean up the temporary directory
+        if temp_dir.exists():
+            try:
+                shutil.rmtree(temp_dir)
+                logger.debug(f"Cleaned up temp directory {temp_dir}")
+            except Exception as e:
+                logger.warning(f"Failed to clean up temp directory {temp_dir}: {e}")
+
+    return all_skills
+
+
+def create_sandbox_skill(
+    exposed_urls: list[ExposedUrlData],
+) -> Skill | None:
+    """Create a skill from sandbox exposed URLs.
+
+    This function creates a skill that informs the agent about web applications
+    and services available in the sandbox environment via exposed ports/URLs.
+
+    Only URLs with names starting with SANDBOX_WORKER_URL_PREFIX are included,
+    as these represent web applications the agent should be aware of.
+
+    Args:
+        exposed_urls: List of ExposedUrlData objects containing name, url, and port.
+
+    Returns:
+        A Skill object with work_hosts content if there are matching URLs,
+        or None if no relevant URLs are provided.
+    """
+    if not exposed_urls:
+        return None
+
+    # Filter for URLs with the worker prefix
+    worker_urls = [
+        url for url in exposed_urls if url.name.startswith(SANDBOX_WORKER_URL_PREFIX)
+    ]
+
+    if not worker_urls:
+        return None
+
+    # Build the hosts content
+    hosts_lines = []
+    for url_info in worker_urls:
+        hosts_lines.append(f"* {url_info.url} (port {url_info.port})")
+
+    hosts_content = "\n".join(hosts_lines)
+    content = WORK_HOSTS_SKILL_CONTENT.format(hosts=hosts_content)
+
+    return Skill(
+        name="work_hosts",
+        content=content,
+        trigger=None,  # Always active
+        source=None,  # Programmatically generated
+    )
+
+
+def merge_skills(skill_lists: list[list[Skill]]) -> list[Skill]:
+    """Merge multiple skill lists with precedence.
+
+    Later lists override earlier lists for duplicate names.
+
+    Args:
+        skill_lists: List of skill lists to merge in order of precedence.
+
+    Returns:
+        Merged list of skills with duplicates resolved.
+    """
+    skills_by_name: dict[str, Skill] = {}
+
+    for skill_list in skill_lists:
+        for skill in skill_list:
+            if skill.name in skills_by_name:
+                logger.info(
+                    f"Overriding skill '{skill.name}' from earlier source "
+                    "with later source"
+                )
+            skills_by_name[skill.name] = skill
+
+    return list(skills_by_name.values())
+
+
+def load_all_skills(
+    load_public: bool = True,
+    load_user: bool = True,
+    load_project: bool = True,
+    load_org: bool = True,
+    project_dir: str | None = None,
+    org_repo_url: str | None = None,
+    org_name: str | None = None,
+    sandbox_exposed_urls: list[ExposedUrlData] | None = None,
+) -> SkillLoadResult:
+    """Load and merge skills from all configured sources.
+
+    Skills are loaded from multiple sources and merged with the following
+    precedence (later overrides earlier for duplicate names):
+    1. Sandbox skills (lowest) - Exposed URLs from sandbox
+    2. Public skills - From GitHub OpenHands/skills repository
+    3. User skills - From ~/.openhands/skills/
+    4. Organization skills - From {org}/.openhands or equivalent
+    5. Project skills (highest) - From {workspace}/.openhands/skills/
+
+    Args:
+        load_public: Whether to load public skills from OpenHands/skills repo.
+        load_user: Whether to load user skills from ~/.openhands/skills/.
+        load_project: Whether to load project skills from workspace.
+        load_org: Whether to load organization-level skills.
+        project_dir: Workspace directory path for project skills.
+        org_repo_url: Pre-authenticated Git URL for org skills.
+        org_name: Organization name for org skills.
+        sandbox_exposed_urls: List of exposed URLs from sandbox.
+
+    Returns:
+        SkillLoadResult containing merged skills and source counts.
+    """
+    sources: dict[str, int] = {}
+    skill_lists: list[list[Skill]] = []
+
+    # 1. Load sandbox skills (lowest precedence)
+    sandbox_skills: list[Skill] = []
+    if sandbox_exposed_urls:
+        sandbox_skill = create_sandbox_skill(sandbox_exposed_urls)
+        if sandbox_skill:
+            sandbox_skills.append(sandbox_skill)
+    sources["sandbox"] = len(sandbox_skills)
+    skill_lists.append(sandbox_skills)
+
+    # 2. Load public skills
+    public_skills: list[Skill] = []
+    if load_public:
+        try:
+            public_skills = load_public_skills()
+            logger.info(f"Loaded {len(public_skills)} public skills")
+        except Exception as e:
+            logger.warning(f"Failed to load public skills: {e}")
+    sources["public"] = len(public_skills)
+    skill_lists.append(public_skills)
+
+    # 3. Load user skills
+    user_skills: list[Skill] = []
+    if load_user:
+        try:
+            user_skills = load_user_skills()
+            logger.info(f"Loaded {len(user_skills)} user skills")
+        except Exception as e:
+            logger.warning(f"Failed to load user skills: {e}")
+    sources["user"] = len(user_skills)
+    skill_lists.append(user_skills)
+
+    # 4. Load organization skills
+    org_skills: list[Skill] = []
+    if load_org and org_repo_url and org_name:
+        try:
+            org_skills = load_org_skills_from_url(
+                org_repo_url=org_repo_url,
+                org_name=org_name,
+            )
+            logger.info(f"Loaded {len(org_skills)} organization skills")
+        except Exception as e:
+            logger.warning(f"Failed to load organization skills: {e}")
+    sources["org"] = len(org_skills)
+    skill_lists.append(org_skills)
+
+    # 5. Load project skills (highest precedence)
+    project_skills: list[Skill] = []
+    if load_project and project_dir:
+        try:
+            project_skills = load_project_skills(project_dir)
+            logger.info(f"Loaded {len(project_skills)} project skills")
+        except Exception as e:
+            logger.warning(f"Failed to load project skills: {e}")
+    sources["project"] = len(project_skills)
+    skill_lists.append(project_skills)
+
+    # Merge all skills with precedence
+    all_skills = merge_skills(skill_lists)
+
+    logger.info(
+        f"Returning {len(all_skills)} total skills: {[s.name for s in all_skills]}"
+    )
+
+    return SkillLoadResult(skills=all_skills, sources=sources)
+
+
+def sync_public_skills() -> tuple[bool, str]:
+    """Force refresh of public skills from GitHub repository.
+
+    This triggers a git pull on the cached skills repository to get
+    the latest skills from the OpenHands/skills repository.
+
+    Returns:
+        Tuple of (success: bool, message: str).
+    """
+    try:
+        cache_dir = get_skills_cache_dir()
+        result = update_skills_repository(
+            PUBLIC_SKILLS_REPO, PUBLIC_SKILLS_BRANCH, cache_dir
+        )
+
+        if result:
+            return (True, "Skills repository synced successfully")
+        else:
+            return (False, "Failed to sync skills repository")
+    except Exception as e:
+        logger.warning(f"Failed to sync skills repository: {e}")
+        return (False, f"Sync failed: {str(e)}")

{openhands_agent_server-1.8.2.dist-info → openhands_agent_server-1.9.1.dist-info}/METADATA

@@ -1,7 +1,11 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.8.2
+Version: 1.9.1
 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.8.2.dist-info → openhands_agent_server-1.9.1.dist-info}/RECORD

@@ -1,7 +1,7 @@
 openhands/agent_server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openhands/agent_server/__main__.py,sha256=QCdBRWVV9gNtPwRwYieQisvKsmJljjJ8f293RhtHl_w,3642
-openhands/agent_server/api.py,sha256=M9__D_T6m3_0dlkbZzahMM_SPF-j0uYAnoJoCvkZGQM,11901
-openhands/agent_server/bash_router.py,sha256=9aKNxzdKSlKoYJ3ngvdf4rjv1_iNNmpRoZkqhJ4qhxQ,3203
+openhands/agent_server/api.py,sha256=LqU4BWXc4VQ29sIiABZykznSMJ_dUQEOHixxeLBTuGY,12009
+openhands/agent_server/bash_router.py,sha256=9GRsLeVZgqR1XeayJvBBycVqfg5O-Fye2ek75kGCuno,3353
 openhands/agent_server/bash_service.py,sha256=QgTSyQoxlk52BnZuo35xlX7u7-3xs5BvvaKU3AEva_w,14083
 openhands/agent_server/config.py,sha256=EKxVV0QyD3KLLtFxNuUextxJplLW_zZ32nPFhli6ozA,6403
 openhands/agent_server/conversation_router.py,sha256=lz-dnfPXrVBiGZ9GhYqfteCWJ4pq7AcnWqxsKWwCfc0,11178
@@ -9,18 +9,20 @@ openhands/agent_server/conversation_service.py,sha256=Oj8IBSY9ZYbduOOBatd3I0H_kS
 openhands/agent_server/dependencies.py,sha256=H3zyOc8uthpXseB3E7rWNccKIj7PlyfcgCYwFvmFq4c,2629
 openhands/agent_server/desktop_router.py,sha256=OaCmevO33eUo3jTwiXBmQ3uT3ONu4-tqgBfYpZWrHSA,1349
 openhands/agent_server/desktop_service.py,sha256=iCwQJXK4DvGuBXKOQ1oko60wXkf_pYHCubOzBsd2k60,7415
-openhands/agent_server/env_parser.py,sha256=NBa5p_JGYJVMMdCJJ_jicW1iAGS6h8AG_HVlcQ2dxaY,14929
+openhands/agent_server/env_parser.py,sha256=6b4-Iegq82crMbwjo1w4C_nu5B0Wm0xysrhGhfiyMF8,16770
 openhands/agent_server/event_router.py,sha256=XM46zcqPOXStISfihzsPXPfsW_23E50brmBHk04ncVI,6156
-openhands/agent_server/event_service.py,sha256=DdaoMh97aXtfzMr17psmDThugUPdf2_GKJGu98WIN78,25221
-openhands/agent_server/file_router.py,sha256=ysDjIKzDNbi7m95JrH6kP6BYcBhTJhTpJVMkNtYVYhs,4011
-openhands/agent_server/git_router.py,sha256=g0cVeyJ_mUAuieZ3bbTl5Xvm94FnNwRt07iNBASiXgU,844
-openhands/agent_server/logging_config.py,sha256=DPPxIl1tUVGiui-JVSKgs73KXPFfDNX2ivGuZSkbLe4,1832
-openhands/agent_server/middleware.py,sha256=9wuAurN8TCXTCRl6ANIMoFSvHeZsYDLFXIrBH15yhQU,1117
+openhands/agent_server/event_service.py,sha256=EFjIkWbTrROAv2zFzsIOhcRDTZIhf0uIGQStNDg8nFY,26838
+openhands/agent_server/file_router.py,sha256=MqFmTcDFE42EEPwRncBtT-Vu8_U78OZfC6pm0tnlBZk,4161
+openhands/agent_server/git_router.py,sha256=z-jbkY4me1HuLOWTzJu_osI19ZGGri5ffYujVAWe31s,974
+openhands/agent_server/logging_config.py,sha256=b3N5LVGuwDd0bBsMxrVdCHa8N1Nsreawgi23hTkDrro,3985
+openhands/agent_server/middleware.py,sha256=WQN5T14E58cvG2ZG6qfaJL4Dk9DqUGqD5tyAva1Un_4,1407
 openhands/agent_server/models.py,sha256=R3WSDIQN1burIyV4Dz05YITR9WWcC_pXgZDk-7WG6hw,9723
 openhands/agent_server/openapi.py,sha256=RJWaOnM9NjzrH-fJi3PoIBv5d0sH5z8zZTdvYzSqoFU,482
 openhands/agent_server/pub_sub.py,sha256=yPB84Wub7A2uwUWsW_grbxomWmKaWyGuo6dVNUzg1FU,2755
 openhands/agent_server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openhands/agent_server/server_details_router.py,sha256=LCa0NQ3SOw-IgJh3rDJL5GolFOpZcX_-XEbDLHF8dN4,950
+openhands/agent_server/skills_router.py,sha256=mYiIAOGJxnpMz_OsbtP2cBjHNvo3qYUXqGPHKQs_pEw,5601
+openhands/agent_server/skills_service.py,sha256=hmyo1FtUEwfPWk1NnMyGGhvIqPwO28Mjk3chUw_98XM,14125
 openhands/agent_server/sockets.py,sha256=UhZr_QoHsIX7x_tzvk9_AJa2S8KJmRr4syhIU4He8Rs,6617
 openhands/agent_server/tool_preload_service.py,sha256=2QuFyn7jC4Ifq2aUhs9j8876wSBdY0eeoLo4qEVi-yA,2341
 openhands/agent_server/tool_router.py,sha256=vM_9UKUzfChLK9B9Z3DL4VtKNdDw4w635knu9N36y0c,676
@@ -28,12 +30,12 @@ openhands/agent_server/utils.py,sha256=ajivE_kGCJ9qUhF9H3Qu7DUKg7uDvDQk16JcO3Xnt
 openhands/agent_server/vscode_router.py,sha256=tPmXzN6teuqMa1jvKS4Q3aWpk9p9wsp4LleKoDvkYGs,2133
 openhands/agent_server/vscode_service.py,sha256=xS_vwIU5W5KwXTbOTzHPkPRIB4xbjmYlAygmRfBOAF8,7606
 openhands/agent_server/docker/Dockerfile,sha256=rdFlMdI_uITipzR7-pPEGFx2Ld-jYhOBfGKONRk4dbU,10724
-openhands/agent_server/docker/build.py,sha256=Egsge_yIVCeiJ_gvva6VyPeQtOp0WjZFsWvybFV-OfQ,27555
+openhands/agent_server/docker/build.py,sha256=UgHoLkgHZtgWqloG2MQ2RCzc6zTIyttOFL_vUzmw_c0,28189
 openhands/agent_server/docker/wallpaper.svg,sha256=FR2g_b5mzz0x5EvRTKO93ASnWPagAyeS9RI3vRQBAsw,11532
 openhands/agent_server/vscode_extensions/openhands-settings/extension.js,sha256=xoCKZ6YXlzlTWnTC52HuzX0sn9s77Vma-47WgEibO88,858
 openhands/agent_server/vscode_extensions/openhands-settings/package.json,sha256=eCkuBBYEVArEjpp7c_m0H207OCLEygZhBLUEkeFNWOg,289
-openhands_agent_server-1.8.2.dist-info/METADATA,sha256=n3mvRXnyuqYOaTMKUeOPGoHMGZiOHB8MYJZQPmAADiA,468
-openhands_agent_server-1.8.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-openhands_agent_server-1.8.2.dist-info/entry_points.txt,sha256=uLQzPhqDqe85Dy9DvPiBE2CeqkwCryggr1Ty_mq65NA,70
-openhands_agent_server-1.8.2.dist-info/top_level.txt,sha256=jHgVu9I0Blam8BXFgedoGKfglPF8XvW1TsJFIjcgP4E,10
-openhands_agent_server-1.8.2.dist-info/RECORD,,
+openhands_agent_server-1.9.1.dist-info/METADATA,sha256=B0VjqaMpQpjLUEpETaqh1uOPDKKE28xDE4G4NOnVkRc,748
+openhands_agent_server-1.9.1.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+openhands_agent_server-1.9.1.dist-info/entry_points.txt,sha256=uLQzPhqDqe85Dy9DvPiBE2CeqkwCryggr1Ty_mq65NA,70
+openhands_agent_server-1.9.1.dist-info/top_level.txt,sha256=jHgVu9I0Blam8BXFgedoGKfglPF8XvW1TsJFIjcgP4E,10
+openhands_agent_server-1.9.1.dist-info/RECORD,,

{openhands_agent_server-1.8.2.dist-info → openhands_agent_server-1.9.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any