Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
08f4625
fix(extensions): lock and atomically write installation metadata
vnktadithya Oct 7, 2026
275423f
fix(extensions): read installation metadata under the lock
vnktadithya Oct 9, 2026
6c8cb39
Merge branch 'main' into fix/installed-json-race-5496
vnktadithya Oct 9, 2026
26eabd5
Merge branch 'main' into fix/installed-json-race-5496
vnktadithya Oct 10, 2026
b3377bb
Merge branch 'main' into fix/installed-json-race-5496
vnktadithya Oct 11, 2026
06394f1
Merge branch 'main' into fix/installed-json-race-5496
vnktadithya Oct 12, 2026
b917f9f
fix(sdk): write installation metadata with owner-only permissions
vnktadithya Oct 14, 2026
3d65e49
Merge branch 'fix/installed-json-race-5496' of https://github.com/vnk…
vnktadithya Oct 14, 2026
8a66583
Merge remote-tracking branch 'upstream/main' into fix/installed-json-…
vnktadithya Nov 9, 2026
f02f638
Merge remote-tracking branch 'upstream/main' into fix/installed-json-…
vnktadithya Nov 10, 2026
6e922e3
fix(sdk): refuse to save over installation metadata that cannot be lo…
vnktadithya Nov 10, 2026
5c3c386
fix(sdk): read installation metadata without the lock; retry a blocke…
vnktadithya Nov 10, 2026
e88b6ff
fix(sdk): retry an unlocked metadata read that meets a replace on Win…
vnktadithya Nov 10, 2026
47dc234
fix(sdk): stage installs and swap them in under the metadata lock
vnktadithya Nov 10, 2026
0b9f406
fix(sdk): retry a blocked metadata replace or read every 10 ms
vnktadithya Nov 10, 2026
e724f2f
fix(agent-server): run lock-taking Canvas calls off the event loop
vnktadithya Nov 10, 2026
ebdf32b
fix(sdk): answer 503 when the installation metadata lock times out
vnktadithya Nov 11, 2026
84c832e
fix(sdk): keep the installation metadata file's mode on save
vnktadithya Nov 11, 2026
82c5320
fix(sdk): keep the user's ownership when root saves installation meta…
vnktadithya Nov 11, 2026
15d52e6
test(agent-server): stub the marketplace clone in the lock-timeout tests
vnktadithya Nov 11, 2026
ab876c0
fix(agent-server): decide which listed Canvas extensions are new unde…
vnktadithya Nov 12, 2026
59e9ad1
docs(sdk): describe the metadata save rule without its history
vnktadithya Nov 12, 2026
cf1a350
Merge upstream main (7435f4be9)
vnktadithya Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,16 @@
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
``install(force=True)``, which fetch and swap in one step, with nothing to
confirm in between. ``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
import tempfile
from contextlib import suppress
from pathlib import Path

Expand All @@ -34,12 +35,14 @@
InstallationInfo,
InstallationInterface,
InstallationManager,
InstallationMetadata,
)
from openhands.sdk.extensions.installation.manager import DEFAULT_CACHE_DIR
from openhands.sdk.logger import get_logger
from openhands.sdk.utils.path import get_user_persistence_dir


logger = get_logger(__name__)

# Matches the InstalledPluginInfo naming convention.
InstalledCanvasExtensionInfo = InstallationInfo

Expand Down Expand Up @@ -78,19 +81,6 @@ def _manager(installed_dir: Path) -> InstallationManager[CanvasExtensionManifest
)


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,
Expand Down Expand Up @@ -132,9 +122,14 @@ def install_canvas_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)
# Whether this replaced an installed extension is decided inside the
# install's own metadata session: a snapshot taken before the install
# can be made stale by a concurrent uninstall.
outcome = manager.install_with_outcome(
source, ref=ref, repo_path=repo_path, force=force
)
pre_existing = {outcome.info.name} if outcome.was_installed else set()
return _force_disable_new(manager, outcome.info, pre_existing)


