openhands-agent-server 1.40.0__tar.gz → 1.41.0__tar.gz

{openhands_agent_server-1.40.0 → openhands_agent_server-1.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.40.0
+Version: 1.41.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.40.0 → openhands_agent_server-1.41.0}/openhands/agent_server/_secrets_exposure.py

@@ -120,3 +120,22 @@ def translate_missing_cipher() -> Iterator[None]:
                 ),
             )
         raise
+
+
+@contextmanager
+def store_errors() -> Iterator[None]:
+    """Map profile-store errors (``LLMProfileStore``/``AgentProfileStore``) to
+    HTTP responses. Shared by the settings, profiles, and agent-profiles
+    routers."""
+    try:
+        yield
+    except TimeoutError:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Profile store is busy. Please retry.",
+        )
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        )

{openhands_agent_server-1.40.0 → openhands_agent_server-1.41.0}/openhands/agent_server/agent_profiles_router.py

@@ -12,14 +12,16 @@ MCP references and returns :class:`~openhands.sdk.profiles.AgentProfileDiagnosti
 """
 
 import asyncio
-from collections.abc import Iterator
-from contextlib import contextmanager
 from typing import Annotated, Any
 
 from fastapi import APIRouter, HTTPException, Path, Request, status
 from pydantic import BaseModel, Field, ValidationError
 
-from openhands.agent_server._secrets_exposure import get_cipher, get_config
+from openhands.agent_server._secrets_exposure import (
+    get_cipher,
+    get_config,
+    store_errors,
+)
 from openhands.agent_server.persistence import (
     PersistedSettings,
     get_agent_profile_store,
@@ -105,25 +107,6 @@ class RenameAgentProfileRequest(BaseModel):
     )
 
 
-@contextmanager
-def _store_errors() -> Iterator[None]:
-    """Map ``AgentProfileStore`` errors to HTTP responses.
-
-    Mirrors ``profiles_router._store_errors``: ``TimeoutError`` and
-    ``ValueError`` only. ``FileNotFoundError`` / ``FileExistsError`` are handled
-    inline per-endpoint so each gets a clean, resource-specific message.
-    """
-    try:
-        yield
-    except TimeoutError:
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail="Agent profile store is busy. Please retry.",
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
 def _llm_has_real_config(llm: LLM) -> bool:
     """True when ``llm`` carries real, user-provided configuration.
 
@@ -173,7 +156,7 @@ def _seed_default_llm_profile(llm: LLM, cipher: Cipher | None) -> str:
     silently clobber it.
     """
     llm_store = get_llm_profile_store()
-    with _store_errors():
+    with store_errors():
         try:
             llm_store.load(SEED_PROFILE_NAME, cipher=cipher)
             return SEED_PROFILE_NAME
@@ -227,7 +210,7 @@ def _seed_default_profile(
     The lock spans empty-check + save + pointer write so concurrent first
     requests seed exactly once and the pointer matches the persisted id.
     """
-    with _store_errors(), store.lock():
+    with store_errors(), store.lock():
         # Double-checked under the lock: a concurrent first request may have
         # already seeded (the outer emptiness check in the list endpoint is
         # unlocked).
@@ -261,7 +244,7 @@ def _seed_default_profile(
 
 def _summary_id_for_name(store: AgentProfileStore, name: str) -> str | None:
     """Return the stable id of the profile stored under ``name``, if present."""
-    with _store_errors():
+    with store_errors():
         for summary in store.list_summaries():
             if summary.get("name") == name:
                 sid = summary.get("id")
@@ -282,14 +265,14 @@ async def list_agent_profiles(request: Request) -> AgentProfileListResponse:
     settings = settings_store.load() or PersistedSettings()
 
     store = get_agent_profile_store()
-    with _store_errors():
+    with store_errors():
         existing = store.list()
 
     if not existing and settings.active_agent_profile_id is None:
         _seed_default_profile(store, request, settings, get_cipher(request))
         settings = settings_store.load() or settings
 
-    with _store_errors():
+    with store_errors():
         summaries = store.list_summaries()
 
     return AgentProfileListResponse(
@@ -308,7 +291,7 @@ async def get_agent_profile(name: ProfileName) -> AgentProfileDetailResponse:
     """
     store = get_agent_profile_store()
     try:
-        with _store_errors():
+        with store_errors():
             profile = store.load(name)
     except FileNotFoundError:
         raise HTTPException(
@@ -361,7 +344,7 @@ async def save_agent_profile(
     # holds the store lock across read + mint + save so two concurrent creates
     # of the same new name can't both mint an id and clobber each other.
     try:
-        with _store_errors():
+        with store_errors():
             save_profile_preserving_identity(
                 store, profile, max_profiles=MAX_AGENT_PROFILES
             )
@@ -392,7 +375,7 @@ async def delete_agent_profile(
     store = get_agent_profile_store()
     deleted_id = _summary_id_for_name(store, name)
 
-    with _store_errors():
+    with store_errors():
         store.delete(name)
 
     if deleted_id is not None:
@@ -428,7 +411,7 @@ async def rename_agent_profile(
     """
     store = get_agent_profile_store()
     try:
-        with _store_errors():
+        with store_errors():
             store.rename(name, body.new_name)
     except FileNotFoundError:
         raise HTTPException(
@@ -462,7 +445,7 @@ async def activate_agent_profile(
     creation-time-only contract). Returns 404 if no stored profile has that id.
     """
     store = get_agent_profile_store()
-    with _store_errors():
+    with store_errors():
         known_ids = {
             str(s["id"]) for s in store.list_summaries() if s.get("id") is not None
         }
@@ -515,7 +498,7 @@ async def materialize_agent_profile(
     """
     store = get_agent_profile_store()
     try:
-        with _store_errors():
+        with store_errors():
             profile = store.load(name)
     except FileNotFoundError:
         raise HTTPException(

openhands_agent_server-1.41.0/openhands/agent_server/canvas_extensions/__init__.py

@@ -0,0 +1,44 @@
+"""Canvas Extensions: installable UI bundles that contribute pages to Canvas."""
+
+from openhands.agent_server.canvas_extensions.installed import (
+    CanvasExtensionUpdateCheck,
+    InstalledCanvasExtensionInfo,
+    apply_canvas_extension_update,
+    check_canvas_extension_update,
+    disable_canvas_extension,
+    enable_canvas_extension,
+    get_installed_canvas_extension,
+    get_installed_canvas_extensions_dir,
+    install_canvas_extension,
+    list_installed_canvas_extensions,
+    load_installed_canvas_extensions,
+    uninstall_canvas_extension,
+)
+from openhands.agent_server.canvas_extensions.manifest import (
+    MANIFEST_FILENAME,
+    CanvasExtensionContributes,
+    CanvasExtensionManifest,
+    CanvasExtensionPage,
+    resolve_entrypoint,
+)
+
+
+__all__ = [
+    "CanvasExtensionManifest",
+    "CanvasExtensionContributes",
+    "CanvasExtensionPage",
+    "MANIFEST_FILENAME",
+    "resolve_entrypoint",
+    "InstalledCanvasExtensionInfo",
+    "install_canvas_extension",
+    "uninstall_canvas_extension",
+    "enable_canvas_extension",
+    "disable_canvas_extension",
+    "list_installed_canvas_extensions",
+    "load_installed_canvas_extensions",
+    "get_installed_canvas_extension",
+    "get_installed_canvas_extensions_dir",
+    "CanvasExtensionUpdateCheck",
+    "check_canvas_extension_update",
+    "apply_canvas_extension_update",
+]

openhands_agent_server-1.41.0/openhands/agent_server/canvas_extensions/installed.py

@@ -0,0 +1,403 @@
+"""Installed Canvas Extensions.
+
+Built on ``openhands.sdk.extensions.installation``, shared with Plugins/
+Skills, with two behaviors specific to this module:
+
+Disabled by default -- ``InstallationInfo.enabled`` defaults to ``True``
+and neither ``InstallationManager.install()`` nor its directory discovery
+override that for a new entry, so every write path that can create one
+forces ``enabled=False`` as an explicit post-write step.
+
+Staged refresh -- ``check``/``apply`` replace ``update()``/
+``install(force=True)``, which rmtree+copytree straight onto the live
+install path with no staging directory. ``check`` fetches and validates
+into ``.staging/`` without touching the active install; ``apply`` swaps it
+in via two atomic renames (POSIX can't atomically replace a non-empty
+directory in one rename), rolling back if the second fails.
+"""
+
+import os
+import shutil
+from pathlib import Path
+
+from pydantic import BaseModel, Field, ValidationError
+
+from openhands.agent_server.canvas_extensions.manifest import (
+    MANIFEST_FILENAME,
+    CanvasExtensionManifest,
+    resolve_entrypoint,
+)
+from openhands.sdk.extensions.fetch import fetch_with_resolution
+from openhands.sdk.extensions.installation import (
+    InstallationInfo,
+    InstallationInterface,
+    InstallationManager,
+    InstallationMetadata,
+)
+from openhands.sdk.extensions.installation.manager import DEFAULT_CACHE_DIR
+
+
+# Matches the InstalledPluginInfo naming convention.
+InstalledCanvasExtensionInfo = InstallationInfo
+
+
+def get_installed_canvas_extensions_dir() -> Path:
+    """Get the default directory for installed canvas extensions."""
+    return Path.home() / ".openhands" / "canvas-extensions" / "installed"
+
+
+class CanvasExtensionInstallationInterface(
+    InstallationInterface[CanvasExtensionManifest]
+):
+    @staticmethod
+    def load_from_dir(extension_dir: Path) -> CanvasExtensionManifest:
+        manifest_path = extension_dir / MANIFEST_FILENAME
+        manifest = CanvasExtensionManifest.model_validate_json(
+            manifest_path.read_text()
+        )
+        # Containment must hold too -- a parseable manifest alone isn't enough.
+        resolve_entrypoint(manifest, extension_dir)
+        return manifest
+
+
+def _resolve_installed_dir(installed_dir: Path | None) -> Path:
+    return (
+        installed_dir
+        if installed_dir is not None
+        else get_installed_canvas_extensions_dir()
+    )
+
+
+def _manager(installed_dir: Path) -> InstallationManager[CanvasExtensionManifest]:
+    return InstallationManager(
+        installation_dir=installed_dir,
+        installation_interface=CanvasExtensionInstallationInterface(),
+    )
+
+
+def _tracked_names(installed_dir: Path) -> set[str]:
+    """Names with a real, valid tracked entry, not just a metadata key.
+
+    A stale record with no matching directory must not count as "already
+    installed" -- otherwise a real install of that name would wrongly
+    inherit its state as if this were a force-reinstall.
+    """
+    if not installed_dir.exists():
+        return set()
+    metadata = InstallationMetadata.load_from_dir(installed_dir)
+    return {info.name for info in metadata.validate_tracked(installed_dir)}
+
+
+def _force_disable_new(
+    manager: InstallationManager[CanvasExtensionManifest],
+    info: InstallationInfo,
+    pre_existing: set[str],
+) -> InstallationInfo:
+    """Force a newly created tracked entry to ``enabled=False``.
+
+    ``pre_existing`` distinguishes a genuinely new entry from a
+    force-reinstall, whose prior enabled state is already preserved.
+    """
+    if info.name in pre_existing or not info.enabled:
+        return info
+    manager.disable(info.name)
+    info.enabled = False
+    return info
+
+
+def install_canvas_extension(
+    source: str,
+    ref: str | None = None,
+    repo_path: str | None = None,
+    installed_dir: Path | None = None,
+    force: bool = False,
+) -> InstalledCanvasExtensionInfo:
+    """Install a canvas extension from a source.
+
+    A newly created entry always lands disabled, regardless of what the
+    caller passes in.
+
+    Args:
+        source: ``"github:owner/repo"``, a git URL, or a local path.
+        ref: Optional branch, tag, or commit to install.
+        repo_path: Subdirectory within the repository (for monorepos).
+        installed_dir: Defaults to ``~/.openhands/canvas-extensions/installed/``.
+        force: If True, overwrite an existing installation.
+
+    Returns:
+        InstalledCanvasExtensionInfo for the installed extension.
+    """
+    installed_dir = _resolve_installed_dir(installed_dir)
+    manager = _manager(installed_dir)
+    pre_existing = _tracked_names(installed_dir)
+    info = manager.install(source, ref=ref, repo_path=repo_path, force=force)
+    return _force_disable_new(manager, info, pre_existing)
+
+
+def uninstall_canvas_extension(name: str, installed_dir: Path | None = None) -> bool:
+    """Uninstall a canvas extension by name.
+
+    Also drops any staged, not-yet-applied update for *name*, so refreshing
+    a since-uninstalled name never leaves an orphaned staging slot behind.
+
+    Returns:
+        True if uninstalled, False if it wasn't installed.
+    """
+    installed_dir = _resolve_installed_dir(installed_dir)
+    uninstalled = _manager(installed_dir).uninstall(name)
+    if uninstalled:
+        shutil.rmtree(_staging_root(installed_dir) / name, ignore_errors=True)
+    return uninstalled
+
+
+def enable_canvas_extension(name: str, installed_dir: Path | None = None) -> bool:
+    """Enable an installed canvas extension by name."""
+    return _manager(_resolve_installed_dir(installed_dir)).enable(name)
+
+
+def disable_canvas_extension(name: str, installed_dir: Path | None = None) -> bool:
+    """Disable an installed canvas extension by name."""
+    return _manager(_resolve_installed_dir(installed_dir)).disable(name)
+
+
+def list_installed_canvas_extensions(
+    installed_dir: Path | None = None,
+) -> list[InstalledCanvasExtensionInfo]:
+    """List all installed canvas extensions.
+
+    Self-healing like ``InstallationManager.list_installed()``; directories
+    discovered this way also land disabled.
+    """
+    installed_dir = _resolve_installed_dir(installed_dir)
+    manager = _manager(installed_dir)
+    pre_existing = _tracked_names(installed_dir)
+    infos = manager.list_installed()
+    return [_force_disable_new(manager, info, pre_existing) for info in infos]
+
+
+def load_installed_canvas_extensions(
+    installed_dir: Path | None = None,
+) -> list[CanvasExtensionManifest]:
+    """Load all enabled canvas extensions' manifests.
+
+    Runs through ``list_installed_canvas_extensions`` first so discovery
+    is force-disabled before anything is loaded -- see the module
+    docstring. Mirrors ``InstallationManager.load_installed()``'s own
+    enabled-filter/load logic on top of the corrected info list.
+    """
+    installed_dir = _resolve_installed_dir(installed_dir)
+    manager = _manager(installed_dir)
+    manifests: list[CanvasExtensionManifest] = []
+    for info in list_installed_canvas_extensions(installed_dir):
+        if not info.enabled:
+            continue
+        extension_path = installed_dir / info.name
+        if extension_path.exists():
+            manifests.append(
+                manager.installation_interface.load_from_dir(extension_path)
+            )
+    return manifests
+
+
+def get_installed_canvas_extension(
+    name: str, installed_dir: Path | None = None
+) -> InstalledCanvasExtensionInfo | None:
+    """Get information about a specific installed canvas extension."""
+    return _manager(_resolve_installed_dir(installed_dir)).get(name)
+
+
+class CanvasExtensionUpdateCheck(BaseModel):
+    """Result of ``check_canvas_extension_update``.
+
+    The active install is untouched; only ``.staging/`` is written. Pass
+    ``resolved_ref`` back to ``apply_canvas_extension_update`` to confirm
+    and swap this exact staged content into place.
+    """
+
+    requested_ref: str | None = Field(
+        description="Ref the staged fetch was resolved against"
+    )
+    resolved_ref: str | None = Field(
+        description="Commit SHA the staged content was resolved to"
+    )
+    validated: bool = Field(
+        description="Whether staged content passed validation; only True may be applied"
+    )
+
+
+def _staging_root(installed_dir: Path) -> Path:
+    return installed_dir / ".staging"
+
+
+def _staged_path(installed_dir: Path, name: str, resolved_ref: str | None) -> Path:
+    """Path to the staging slot for (*name*, *resolved_ref*).
+
+    *resolved_ref* is untrusted (``apply_canvas_extension_update`` takes it
+    as a caller-supplied argument), so it's rejected if it could escape the
+    staging directory -- same check as ``entrypoint`` in manifest.py.
+    """
+    if resolved_ref is not None and (
+        not resolved_ref
+        or resolved_ref.startswith("/")
+        or ".." in Path(resolved_ref).parts
+    ):
+        raise ValueError(f"Invalid resolved_ref: {resolved_ref!r}")
+    return _staging_root(installed_dir) / name / (resolved_ref or "local")
+
+
+def _stage_fetched_content(
+    installed_dir: Path, name: str, resolved_ref: str | None, fetched_path: Path
+) -> Path:
+    """Copy fetched content into a clean staging slot for *name*.
+
+    Clears any previously staged candidate first -- at most one is kept
+    per extension at a time.
+    """
+    slot_root = _staging_root(installed_dir) / name
+    shutil.rmtree(slot_root, ignore_errors=True)
+    staged_path = _staged_path(installed_dir, name, resolved_ref)
+    # symlinks=True: dereferencing here would copy a malicious symlink's
+    # target in as a plain file, defeating containment validation below.
+    shutil.copytree(fetched_path, staged_path, symlinks=True)
+    return staged_path
+
+
+def _load_validated_manifest(
+    staged_path: Path, expected_name: str
+) -> CanvasExtensionManifest:
+    """Load and validate a staged extension's manifest.
+
+    Raises if the manifest is malformed, its entrypoint escapes the package
+    root, or its name no longer matches *expected_name*.
+    """
+    manifest = CanvasExtensionInstallationInterface.load_from_dir(staged_path)
+    if manifest.name != expected_name:
+        raise ValueError(
+            f"Staged content for {expected_name!r} declares a different "
+            f"name {manifest.name!r}; refusing to treat it as an update"
+        )
+    return manifest
+
+
+def check_canvas_extension_update(
+    name: str, installed_dir: Path | None = None
+) -> CanvasExtensionUpdateCheck | None:
+    """Check for an update to *name*, staging and validating it.
+
+    Re-fetches the tracked source at its original ref (never "latest")
+    into ``.staging/``; the active install is untouched. See
+    ``apply_canvas_extension_update`` for the step that swaps it into
+    place.
+
+    Args:
+        name: Name of the installed extension to check.
+        installed_dir: Defaults to ``~/.openhands/canvas-extensions/installed/``.
+
+    Returns:
+        None if not installed, else a result -- only apply when ``validated``.
+
+    Raises:
+        ValueError: If *name* is not valid kebab-case.
+        ExtensionFetchError: If fetching the tracked source fails.
+    """
+    installed_dir = _resolve_installed_dir(installed_dir)
+    manager = _manager(installed_dir)
+    current_info = manager.get(name)
+    if current_info is None:
+        return None
+
+    fetched_path, resolved_ref = fetch_with_resolution(
+        source=current_info.source,
+        cache_dir=DEFAULT_CACHE_DIR,
+        ref=current_info.requested_ref,
+        repo_path=current_info.repo_path,
+        update=True,
+    )
+
+    staged_path = _stage_fetched_content(
+        installed_dir, name, resolved_ref, fetched_path
+    )
+    try:
+        _load_validated_manifest(staged_path, name)
+        validated = True
+    except (ValidationError, ValueError, OSError):
+        validated = False
+        shutil.rmtree(staged_path.parent, ignore_errors=True)
+
+    return CanvasExtensionUpdateCheck(
+        requested_ref=current_info.requested_ref,
+        resolved_ref=resolved_ref,
+        validated=validated,
+    )
+
+
+def apply_canvas_extension_update(
+    name: str,
+    resolved_ref: str | None,
+    enabled: bool,
+    installed_dir: Path | None = None,
+) -> InstalledCanvasExtensionInfo | None:
+    """Apply a previously checked and validated update.
+
+    *resolved_ref* must match a staged candidate already validated by
+    ``check_canvas_extension_update``, reconfirming what's being applied.
+    Atomically swaps staged content into the active install path;
+    *enabled* is always applied explicitly, never inherited.
+
+    Args:
+        name: Name of the installed extension to update.
+        resolved_ref: The ``resolved_ref`` from a prior, validated check.
+        enabled: Enabled state to apply to the new bundle.
+        installed_dir: Defaults to ``~/.openhands/canvas-extensions/installed/``.
+
+    Returns:
+        None if not installed, else the InstallationInfo for the new bundle.
+
+    Raises:
+        ValueError: If *name* is invalid, *resolved_ref* could escape the
+            staging directory, or no validated staged candidate matches it
+            -- call check first.
+    """
+    installed_dir = _resolve_installed_dir(installed_dir)
+    manager = _manager(installed_dir)
+    current_info = manager.get(name)
+    if current_info is None:
+        return None
+
+    staged_path = _staged_path(installed_dir, name, resolved_ref)
+    if not staged_path.is_dir():
+        raise ValueError(
+            f"No validated staged update found for {name!r} at ref "
+            f"{resolved_ref!r}. Call check_canvas_extension_update() first."
+        )
+    manifest = _load_validated_manifest(staged_path, name)
+
+    install_path = installed_dir / name
+    backup_path = _staging_root(installed_dir) / f"{name}.previous"
+    shutil.rmtree(backup_path, ignore_errors=True)
+
+    # POSIX rename() can't atomically replace a non-empty directory, so the
+    # active bundle moves aside first; roll back if the second rename fails.
+    os.replace(install_path, backup_path)
+    try:
+        os.replace(staged_path, install_path)
+    except OSError:
+        os.replace(backup_path, install_path)
+        raise
+    shutil.rmtree(backup_path, ignore_errors=True)
+    shutil.rmtree(_staging_root(installed_dir) / name, ignore_errors=True)
+
+    info = InstallationInfo.from_extension(
+        manifest,
+        source=current_info.source,
+        install_path=install_path,
+        requested_ref=current_info.requested_ref,
+        resolved_ref=resolved_ref,
+        repo_path=current_info.repo_path,
+    )
+    info.enabled = enabled
+
+    with manager.metadata_session as session:
+        session.extensions[name] = info
+
+    return info