feat: Extension installation module

openhands-sdk/openhands/sdk/extensions/installation/README.md

@@ -0,0 +1,93 @@
+# Installation
+
+Generic framework for installing, tracking, and loading extensions from local
+or remote sources.
+
+## Overview
+
+The installation module is **extension-type agnostic**.  It is parameterised by
+a type `T` (any object with `name`, `version`, and `description` attributes)
+and an `InstallationInterface[T]` that knows how to load `T` from a directory.
+Everything else — fetching, copying, metadata bookkeeping, enable/disable
+state — is handled generically.
+
+## Usage
+
+### 1. Define your extension type and loader
+
+```python
+from pathlib import Path
+from pydantic import BaseModel
+from openhands.sdk.extensions.installation import (
+    InstallationInterface,
+    InstallationManager,
+)
+
+class Widget(BaseModel):
+    name: str
+    version: str
+    description: str
+
+class WidgetLoader(InstallationInterface[Widget]):
+    @staticmethod
+    def load_from_dir(extension_dir: Path) -> Widget:
+        return Widget.model_validate_json(
+            (extension_dir / "widget.json").read_text()
+        )
+```
+
+### 2. Create a manager
+
+```python
+manager = InstallationManager(
+    installation_dir=Path("~/.myapp/widgets/installed").expanduser(),
+    installation_interface=WidgetLoader(),
+)
+```
+
+### 3. Manage extensions
+
+```python
+# Install from a local path or remote source
+info = manager.install("github:owner/my-widget", ref="v1.0.0")
+info = manager.install("/path/to/local/widget")
+
+# Force-overwrite an existing installation (preserves enabled state)
+info = manager.install("github:owner/my-widget", force=True)
+
+# List / load
+all_info = manager.list_installed()        # List[InstallationInfo]
+widgets  = manager.load_installed()        # List[Widget]  (enabled only)
+
+# Enable / disable
+manager.disable("my-widget")               # excluded from load_installed()
+manager.enable("my-widget")                # included again
+
+# Look up a single extension
+info = manager.get("my-widget")            # InstallationInfo | None
+
+# Update to latest from the original source
+info = manager.update("my-widget")
+
+# Remove completely
+manager.uninstall("my-widget")
+```
+
+## Self-healing metadata
+
+`list_installed()` (and by extension `load_installed()`) automatically
+reconciles the `.installed.json` metadata with what is actually on disk:
+
+- **Stale entries** — if a tracked extension's directory has been manually
+  deleted, the metadata entry is pruned.
+- **Untracked directories** — if a valid extension directory exists but is not
+  in metadata, it is discovered and added with `source="local"`.
+
+This means the metadata file is always the single source of truth *after* a
+list/load call, even if the filesystem was modified externally.
+
+## Extension naming
+
+Extension names must be **kebab-case** (`^[a-z0-9]+(-[a-z0-9]+)*$`).  This is
+enforced on install, uninstall, enable, disable, get, and update to prevent
+path-traversal attacks (e.g. `../evil`).

openhands-sdk/openhands/sdk/extensions/installation/__init__.py

@@ -0,0 +1,20 @@
+from openhands.sdk.extensions.installation.info import InstallationInfo
+from openhands.sdk.extensions.installation.interface import (
+    ExtensionProtocol,
+    InstallationInterface,
+)
+from openhands.sdk.extensions.installation.manager import InstallationManager
+from openhands.sdk.extensions.installation.metadata import (
+    InstallationMetadata,
+    MetadataSession,
+)
+
+
+__all__ = [
+    "InstallationInfo",
+    "InstallationInterface",
+    "ExtensionProtocol",
+    "InstallationManager",
+    "InstallationMetadata",
+    "MetadataSession",
+]

openhands-sdk/openhands/sdk/extensions/installation/info.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from openhands.sdk.extensions.installation.interface import ExtensionProtocol
+
+
+class InstallationInfo(BaseModel):
+    """Metadata record for a single installed extension.
+
+    Stored (keyed by name) inside ``InstallationMetadata`` and persisted to
+    the ``.installed.json`` file in the installation directory.
+    """
+
+    name: str = Field(description="Extension name")
+    version: str = Field(default="1.0.0", description="Extension version")
+    description: str = Field(default="", description="Extension description")
+
+    enabled: bool = Field(default=True, description="Whether the extension is enabled")
+
+    source: str = Field(description="Original source (e.g., 'github:owner/repo')")
+    resolved_ref: str | None = Field(
+        default=None, description="Resolved git commit SHA (for version pinning)"
+    )
+    repo_path: str | None = Field(
+        default=None,
+        description="Subdirectory path within the repository (for monorepos)",
+    )
+
+    installed_at: str = Field(
+        default_factory=lambda: datetime.now(UTC).isoformat(),
+        description="ISO 8601 timestamp of installation",
+    )
+    install_path: Path = Field(description="Path where the extension is installed")
+
+    @staticmethod
+    def from_extension(
+        extension: ExtensionProtocol,
+        source: str,
+        install_path: Path,
+        resolved_ref: str | None = None,
+        repo_path: str | None = None,
+    ) -> InstallationInfo:
+        """Create an InstallationInfo from an extension and its install context.
+
+        Only ``extension.name`` is required by ``ExtensionProtocol``.
+        ``version`` and ``description`` are read with ``getattr`` so
+        extension types that omit them (e.g. skills) get sensible defaults.
+
+        Args:
+            extension: Any object satisfying ``ExtensionProtocol``.
+            source: Original source string (e.g. ``"github:owner/repo"``).
+            install_path: Filesystem path the extension was copied to.
+            resolved_ref: Resolved git commit SHA, if applicable.
+            repo_path: Subdirectory within a monorepo, if applicable.
+        """
+        return InstallationInfo(
+            name=extension.name,
+            version=getattr(extension, "version", "1.0.0"),
+            description=getattr(extension, "description", None) or "",
+            source=source,
+            resolved_ref=resolved_ref,
+            repo_path=repo_path,
+            install_path=install_path,
+        )

openhands-sdk/openhands/sdk/extensions/installation/interface.py

@@ -0,0 +1,31 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Protocol
+
+
+class ExtensionProtocol(Protocol):
+    """Minimal structural protocol for installable extensions.
+
+    Only ``name`` is required.  ``version`` and ``description`` are read
+    via ``getattr`` in ``InstallationInfo.from_extension`` so that
+    extension types that don't carry those fields (e.g. skills) still
+    work without adapter wrappers.
+
+    ``name`` is declared as a read-only property so that both plain
+    attributes and ``@property`` accessors satisfy the protocol.
+    """
+
+    @property
+    def name(self) -> str: ...
+
+
+class InstallationInterface[T: ExtensionProtocol](ABC):
+    """Abstract interface that teaches ``InstallationManager`` how to load ``T``.
+
+    Subclass this and implement ``load_from_dir`` for each concrete
+    extension type (e.g. plugins, skills).
+    """
+
+    @staticmethod
+    @abstractmethod
+    def load_from_dir(extension_dir: Path) -> T: ...