def uninstall_canvas_extension(name: str, installed_dir: Path | None = None) -> bool:
Expand Down Expand Up @@ -172,9 +167,16 @@ def list_installed_canvas_extensions(
discovered this way also land disabled.
"""
installed_dir = _resolve_installed_dir(installed_dir)
if not installed_dir.exists():
return []
manager = _manager(installed_dir)
pre_existing = _tracked_names(installed_dir)
infos = manager.list_installed()
# Decided under the lock the listing takes: a reinstall swapping the
# directory in can't make an installed extension look new meanwhile.
with manager.metadata_session() as session:
pre_existing = {
info.name for info in session.metadata.validate_tracked(installed_dir)
}
infos = session.sync()
return [_force_disable_new(manager, info, pre_existing) for info in infos]


Expand Down Expand Up @@ -422,8 +424,7 @@ def apply_canvas_extension_update(
"""
installed_dir = _resolve_installed_dir(installed_dir)
manager = _manager(installed_dir)
current_info = manager.get(name)
if current_info is None:
if manager.get(name) is None:
return None

staged_path = _staged_path(installed_dir, name, resolved_ref)
Expand All @@ -435,31 +436,50 @@ def apply_canvas_extension_update(
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,
# A directory of its own per apply: the previous bundle is deleted after
# the lock is released, so a shared backup path could be cleared while
# another apply is between its renames.
backup_root = Path(
tempfile.mkdtemp(prefix=f"{name}.previous-", dir=_staging_root(installed_dir))
)
info.enabled = enabled

with manager.metadata_session as session:
session.extensions[name] = info
backup_path = backup_root / name
try:
# The swap and the metadata write share one session, so a concurrent
# list can't see the install path missing between the two renames
# and prune the entry.
with manager.metadata_session() as session:
current_info = session.extensions.get(name)
if current_info is None or not install_path.is_dir():
return None

# 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

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
session.extensions[name] = info
finally:
if backup_path.exists() and not install_path.exists():
logger.error(
f"Could not restore {install_path} after a failed update;"
f" the previous version was kept at {backup_path}"
)
else:
shutil.rmtree(backup_root, ignore_errors=True)

shutil.rmtree(_staging_root(installed_dir) / name, ignore_errors=True)
return info
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,13 @@
)
from openhands.agent_server.errors import error_responses
from openhands.agent_server.server_context import server_context_of
from openhands.sdk.errors import Conflict, Invalid, NotFound, Unprocessable
from openhands.sdk.errors import (
Conflict,
Invalid,
LockTimeout,
NotFound,
Unprocessable,
)
from openhands.sdk.extensions.fetch import ExtensionFetchError
from openhands.sdk.utils.redact import redact_url_credentials

Expand Down Expand Up @@ -203,6 +209,7 @@ class UninstallCanvasExtensionResponse(BaseModel):
Invalid: "Could not read canvas extension source",
Conflict: "Canvas extension already installed (use force=true)",
Unprocessable: "Invalid canvas extension (bad manifest, etc.)",
LockTimeout: "Another extension operation is in progress",
}
),
)
Expand Down Expand Up @@ -251,14 +258,21 @@ async def install_canvas_extension_endpoint(
"Source plus Path must point at the extension's own "
"directory, not the repository root."
)
except LockTimeout:
# A LockTimeout is also an OSError; it means busy, not invalid.
raise
except (ValidationError, ValueError, OSError):
raise Unprocessable(
"Invalid canvas extension. Ensure the manifest is well-formed."
)


