openhands-agent-server 1.48.0__tar.gz → 1.49.0__tar.gz

{openhands_agent_server-1.48.0 → openhands_agent_server-1.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.48.0
+Version: 1.49.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

{openhands_agent_server-1.48.0 → openhands_agent_server-1.49.0}/openhands/agent_server/api.py

@@ -26,7 +26,13 @@ from openhands.agent_server.config import (
     Config,
     get_default_config,
 )
-from openhands.agent_server.conversation_router import conversation_router
+from openhands.agent_server.conversation_registry import (
+    create_conversation_registry,
+)
+from openhands.agent_server.conversation_router import (
+    conversation_catalog_router,
+    conversation_router,
+)
 from openhands.agent_server.conversation_service import (
     CredentialBindingActivationRequired,
     get_default_conversation_service,
@@ -38,8 +44,6 @@ from openhands.agent_server.dependencies import (
     check_session_api_key,
     check_workspace_session,
 )
-from openhands.agent_server.desktop_router import desktop_router
-from openhands.agent_server.event_router import event_router
 from openhands.agent_server.file_router import file_discovery_router, file_router
 from openhands.agent_server.git_router import git_router
 from openhands.agent_server.hooks_router import hooks_router
@@ -60,16 +64,13 @@ from openhands.agent_server.profiles_router import profiles_router
 from openhands.agent_server.provider_connections_router import (
     provider_connections_router,
 )
-from openhands.agent_server.runtime_router import create_runtime_router
 from openhands.agent_server.server_details_router import (
     get_server_info,
     mark_initialization_complete,
     server_details_router,
 )
-from openhands.agent_server.session_socket import session_router
 from openhands.agent_server.settings_router import settings_router
 from openhands.agent_server.skills_router import skills_router
-from openhands.agent_server.sockets import sockets_router
 from openhands.agent_server.sub_agents_router import sub_agents_router
 from openhands.agent_server.telemetry import (
     build_telemetry_sink,
@@ -92,7 +93,6 @@ 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.agent_server.workspace_router import workspace_router
 from openhands.agent_server.workspaces_router import workspaces_router
 from openhands.sdk.logger import DEBUG, get_logger
 from openhands.sdk.utils.redact import sanitize_dict
@@ -160,6 +160,10 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
 
         config: Config = api.state.config
         deferred = config.deferred_init
+        conversation_registry = getattr(
+            api.state, "conversation_registry", None
+        ) or create_conversation_registry(config)
+        api.state.conversation_registry = conversation_registry
 
         # Deferred pods boot with telemetry disabled and are rebuilt by
         # InitService, so they emit `server_started` there instead.
@@ -254,6 +258,11 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
         bash_svc = get_default_bash_event_service()
         api.state.bash_event_service = bash_svc
 
+        conversation_registry.configure_service(service)
+        # Runtime cleanup must precede external-catalog recovery so stale
+        # runtime owners cannot lose their expired leases to the outer service.
+        await conversation_registry.start()
+
         async with service:
             api.state.conversation_service = service
 
@@ -273,6 +282,7 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
             try:
                 yield
             finally:
+                await conversation_registry.shutdown()
                 if retention_task is not None:
                     retention_task.cancel()
                     with suppress(asyncio.CancelledError):
@@ -388,6 +398,7 @@ def _find_http_exception(exc: BaseExceptionGroup) -> HTTPException | None:
 
 def _add_api_routes(app: FastAPI) -> None:
     """Add all API routes to the FastAPI application."""
+    conversation_registry = app.state.conversation_registry
     app.include_router(server_details_router)
 
     # The /api/init endpoint bypasses both the session-key auth and the
@@ -413,8 +424,10 @@ def _add_api_routes(app: FastAPI) -> None:
 
     api_router = APIRouter(prefix="/api", dependencies=dependencies)
     api_router.include_router(file_discovery_router)
-    api_router.include_router(create_runtime_router())
-    api_router.include_router(event_router)
+    # Collection routes must precede runtime catch-alls such as
+    # ``/conversations/{conversation_id}``.
+    api_router.include_router(conversation_catalog_router)
+    conversation_registry.add_execution_routes(api_router)
     api_router.include_router(conversation_router)
     api_router.include_router(credential_binding_router)
     api_router.include_router(tool_router)
@@ -422,7 +435,6 @@ def _add_api_routes(app: FastAPI) -> None:
     api_router.include_router(git_router)
     api_router.include_router(file_router)
     api_router.include_router(vscode_router)
-    api_router.include_router(desktop_router)
     api_router.include_router(skills_router)
     api_router.include_router(sub_agents_router)
     api_router.include_router(plugins_router)
@@ -438,8 +450,6 @@ def _add_api_routes(app: FastAPI) -> None:
     # /api/auth/* mints workspace cookies and requires the header to bootstrap,
     # so it lives under the header-only auth group.
     api_router.include_router(auth_router)
-    app.include_router(api_router)
-
     app.include_router(openai_router, dependencies=[Depends(check_openai_api_key)])
 
     # Workspace static-file routes get their own auth group that accepts
@@ -450,12 +460,11 @@ def _add_api_routes(app: FastAPI) -> None:
     workspace_api_router = APIRouter(
         prefix="/api", dependencies=[Depends(check_workspace_session)]
     )
-    workspace_api_router.include_router(workspace_router)
+    workspace_api_router.include_router(conversation_registry.workspace_router)
     app.include_router(workspace_api_router)
+    app.include_router(api_router)
 
-    app.include_router(sockets_router)
-
-    app.include_router(session_router)
+    app.include_router(conversation_registry.sockets_router)
 
 
 def _setup_static_files(app: FastAPI, config: Config) -> None:
@@ -683,6 +692,7 @@ def create_app(config: Config | None = None) -> FastAPI:
         config = get_default_config()
     app = _create_fastapi_instance(config)
     app.state.config = config
+    app.state.conversation_registry = create_conversation_registry(config)
 
     _add_api_routes(app)
     _setup_static_files(app, config)

{openhands_agent_server-1.48.0 → openhands_agent_server-1.49.0}/openhands/agent_server/config.py

@@ -346,6 +346,13 @@ class Config(BaseModel):
             "The URL where this agent server instance is available externally"
         ),
     )
+    conversation_runtime: Literal["local", "docker"] = "local"
+    conversation_image: str = "ghcr.io/openhands/agent-server:latest-python"
+    conversation_container_memory: str | None = "4g"
+    conversation_container_cpus: float | None = Field(default=2.0, gt=0)
+    conversation_container_pids_limit: int | None = Field(default=512, gt=0)
+    conversation_container_startup_timeout: float = Field(default=120, gt=0)
+
     acp_skill_sourcing: ACPSkillSourcing = Field(
         default="native",
         description=(

openhands_agent_server-1.49.0/openhands/agent_server/conversation_registry.py

@@ -0,0 +1,74 @@
+"""Select and manage the configured conversation runtime."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter
+
+from openhands.agent_server.config import Config
+
+
+if TYPE_CHECKING:
+    from openhands.agent_server.conversation_service import ConversationService
+
+
+class ConversationRegistry:
+    """Route and lifecycle adapter for host-local conversations."""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+
+    def configure_service(self, service: ConversationService) -> None:
+        """Connect runtime-specific persistence to the shared catalog."""
+
+    async def start(self) -> None:
+        """Start resources owned by this registry."""
+
+    async def shutdown(self) -> None:
+        """Stop resources owned by this registry."""
+
+    def add_execution_routes(self, router: APIRouter) -> None:
+        from openhands.agent_server.event_router import event_router
+        from openhands.agent_server.runtime_router import create_runtime_router
+
+        router.include_router(create_runtime_router())
+        router.include_router(event_router)
+
+    @property
+    def workspace_router(self) -> APIRouter:
+        from openhands.agent_server.workspace_router import workspace_router
+
+        return workspace_router
+
+    @property
+    def conversation_sockets_router(self) -> APIRouter:
+        from openhands.agent_server.sockets import conversation_sockets_router
+
+        return conversation_sockets_router
+
+    @property
+    def session_sockets_router(self) -> APIRouter:
+        from openhands.agent_server.session_socket import session_router
+
+        return session_router
+
+    @property
+    def sockets_router(self) -> APIRouter:
+        from openhands.agent_server.sockets import bash_sockets_router
+
+        router = APIRouter()
+        router.include_router(self.conversation_sockets_router)
+        router.include_router(self.session_sockets_router)
+        router.include_router(bash_sockets_router)
+        return router
+
+
+def create_conversation_registry(config: Config) -> ConversationRegistry:
+    if config.conversation_runtime == "docker":
+        from openhands.agent_server.docker_runtime.registry import (
+            DockerConversationRegistry,
+        )
+
+        return DockerConversationRegistry(config)
+    return ConversationRegistry(config)

{openhands_agent_server-1.48.0 → openhands_agent_server-1.49.0}/openhands/agent_server/conversation_router.py

@@ -63,6 +63,7 @@ from openhands.sdk.workspace import LocalWorkspace
 from openhands.tools.preset.default import get_default_tools
 
 
+conversation_catalog_router = APIRouter(prefix="/conversations", tags=["Conversations"])
 conversation_router = APIRouter(prefix="/conversations", tags=["Conversations"])
 
 # Examples
@@ -88,6 +89,7 @@ START_CONVERSATION_EXAMPLES = [
 # Read methods
 
 
+@conversation_catalog_router.get("/search", include_in_schema=False)
 @conversation_router.get("/search")
 async def search_conversations(
     page_id: Annotated[
@@ -128,6 +130,7 @@ async def search_conversations(
     return page
 
 
+@conversation_catalog_router.get("/count", include_in_schema=False)
 @conversation_router.get("/count")
 async def count_conversations(
     status: Annotated[

{openhands_agent_server-1.48.0 → openhands_agent_server-1.49.0}/openhands/agent_server/conversation_service.py

@@ -693,6 +693,7 @@ class ConversationService:
     webhook_specs: list[WebhookSpec] = field(default_factory=list)
     session_api_key: str | None = field(default=None)
     cipher: Cipher | None = None
+    runtime_cipher_resolver: Callable[[UUID], Cipher] | None = None
     mcp_tool_provider: MCPToolProvider | None = None
     secrets_store: FileSecretsStore | None = None
     owner_instance_id: str = field(default_factory=lambda: uuid4().hex)
@@ -703,6 +704,7 @@ class ConversationService:
         default=Path("/tmp/conversation-worktrees")
     )
     acp_skill_sourcing: ACPSkillSourcing = "native"
+    sync_external_catalog: bool = False
     _event_services: dict[UUID, EventService] | None = field(default=None, init=False)
     _conversation_records: dict[UUID, _ConversationRecord] = field(
         default_factory=dict, init=False
@@ -726,16 +728,23 @@ class ConversationService:
         default_factory=dict, init=False
     )
 
-    def _load_catalog_sync(self) -> dict[UUID, _ConversationRecord]:
+    def _load_catalog_sync(
+        self, conversation_id: UUID | None = None
+    ) -> dict[UUID, _ConversationRecord]:
         records: dict[UUID, _ConversationRecord] = {}
-        for conversation_dir in self.conversations_dir.iterdir():
+        directories = (
+            [self.conversations_dir / conversation_id.hex]
+            if conversation_id is not None
+            else self.conversations_dir.iterdir()
+        )
+        for conversation_dir in directories:
             meta_file = conversation_dir / "meta.json"
             if not meta_file.exists():
                 continue
             try:
                 stored = StoredConversation.model_validate_json(
                     meta_file.read_text(),
-                    context={"cipher": self.cipher},
+                    context={"cipher": self._cipher_for(UUID(conversation_dir.name))},
                 )
                 execution_status = ConversationExecutionStatus.IDLE
                 base_state_file = conversation_dir / BASE_STATE
@@ -778,13 +787,19 @@ class ConversationService:
             record.base_state_path = path
         return path
 
+    def _cipher_for(self, conversation_id: UUID) -> Cipher | None:
+        if self.runtime_cipher_resolver is not None:
+            return self.runtime_cipher_resolver(conversation_id)
+        return self.cipher
+
     def _load_persisted_state_sync(
         self, conversation_id: UUID
     ) -> ConversationState | None:
         base_state_file = self.conversations_dir / conversation_id.hex / BASE_STATE
         if not base_state_file.exists():
             return None
-        context = {"cipher": self.cipher} if self.cipher else None
+        cipher = self._cipher_for(conversation_id)
+        context = {"cipher": cipher} if cipher else None
         return ConversationState.model_validate_json(
             base_state_file.read_text(), context=context
         )
@@ -1093,16 +1108,34 @@ class ConversationService:
             record.cached_info = None
             record.state_signature = signature
 
-    async def _reconcile_active_records(self) -> None:
-        """Fill catalog entries for services injected outside normal startup.
-
-        Normal service lifecycle paths maintain the catalog themselves. This
-        small reconciliation keeps direct embedders and existing test fixtures
-        that populate ``_event_services`` compatible.
-        """
+    async def _reconcile_active_records(
+        self, conversation_id: UUID | None = None
+    ) -> None:
+        """Discover externally persisted records and injected live services."""
         event_services = self._event_services
         if event_services is None:
             raise ValueError("inactive_service")
+        if self.sync_external_catalog:
+            disk_records = await asyncio.to_thread(
+                self._load_catalog_sync, conversation_id
+            )
+            stale_ids = (
+                {conversation_id}
+                if conversation_id is not None
+                else set(self._conversation_records)
+            ) - set(disk_records)
+            for record_id in stale_ids:
+                event_service = event_services.get(record_id)
+                if event_service is None or not event_service.is_open():
+                    self._conversation_records.pop(record_id, None)
+            for record_id, record in disk_records.items():
+                event_service = event_services.get(record_id)
+                if event_service is not None and event_service.is_open():
+                    continue
+                existing = self._conversation_records.setdefault(record_id, record)
+                if existing.stored != record.stored:
+                    existing.stored = record.stored
+                    existing.cached_info = None
         for conversation_id, event_service in event_services.items():
             if conversation_id in self._conversation_records:
                 continue
@@ -1237,6 +1270,8 @@ class ConversationService:
     async def get_conversation(self, conversation_id: UUID) -> ConversationInfo | None:
         if self._event_services is None:
             raise ValueError("inactive_service")
+        if self.sync_external_catalog:
+            await self._reconcile_active_records(conversation_id)
         record = self._conversation_records.get(conversation_id)
         if record is None:
             event_service = self._event_services.get(conversation_id)
@@ -1615,7 +1650,12 @@ class ConversationService:
         # Profile resolution and the load_memory stamp must happen before
         # _prepare_request_workspace (which asserts request.agent is not None)
         # and before model_dump so the resolved agent is captured in request_data.
-        launched_agent_profile: LaunchedAgentProfile | None = None
+        runtime_profile = os.getenv("OH_RUNTIME_LAUNCHED_PROFILE")
+        launched_agent_profile = (
+            LaunchedAgentProfile.model_validate_json(runtime_profile)
+            if runtime_profile
+            else None
+        )
 
         from openhands.agent_server.persistence import (
             PersistedSettings,
@@ -2386,6 +2426,7 @@ class ConversationService:
             conversation_idle_ttl_seconds=config.conversation_idle_ttl_seconds,
             conversation_worktree_root=config.conversation_worktree_root,
             acp_skill_sourcing=config.acp_skill_sourcing,
+            sync_external_catalog=False,
         )
 
     async def _start_event_service(

{openhands_agent_server-1.48.0 → openhands_agent_server-1.49.0}/openhands/agent_server/docker/build.py

@@ -398,7 +398,7 @@ class BuildOptions(BaseModel):
         default="", description="Comma-separated list of custom tags."
     )
     image: str = Field(default="ghcr.io/openhands/agent-server")
-    image_flavor: Literal["default", "slim"] = Field(default="default")
+    image_flavor: Literal["default", "slim", "minimal"] = Field(default="default")
     target: TargetType = Field(default="binary")
     platforms: list[PlatformType] = Field(default=["linux/amd64"])
     push: bool | None = Field(
@@ -600,8 +600,10 @@ class BuildOptions(BaseModel):
             for versioned_tag in self.versioned_tags:
                 tags.append(f"{self.image}:{versioned_tag}{arch_suffix}")
 
-        # Append target suffix for clarity (binary is default, no suffix needed)
-        if self.target != "binary":
+        # The minimal image flavor already names its binary-minimal target.
+        if self.target != "binary" and not (
+            self.target == "binary-minimal" and self.image_flavor == "minimal"
+        ):
             tags = [f"{t}-{self.target}" for t in tags]
         return list(dict.fromkeys(tags))
 
@@ -1083,7 +1085,7 @@ def main(argv: list[str]) -> int:
     parser.add_argument(
         "--image-flavor",
         default=_env("IMAGE_FLAVOR", "default"),
-        choices=("default", "slim"),
+        choices=("default", "slim", "minimal"),
         help="Image flavor (default from $IMAGE_FLAVOR).",
     )
     parser.add_argument(

openhands_agent_server-1.49.0/openhands/agent_server/docker_runtime/__init__.py

@@ -0,0 +1 @@
+"""Per-conversation Docker runtime support."""

openhands_agent_server-1.49.0/openhands/agent_server/docker_runtime/mediation.py

@@ -0,0 +1,112 @@
+"""Prepare a conversation request for an isolated agent-server."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import SecretStr
+
+from openhands.agent_server.config import Config
+from openhands.agent_server.conversation_service import (
+    _resolve_agent_from_profile,
+    _with_load_memory,
+)
+from openhands.agent_server.docker_runtime.provisioning import RuntimeIdentity
+from openhands.agent_server.persistence import PersistedSettings, get_settings_store
+from openhands.sdk.agent.base import AgentBase
+from openhands.sdk.conversation.request import StartConversationRequest
+from openhands.sdk.conversation.secret_registry import SecretRegistry
+from openhands.sdk.profiles.agent_profile import LaunchedAgentProfile
+from openhands.sdk.secret import SecretSource, SecretValue, StaticSecret
+from openhands.sdk.settings.model import validate_agent_settings
+
+
+def materialize_secrets(
+    secrets: Mapping[str, SecretValue],
+) -> dict[str, SecretSource]:
+    """Resolve the SDK's secret sources before crossing a runtime boundary."""
+    registry = SecretRegistry()
+    registry.update_secrets(secrets)
+    return {
+        name: StaticSecret(
+            value=SecretStr(value)
+            if (value := registry.get_secret_value(name))
+            else None,
+            description=source.description,
+        )
+        for name, source in registry.secret_sources.items()
+    }
+
+
+def _materialize_agent_context(agent: AgentBase) -> AgentBase:
+    context = agent.agent_context
+    if context is None or not context.secrets:
+        return agent
+    return agent.model_copy(
+        update={
+            "agent_context": context.model_copy(
+                update={"secrets": materialize_secrets(context.secrets)}
+            )
+        }
+    )
+
+
+async def prepare_start(
+    body: dict[str, Any], config: Config
+) -> tuple[StartConversationRequest, LaunchedAgentProfile | None]:
+    body = {
+        name: value
+        for name, value in body.items()
+        if value is not None or name not in {"agent", "agent_settings"}
+    }
+    context = {"cipher": config.cipher} if body.get("secrets_encrypted") else None
+    if body.get("agent_settings") is not None:
+        settings = validate_agent_settings(body["agent_settings"], context=context)
+        body = {**body, "agent": settings.create_agent(), "agent_settings": None}
+    request = StartConversationRequest.model_validate(body, context=context)
+
+    try:
+        settings = await asyncio.to_thread(get_settings_store(config).load)
+    except (OSError, PermissionError):
+        settings = None
+    settings = settings or PersistedSettings()
+    launched = None
+    if request.agent_profile_id is not None:
+        agent, launched, allowed = await asyncio.to_thread(
+            _resolve_agent_from_profile,
+            request.agent_profile_id,
+            config.cipher,
+            settings.agent_settings.mcp_config,
+            acp_skill_sourcing=config.acp_skill_sourcing,
+        )
+        secrets = request.secrets
+        if allowed is not None:
+            secrets = {
+                name: value for name, value in secrets.items() if name in allowed
+            }
+        request = request.model_copy(
+            update={"agent": agent, "agent_profile_id": None, "secrets": secrets}
+        )
+
+    context_settings = settings.agent_settings.agent_context
+    if context_settings is not None and context_settings.load_memory:
+        request = request.model_copy(update={"agent": _with_load_memory(request.agent)})
+    request = request.model_copy(
+        update={
+            "agent": await asyncio.to_thread(_materialize_agent_context, request.agent),
+            "secrets": await asyncio.to_thread(materialize_secrets, request.secrets),
+        }
+    )
+    return request, launched
+
+
+def serialize_start(
+    request: StartConversationRequest, identity: RuntimeIdentity
+) -> dict[str, Any]:
+    payload = request.model_dump(
+        mode="json", context={"cipher": identity.cipher}, exclude={"agent_profile_id"}
+    )
+    payload["secrets_encrypted"] = True
+    return payload