openhands-agent-server 1.44.1__tar.gz → 1.45.0__tar.gz

{openhands_agent_server-1.44.1 → openhands_agent_server-1.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.44.1
+Version: 1.45.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.44.1 → openhands_agent_server-1.45.0}/openhands/agent_server/api.py

@@ -39,7 +39,6 @@ from openhands.agent_server.dependencies import (
     check_workspace_session,
 )
 from openhands.agent_server.desktop_router import desktop_router
-from openhands.agent_server.desktop_service import get_desktop_service
 from openhands.agent_server.event_router import event_router
 from openhands.agent_server.file_router import file_router
 from openhands.agent_server.git_router import git_router
@@ -66,6 +65,7 @@ from openhands.agent_server.server_details_router import (
     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
@@ -167,7 +167,6 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
             emit_server_started()
 
         vscode_service = get_vscode_service()
-        desktop_service = get_desktop_service()
         tool_preload_service = get_tool_preload_service()
 
         # Define async functions for starting each service
@@ -183,18 +182,6 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
             else:
                 logger.info("VSCode service is disabled")
 
-        async def start_desktop_service():
-            if desktop_service is not None:
-                desktop_started = await desktop_service.start()
-                if desktop_started:
-                    logger.info("Desktop service started successfully")
-                else:
-                    logger.warning(
-                        "Desktop service failed to start, continuing without desktop"
-                    )
-            else:
-                logger.info("Desktop service is disabled")
-
         async def start_tool_preload_service():
             if tool_preload_service is not None:
                 tool_preload_started = await tool_preload_service.start()
@@ -208,7 +195,6 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
         # Start all services concurrently
         results = await asyncio.gather(
             start_vscode_service(),
-            start_desktop_service(),
             start_tool_preload_service(),
             return_exceptions=True,
         )
@@ -231,17 +217,12 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
                 if vscode_service is not None:
                     await vscode_service.stop()
 
-            async def stop_desktop_service():
-                if desktop_service is not None:
-                    await desktop_service.stop()
-
             async def stop_tool_preload_service():
                 if tool_preload_service is not None:
                     await tool_preload_service.stop()
 
             await asyncio.gather(
                 stop_vscode_service(),
-                stop_desktop_service(),
                 stop_tool_preload_service(),
                 return_exceptions=True,
             )
@@ -471,6 +452,8 @@ def _add_api_routes(app: FastAPI) -> None:
 
     app.include_router(sockets_router)
 
+    app.include_router(session_router)
+
 
 def _setup_static_files(app: FastAPI, config: Config) -> None:
     """Set up static file serving and root redirect if configured.

{openhands_agent_server-1.44.1 → openhands_agent_server-1.45.0}/openhands/agent_server/canvas_extensions/installed.py

@@ -35,6 +35,7 @@ from openhands.sdk.extensions.installation import (
     InstallationMetadata,
 )
 from openhands.sdk.extensions.installation.manager import DEFAULT_CACHE_DIR
+from openhands.sdk.utils.path import get_user_persistence_dir
 
 
 # Matches the InstalledPluginInfo naming convention.
@@ -43,7 +44,7 @@ InstalledCanvasExtensionInfo = InstallationInfo
 
 def get_installed_canvas_extensions_dir() -> Path:
     """Get the default directory for installed canvas extensions."""
-    return Path.home() / ".openhands" / "canvas-extensions" / "installed"
+    return get_user_persistence_dir() / "canvas-extensions" / "installed"
 
 
 class CanvasExtensionInstallationInterface(

{openhands_agent_server-1.44.1 → openhands_agent_server-1.45.0}/openhands/agent_server/config.py

@@ -319,10 +319,6 @@ class Config(BaseModel):
             "For example, '/{runtime_id}/vscode' when using path-based routing."
         ),
     )
-    enable_vnc: bool = Field(
-        default=False,
-        description="Whether to enable VNC desktop functionality",
-    )
     preload_tools: bool = Field(
         default=True,
         description="Whether to preload tools",

{openhands_agent_server-1.44.1 → openhands_agent_server-1.45.0}/openhands/agent_server/conversation_service.py

@@ -130,6 +130,22 @@ def _append_system_message_suffix(agent: AgentBase, addition: str) -> AgentBase:
     return agent.model_copy(update={"agent_context": updated_context})
 
 
+def _with_load_memory(agent: AgentBase) -> AgentBase:
+    """Stamp the global persistent-memory preference onto an agent.
+
+    ``load_memory`` is a user-level setting, not part of any agent, profile or
+    client payload, so it is applied here regardless of how the agent reached
+    the request.
+    """
+    # current_datetime stays suppressed on a synthesized context: a null
+    # agent_context means "no prompt context", and ACPAgent._render_suffix
+    # relies on that to keep a <CURRENT_DATETIME> block out of the prompt.
+    context = agent.agent_context or AgentContext(current_datetime=None)
+    return agent.model_copy(
+        update={"agent_context": context.model_copy(update={"load_memory": True})}
+    )
+
+
 def _has_git_remote(repo_root: Path, remote: str = "origin") -> bool:
     try:
         run_git_command(["git", "remote", "get-url", remote], repo_root)
@@ -335,7 +351,6 @@ def _resolve_agent_from_profile(
     profile_id: "UUID",
     cipher: "Cipher | None",
     mcp_config: "dict[str, MCPServer]",
-    load_memory: bool = False,
     acp_skill_sourcing: ACPSkillSourcing = "native",
 ) -> "tuple[AgentBase, LaunchedAgentProfile]":
     """Load and resolve an agent profile by id, returning the built agent + provenance.
@@ -347,11 +362,6 @@ def _resolve_agent_from_profile(
             server's cipher.  Passed explicitly so this free function never
             touches the settings-store singleton (which may not have been
             initialised with the correct cipher yet).
-        load_memory: The user's global persistent-memory preference
-            (``agent_settings.agent_context.load_memory``).  An ``AgentProfile``
-            has no ``agent_context`` field, so the preference cannot ride the
-            profile — it is stamped onto the resolved agent below, else a
-            profile-launched conversation would silently ignore the setting.
         acp_skill_sourcing: This deployment's ACP skill policy
             (``Config.acp_skill_sourcing``).  Decides whether an ACP profile is
             resolved with the server's managed skill catalog or with none.
@@ -435,15 +445,7 @@ def _resolve_agent_from_profile(
         agent = agent.model_copy(
             update={"tools": [*agent.tools, Tool(name=BROWSER_TOOL_NAME)]}
         )
-    # Persistent memory is a global user preference, not a profile field, so it
-    # is carried across the profile-resolution boundary the same way the global
-    # ``mcp_config`` is. Left untouched when off, so the resolved agent stays
-    # byte-identical for everyone who hasn't opted in.
-    if load_memory:
-        context = agent.agent_context or AgentContext()
-        agent = agent.model_copy(
-            update={"agent_context": context.model_copy(update={"load_memory": True})}
-        )
+
     launched = LaunchedAgentProfile(
         agent_profile_id=profile.id,
         revision=profile.revision,
@@ -1561,32 +1563,56 @@ class ConversationService:
                     f"to a different workspace"
                 )
 
-        # Profile resolution 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.
+        # 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
-        if request.agent_profile_id is not None:
-            # get_settings_store() is safe here: get_instance() initialises the
-            # singleton with the server cipher before any conversation can start.
-            from openhands.agent_server.persistence import (
-                PersistedSettings,
-                get_settings_store,
+
+        from openhands.agent_server.persistence import (
+            PersistedSettings,
+            get_settings_store,
+        )
+
+        # get_settings_store() is safe here: get_instance() initialises the
+        # singleton with the server cipher before any conversation can start.
+        # FileSettingsStore.load re-raises PermissionError/OSError by design;
+        # now that every launch reads it, a bad file mode must not take down
+        # request shapes that need nothing from settings.
+        try:
+            settings = await asyncio.to_thread(
+                lambda: get_settings_store().load() or PersistedSettings()
+            )
+        except (PermissionError, OSError):
+            logger.warning(
+                "Cannot read settings; starting without the stored agent preferences",
+                exc_info=True,
             )
+            settings = PersistedSettings()
 
-            settings = get_settings_store().load() or PersistedSettings()
+        # ``ACPAgentSettings.agent_context`` is nullable, hence the guard.
+        stored_context = settings.agent_settings.agent_context
+        load_memory = bool(stored_context and stored_context.load_memory)
+
+        if request.agent_profile_id is not None:
             mcp_config = settings.agent_settings.mcp_config
-            # ``ACPAgentSettings.agent_context`` is nullable, hence the guard.
-            stored_context = settings.agent_settings.agent_context
             resolved_agent, launched_agent_profile = await asyncio.to_thread(
                 _resolve_agent_from_profile,
                 request.agent_profile_id,
                 self.cipher,
                 mcp_config,
-                load_memory=bool(stored_context and stored_context.load_memory),
                 acp_skill_sourcing=self.acp_skill_sourcing,
             )
             request = request.model_copy(update={"agent": resolved_agent})
 
+        # Applied unconditionally: a serialized agent always carries
+        # ``load_memory`` (model_dump emits defaults), so there is no way to
+        # tell a deliberate ``false`` from an echoed one. Opting a single
+        # conversation out needs a tri-state field; tracked separately.
+        if load_memory and request.agent is not None:
+            request = request.model_copy(
+                update={"agent": _with_load_memory(request.agent)}
+            )
+
         request = request.model_copy(
             update={
                 "agent": _apply_acp_skill_sourcing(

openhands_agent_server-1.45.0/openhands/agent_server/desktop_router.py

@@ -0,0 +1,28 @@
+"""Desktop router for agent server API endpoints."""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+
+desktop_router = APIRouter(prefix="/desktop", tags=["Desktop"])
+
+
+class DesktopUrlResponse(BaseModel):
+    """Response model for Desktop URL."""
+
+    url: str | None
+
+
+@desktop_router.get("/url", response_model=DesktopUrlResponse, deprecated=True)
+async def get_desktop_url(
+    base_url: str = "http://localhost:8002",  # noqa: ARG001
+) -> DesktopUrlResponse:
+    """Deprecated since v1.44.1 and scheduled for removal in v1.49.0.
+
+    The VNC/desktop stack has been removed; this always returns 503, the
+    same response every deployment has always gotten since VNC defaults off.
+    """
+    raise HTTPException(
+        status_code=503,
+        detail="Desktop is disabled. VNC/desktop support has been removed.",
+    )

{openhands_agent_server-1.44.1 → openhands_agent_server-1.45.0}/openhands/agent_server/docker/Dockerfile

@@ -13,12 +13,18 @@ ARG PORT=8000
 # to bundle google-cloud-aiplatform so the resulting binary supports
 # `vertex_ai/*` partner models (MiniMax, Qwen, Kimi MaaS endpoints).
 ARG ENABLE_VERTEX=0
-# Comma-separated ACP provider keys (see ACP_PROVIDERS in
-# openhands-sdk/openhands/sdk/settings/acp_providers.py) to bake into the
+# Comma-separated ACP provider keys (see ACP_INSTALL_CATALOG in
+# openhands-sdk/openhands/sdk/settings/acp_install_catalog.py) to bake into the
 # acp-providers stage below. The default reproduces the full provider set
-# shipped today; an unknown key fails the build rather than silently
-# installing nothing.
+# shipped today (DEFAULT_PREINSTALLED_ACP_PROVIDERS); an unknown key fails the
+# build rather than silently installing nothing.
 ARG INSTALL_ACP_PROVIDERS=claude-code,codex,gemini-cli
+# Comma-separated capability keys to include in the `base-image` stage below
+# (`base-image-minimal` is unaffected). The default reproduces today's full
+# contents; an unknown key fails the build. The GitHub CLI is expected to
+# join this list later (see OpenHands/software-agent-sdk#4645) — the parsing
+# below is written so that's a one-case addition, not a signature change.
+ARG INSTALL_CAPABILITIES=vscode,browser,docker
 
 ####################################################################################
 # Builder (source mode)
@@ -96,6 +102,11 @@ RUN test -x /agent-server/dist/openhands-agent-server
 # Failures here are fatal: there is no per-BASE_IMAGE fallback for a broken build of
 # the shared payload itself (see the compatibility probe in base-image-minimal for
 # the per-target-image fallback).
+#
+# The Node pin below is a floor, not a preference: this stage installs every
+# selected provider under one runtime, so it has to clear the highest
+# `min_node_version` in ACP_INSTALL_CATALOG (asserted by
+# tests/cross/test_agent_server_build_metadata.py).
 ####################################################################################
 FROM python:3.13-bookworm AS acp-providers
 ARG INSTALL_ACP_PROVIDERS
@@ -106,23 +117,17 @@ ARG INSTALL_ACP_PROVIDERS
 # parent, mirroring /agent-server's own top-level placement in the builder
 # stage above.
 ENV ACP_NODE_DIR=/acp-node
+# The catalog module is dependency-free (stdlib only), so it can be COPYed
+# into this bare `python` image and run as-is — no pip install, and no need
+# to pull in the rest of the SDK source (which would break the zero-context
+# fast path `build.py` uses for the `base-image-minimal` target). Adding an
+# npm provider is a catalog edit only; this stage never needs to change.
+COPY openhands-sdk/openhands/sdk/settings/acp_install_catalog.py /tmp/acp_install_catalog.py
 RUN set -eux; \
     ACP_WRAPPER_DIR=/opt/acp-wrappers; \
     mkdir -p "$ACP_NODE_DIR" "$ACP_WRAPPER_DIR"; \
-    PACKAGES=""; \
-    WRAPPER_BINS=""; \
-    for provider in $(echo "$INSTALL_ACP_PROVIDERS" | tr ',' ' '); do \
-      case "$provider" in \
-        claude-code) PACKAGES="$PACKAGES @agentclientprotocol/claude-agent-acp@0.63.0"; \
-          WRAPPER_BINS="$WRAPPER_BINS claude-agent-acp";; \
-        codex) PACKAGES="$PACKAGES @agentclientprotocol/codex-acp@1.1.7"; \
-          WRAPPER_BINS="$WRAPPER_BINS codex-acp";; \
-        gemini-cli) PACKAGES="$PACKAGES @google/gemini-cli@0.46.0"; \
-          WRAPPER_BINS="$WRAPPER_BINS gemini";; \
-        *) echo "Unknown ACP provider '$provider' in INSTALL_ACP_PROVIDERS" \
-             "(expected one of: claude-code, codex, gemini-cli)" >&2; exit 1;; \
-      esac; \
-    done; \
+    PLAN=$(python3 /tmp/acp_install_catalog.py "$INSTALL_ACP_PROVIDERS") || exit 1; \
+    eval "$PLAN"; \
     if [ -z "$PACKAGES" ]; then \
       echo "INSTALL_ACP_PROVIDERS is empty; no ACP providers will be installed"; \
       exit 0; \
@@ -133,29 +138,38 @@ RUN set -eux; \
     rm -rf /var/lib/apt/lists/*; \
     ARCH=$(uname -m); \
     case "$ARCH" in \
-      x86_64|amd64) NARCH=x64; NODE_SHA256=69b09dba5c8dcb05c4e4273a4340db1005abeafe3927efda2bc5b249e80437ec;; \
-      aarch64|arm64) NARCH=arm64; NODE_SHA256=08bfbf538bad0e8cbb0269f0173cca28d705874a67a22f60b57d99dc99e30050;; \
+      x86_64|amd64) NARCH=x64; NODE_SHA256=c0649af18e6a24f6fe5535a3e86b341dd49a8e71117c8b68bde973ef834f16f2;; \
+      aarch64|arm64) NARCH=arm64; NODE_SHA256=0b2d9f564b6594222a62c82e1df2efe119dd4a4aff29644f4dd325bf360b6bcc;; \
       *) echo "Unsupported architecture for ACP providers: '$ARCH'" >&2; exit 1;; \
     esac; \
-    NODE_TARBALL="/tmp/node-v22.14.0-linux-${NARCH}.tar.xz"; \
+    NODE_TARBALL="/tmp/node-v22.19.0-linux-${NARCH}.tar.xz"; \
     curl -fsSL --retry 5 --retry-delay 2 --retry-connrefused \
-        "https://nodejs.org/dist/v22.14.0/node-v22.14.0-linux-${NARCH}.tar.xz" -o "$NODE_TARBALL"; \
+        "https://nodejs.org/dist/v22.19.0/node-v22.19.0-linux-${NARCH}.tar.xz" -o "$NODE_TARBALL"; \
     echo "$NODE_SHA256  $NODE_TARBALL" | sha256sum -c -; \
     tar -xJ --strip-components=1 -C "$ACP_NODE_DIR" -f "$NODE_TARBALL"; \
     rm -f "$NODE_TARBALL"; \
     "$ACP_NODE_DIR/bin/node" --version; \
     PATH="$ACP_NODE_DIR/bin:$PATH" "$ACP_NODE_DIR/bin/npm" install -g $PACKAGES; \
     for bin in $WRAPPER_BINS; do \
+      # Fail the build rather than ship a wrapper that execs a missing target:
+      # a wrong binary_name is otherwise invisible until someone launches the
+      # provider, since the wrapper is only a shell script we chmod +x.
+      [ -x "$ACP_NODE_DIR/bin/$bin" ] || { \
+        echo "ACP wrapper target not installed: $ACP_NODE_DIR/bin/$bin" >&2; \
+        echo "(check binary_name in acp_install_catalog.py against the package's npm bin)" >&2; \
+        exit 1; \
+      }; \
       printf '#!/bin/sh\nPATH="%s/bin:$PATH" exec "%s/bin/%s" "$@"\n' \
         "$ACP_NODE_DIR" "$ACP_NODE_DIR" "$bin" \
         > "$ACP_WRAPPER_DIR/$bin"; \
       chmod +x "$ACP_WRAPPER_DIR/$bin"; \
-    done
+    done; \
+    printf '%s\n' $WRAPPER_BINS > "$ACP_NODE_DIR/acp-wrappers.txt"
 
 ####################################################################################
 # Base image (minimal)
 # It includes only basic packages and the UV runtime.
-# No Docker, no VNC, no Desktop, no VSCode Web.
+# No Docker, no browser, no VSCode Web.
 # Suitable for running in headless/evaluation mode.
 ####################################################################################
 FROM ${BASE_IMAGE} AS base-image-minimal
@@ -224,7 +238,7 @@ RUN set -eux; \
     mkdir -p /workspace/project; \
     chown -R "${USERNAME}:${USERNAME}" /workspace
 
-# Install ACP servers for ACPAgent support (Claude Code, Codex, Gemini CLI).
+# Install the ACP servers selected by INSTALL_ACP_PROVIDERS (see the stage above).
 # The payload itself (Node.js 22 + the ACP npm packages, under $ACP_NODE_DIR) is
 # built once in the acp-providers stage above, independent of BASE_IMAGE, and
 # copied in here so the layer is byte-identical across every base image it lands
@@ -243,11 +257,16 @@ COPY --from=acp-providers /opt/acp-wrappers/. /usr/local/bin/
 # glibc-modern stage, so a failure here means "incompatible with this specific
 # BASE_IMAGE", not "the ACP install failed". When that happens we remove the
 # copied payload and wrappers so the rest of the build (and non-ACP agents)
-# still work, rather than leaving binaries in place that cannot execute.
+# still work, rather than leaving binaries in place that cannot execute. The
+# wrapper names come from the manifest the acp-providers stage wrote, so this
+# tracks INSTALL_ACP_PROVIDERS instead of a list that goes stale per provider.
 RUN if ! "$ACP_NODE_DIR/bin/node" --version >/dev/null 2>&1; then \
       echo "Warning: ACP Node 22 runtime is not compatible with this base image (likely older glibc or musl libc); ACP agents will not be available" >&2; \
+      if [ -f "$ACP_NODE_DIR/acp-wrappers.txt" ]; then \
+        while read -r bin; do rm -f "/usr/local/bin/$bin"; done \
+          < "$ACP_NODE_DIR/acp-wrappers.txt"; \
+      fi; \
       rm -rf "$ACP_NODE_DIR"/*; \
-      rm -f /usr/local/bin/claude-agent-acp /usr/local/bin/codex-acp /usr/local/bin/gemini; \
     fi
 
 # Configure Claude Code managed settings for headless operation:
@@ -264,7 +283,6 @@ WORKDIR /
 # Locale settings required for libtmux to work with PyInstaller builds
 ENV LC_ALL=C.UTF-8
 ENV LANG=C.UTF-8
-ENV OH_ENABLE_VNC=false
 ENV LOG_JSON=true
 # The ACP CLIs run without the user's host home here, so OpenHands supplies the
 # managed skill catalog they cannot read for themselves (#4019).
@@ -273,20 +291,49 @@ EXPOSE ${PORT}
 
 ####################################################################################
 # Base image (full)
-# It includes additional Docker, VNC, Desktop, and VSCode Web.
+# It includes additional Docker, browser, and VSCode Web.
 ####################################################################################
 FROM base-image-minimal AS base-image
 ARG USERNAME
+ARG INSTALL_CAPABILITIES
 
 USER root
+
+# Fail fast on a typo'd capability name before spending any time on the
+# installs below (each block only checks for ITS OWN keyword's presence, so
+# an unrecognized one would otherwise be silently ignored rather than erroring).
+RUN set -eux; \
+    for capability in $(echo "$INSTALL_CAPABILITIES" | tr ',' ' '); do \
+      case "$capability" in \
+        vscode|browser|docker) ;; \
+        *) echo "Unknown capability '$capability' in INSTALL_CAPABILITIES" \
+             "(expected one of: vscode, browser, docker)" >&2; exit 1;; \
+      esac; \
+    done
+
 # --- VSCode Web ---
+# EDITOR/VISUAL/GIT_EDITOR/OPENVSCODE_SERVER_ROOT are declared unconditionally:
+# nothing execs `code` unless VSCode Web itself is running, so a dangling
+# path when `vscode` is excluded is harmless (same reasoning as CHROME_BIN
+# below, applied to VSCode).
 ENV EDITOR=code \
     VISUAL=code \
     GIT_EDITOR="code --wait" \
     OPENVSCODE_SERVER_ROOT=/openhands/.openvscode-server
 ARG RELEASE_TAG="openvscode-server-v1.98.2"
 ARG RELEASE_ORG="gitpod-io"
+# The --mount=from=builder on the extensions RUN below is unconditional at
+# the Dockerfile level, so BuildKit still builds the full `builder` stage
+# (the entire SDK venv) even when `vscode` is excluded from
+# INSTALL_CAPABILITIES — the case check inside each RUN only decides what
+# lands in THIS image, not what gets built as a dependency. Excluding vscode
+# shrinks the result, not the build time.
 RUN set -eux; \
+    case ",$INSTALL_CAPABILITIES," in \
+      *,vscode,*) ;; \
+      *) echo "INSTALL_CAPABILITIES excludes vscode; skipping OpenVSCode Server"; exit 0;; \
+    esac; \
+    \
     # Create necessary directories
     mkdir -p $(dirname ${OPENVSCODE_SERVER_ROOT}); \
     \
@@ -311,13 +358,31 @@ RUN set -eux; \
     # Set proper ownership
     chown -R ${USERNAME}:${USERNAME} ${OPENVSCODE_SERVER_ROOT}
 
-
-# Include VSCode extensions alongside the server so targets inheriting base-image
-# implicitly get the extensions; minimal images (without VSCode) won't.
-COPY --chown=${USERNAME}:${USERNAME} --from=builder /agent-server/openhands-agent-server/openhands/agent_server/vscode_extensions ${OPENVSCODE_SERVER_ROOT}/extensions
+# Kept as its own RUN, separate from the tarball download above: extensions
+# are actively-edited local source (unlike the pinned release tarball), so
+# splitting them keeps an extension-only change from invalidating the ~100MB
+# download's cache layer.
+RUN --mount=type=bind,from=builder,source=/agent-server/openhands-agent-server/openhands/agent_server/vscode_extensions,target=/tmp/vscode_extensions \
+    set -eux; \
+    case ",$INSTALL_CAPABILITIES," in \
+      *,vscode,*) ;; \
+      *) exit 0;; \
+    esac; \
+    \
+    # Trailing slashes matter: OpenVSCode Server's tarball already ships its
+    # own extensions/ dir, so a bare `cp -r src dst` would nest src under the
+    # existing dst instead of merging into it the way `COPY` does.
+    mkdir -p ${OPENVSCODE_SERVER_ROOT}/extensions; \
+    cp -r /tmp/vscode_extensions/. ${OPENVSCODE_SERVER_ROOT}/extensions/; \
+    chown -R ${USERNAME}:${USERNAME} ${OPENVSCODE_SERVER_ROOT}/extensions
 
 # --- Docker ---
 RUN set -eux; \
+    case ",$INSTALL_CAPABILITIES," in \
+      *,docker,*) ;; \
+      *) echo "INSTALL_CAPABILITIES excludes docker; skipping Docker Engine"; exit 0;; \
+    esac; \
+    \
     # Determine OS type and install Docker accordingly
     if grep -q "ubuntu" /etc/os-release; then \
         # Handle Ubuntu
@@ -336,10 +401,10 @@ RUN set -eux; \
     apt-get update; \
     apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin; \
     apt-get clean; \
-    rm -rf /var/lib/apt/lists/*
-
-# Configure Docker daemon with MTU 1450 to prevent packet fragmentation issues
-RUN mkdir -p /etc/docker && \
+    rm -rf /var/lib/apt/lists/*; \
+    \
+    # Configure Docker daemon with MTU 1450 to prevent packet fragmentation issues
+    mkdir -p /etc/docker; \
     echo '{"mtu": 1450}' > /etc/docker/daemon.json
 
 # --- GitHub CLI ---
@@ -355,36 +420,36 @@ RUN set -eux; \
     apt-get clean; \
     rm -rf /var/lib/apt/lists/*
 
-# --- VNC + Desktop + noVNC ---
-RUN set -eux; \
-  apt-get update; \
-  apt-get install -y --no-install-recommends \
-    # GUI bits (remove entirely if headless)
-    tigervnc-standalone-server xfce4 dbus-x11 novnc websockify \
-    # Browser
-    $(if grep -q "ubuntu" /etc/os-release; then echo "chromium-browser"; else echo "chromium"; fi); \
-  apt-get clean; rm -rf /var/lib/apt/lists/*
-
-ENV NOVNC_WEB=/usr/share/novnc \
-    NOVNC_PORT=8002 \
-    DISPLAY=:1 \
-    VNC_GEOMETRY=1280x800 \
-    CHROME_BIN=/usr/bin/chromium \
+# --- Browser ---
+# Chromium for BrowserToolSet. Selected by the `browser` capability.
+ENV CHROME_BIN=/usr/bin/chromium \
     PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium \
     CHROMIUM_FLAGS="--no-sandbox --disable-dev-shm-usage --disable-gpu"
 
-RUN chown -R ${USERNAME}:${USERNAME} ${NOVNC_WEB}
-# Override default XFCE wallpaper
-COPY --chown=${USERNAME}:${USERNAME} openhands-agent-server/openhands/agent_server/docker/wallpaper.svg /usr/share/backgrounds/xfce/xfce-shapes.svg
+# CHROME_BIN/PUPPETEER_EXECUTABLE_PATH above are declared unconditionally
+# regardless of which capabilities are selected. Nothing in this repo trusts
+# them as an availability signal — browser_use's chromium detection
+# (openhands-tools/openhands/tools/browser_use/impl.py) does its own filesystem
+# probe of standard install paths — so when `browser` is excluded these simply
+# point at a path that doesn't exist, rather than causing a false "available"
+# signal downstream.
+RUN set -eux; \
+    case ",$INSTALL_CAPABILITIES," in \
+      *,browser,*) \
+        apt-get update; \
+        apt-get install -y --no-install-recommends \
+          "$(if grep -q "ubuntu" /etc/os-release; then echo "chromium-browser"; else echo "chromium"; fi)"; \
+        apt-get clean; rm -rf /var/lib/apt/lists/*; \
+        ;; \
+    esac
 
 USER ${USERNAME}
 WORKDIR /
-ENV OH_ENABLE_VNC=false
 ENV LOG_JSON=true
 # The ACP CLIs run without the user's host home here, so OpenHands supplies the
 # managed skill catalog they cannot read for themselves (#4019).
 ENV OH_ACP_SKILL_SOURCING=openhands_managed
-EXPOSE ${PORT} ${NOVNC_PORT}
+EXPOSE ${PORT}
 
 
 ####################################################################################