@canvas_extensions_router.get(
"/installed", response_model=InstalledCanvasExtensionsListResponse
"/installed",
response_model=InstalledCanvasExtensionsListResponse,
responses=error_responses(
{LockTimeout: "Another extension operation is in progress"}
),
)
def list_installed_canvas_extensions_endpoint() -> (
InstalledCanvasExtensionsListResponse
Expand Down Expand Up @@ -295,7 +309,12 @@ def get_installed_canvas_extension_endpoint(
@canvas_extensions_router.patch(
"/installed/{extension_name}",
response_model=UpdateCanvasExtensionStateResponse,
responses=error_responses({NotFound: "Canvas extension not installed"}),
responses=error_responses(
{
NotFound: "Canvas extension not installed",
LockTimeout: "Another extension operation is in progress",
}
),
)
async def set_canvas_extension_enabled_endpoint(
extension_name: CanvasExtensionNamePath,
Expand All @@ -308,7 +327,9 @@ async def set_canvas_extension_enabled_endpoint(
async with lock:
if not request.enabled:
await _revoke_and_stop_backend(http_request, extension_name)
if not disable_canvas_extension(name=extension_name):
if not await asyncio.to_thread(
disable_canvas_extension, name=extension_name
):
raise NotFound("Canvas App is not installed")
return UpdateCanvasExtensionStateResponse(
name=extension_name, enabled=False
Expand Down Expand Up @@ -356,29 +377,34 @@ async def set_canvas_extension_enabled_endpoint(
)
except (ValueError, RuntimeError, OSError) as exc:
await _revoke_and_stop_backend(http_request, extension_name)
disable_canvas_extension(name=extension_name)
await asyncio.to_thread(disable_canvas_extension, name=extension_name)
raise Conflict(str(exc)) from exc
except BaseException:
await _revoke_and_stop_backend(http_request, extension_name)
disable_canvas_extension(name=extension_name)
await asyncio.to_thread(disable_canvas_extension, name=extension_name)
raise
if not enable_canvas_extension(name=extension_name):
if not await asyncio.to_thread(enable_canvas_extension, name=extension_name):
raise NotFound("Canvas App is not installed")
return UpdateCanvasExtensionStateResponse(name=extension_name, enabled=True)


@canvas_extensions_router.delete(
"/installed/{extension_name}",
response_model=UninstallCanvasExtensionResponse,
responses=error_responses({NotFound: "Canvas extension not installed"}),
responses=error_responses(
{
NotFound: "Canvas extension not installed",
LockTimeout: "Another extension operation is in progress",
}
),
)
async def uninstall_canvas_extension_endpoint(
extension_name: CanvasExtensionNamePath,
request: Request,
) -> UninstallCanvasExtensionResponse:
"""Uninstall a canvas extension by name while retaining backend data."""
await _revoke_and_stop_backend(request, extension_name)
if not uninstall_canvas_extension(name=extension_name):
if not await asyncio.to_thread(uninstall_canvas_extension, name=extension_name):
raise NotFound(f"Canvas extension '{extension_name}' is not installed")
return UninstallCanvasExtensionResponse(
message=f"Canvas extension '{extension_name}' uninstalled"
Expand Down Expand Up @@ -553,13 +579,16 @@ async def grant_canvas_extension_backend_secrets_endpoint(
@canvas_extensions_router.delete(
"/installed/{extension_name}/backend/secret-grant",
response_model=BackendStatus,
responses=error_responses(
{LockTimeout: "Another extension operation is in progress"}
),
)
async def revoke_canvas_extension_backend_secrets_endpoint(
extension_name: CanvasExtensionNamePath,
request: Request,
) -> BackendStatus:
"""Revoke consent, terminate the process group and invalidate bridge sessions."""
async with _lifecycle_lock(request, extension_name):
disable_canvas_extension(name=extension_name)
await asyncio.to_thread(disable_canvas_extension, name=extension_name)
await _backend_manager(request).revoke_secrets(extension_name)
return await _revoke_and_stop_backend(request, extension_name)
33 changes: 29 additions & 4 deletions openhands-agent-server/openhands/agent_server/plugins_router.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
from openhands.sdk.errors import (
Conflict,
Invalid,
LockTimeout,
NotFound,
Unprocessable,
UpstreamFailed,
Expand Down Expand Up @@ -329,6 +330,7 @@ def fetch_plugin_endpoint(request: FetchPluginRequest) -> FetchPluginResponse:
Invalid: "Failed to fetch plugin source",
Conflict: "Plugin already installed (use force=true)",
Unprocessable: "Invalid plugin (bad name, etc.)",
LockTimeout: "Another extension operation is in progress",
}
),
)
Expand All @@ -350,7 +352,13 @@ def install_plugin_endpoint(request: InstallPluginRequest) -> InstalledPluginRes
raise Unprocessable("Invalid plugin. Ensure it has a valid kebab-case name.")


@plugins_router.get("/installed", response_model=InstalledPluginsListResponse)
@plugins_router.get(
"/installed",
response_model=InstalledPluginsListResponse,
responses=error_responses(
{LockTimeout: "Another extension operation is in progress"}
),
)
def list_installed_plugins_endpoint() -> InstalledPluginsListResponse:
"""List all installed plugins (enabled and disabled)."""
plugins = service_list_installed_plugins()
Expand All @@ -377,7 +385,12 @@ def get_installed_plugin_endpoint(
@plugins_router.patch(
"/installed/{plugin_name}",
response_model=UpdatePluginStateResponse,
responses=error_responses({NotFound: "Plugin not installed"}),
responses=error_responses(
{
NotFound: "Plugin not installed",
LockTimeout: "Another extension operation is in progress",
}
),
)
def set_plugin_enabled_endpoint(
plugin_name: PluginNamePath, request: UpdatePluginStateRequest
Expand All @@ -392,7 +405,12 @@ def set_plugin_enabled_endpoint(
@plugins_router.delete(
"/installed/{plugin_name}",
response_model=UninstallPluginResponse,
responses=error_responses({NotFound: "Plugin not installed"}),
responses=error_responses(
{
NotFound: "Plugin not installed",
LockTimeout: "Another extension operation is in progress",
}
),
)
def uninstall_plugin_endpoint(plugin_name: PluginNamePath) -> UninstallPluginResponse:
"""Uninstall a plugin by name."""
Expand All @@ -408,6 +426,7 @@ def uninstall_plugin_endpoint(plugin_name: PluginNamePath) -> UninstallPluginRes
{
Invalid: "Failed to fetch the plugin's recorded source",
NotFound: "Plugin not installed",
LockTimeout: "Another extension operation is in progress",
}
),
)
Expand Down Expand Up @@ -436,7 +455,13 @@ def refresh_plugin_endpoint(plugin_name: PluginNamePath) -> UpdatePluginResponse
)


@plugins_router.get("/marketplace", response_model=MarketplaceCatalogResponse)
@plugins_router.get(
"/marketplace",
response_model=MarketplaceCatalogResponse,
responses=error_responses(
{LockTimeout: "Another extension operation is in progress"}
),
)
def get_marketplace_catalog() -> MarketplaceCatalogResponse:
"""Get the plugins marketplace catalog with installation status.

Expand Down
Loading
Loading