@openhands/extensions 0.25.0 → 0.26.0

package/plugins/vulnerability-remediation/skills/github/scripts/github_client.py

@@ -12,24 +12,62 @@ from urllib.parse import parse_qsl, urlencode, urlsplit
 from urllib.request import Request, urlopen
 
 
+# The secret name of the GitHub token an OpenHands Cloud or Enterprise user's
+# connected GitHub integration provides: how this run's sandbox serves it, and
+# how a conversation sees it in its environment.
+CLOUD_GITHUB_TOKEN_SECRET = "github_token"
+CLOUD_GITHUB_TOKEN_ENV = "GITHUB_TOKEN"
+
+
+def is_cloud_run() -> bool:
+    """Whether this run is on OpenHands Cloud or Enterprise.
+
+    The automation service hands a run the Agent Server URL only on a local
+    Agent Canvas; elsewhere the run talks to the OpenHands API instead.
+    """
+    return bool(os.environ.get("OPENHANDS_CLOUD_API_URL")) and not os.environ.get(
+        "AGENT_SERVER_URL"
+    )
+
+
+def _load_cloud_secret(name: str) -> str | None:
+    """Read one named secret of this run's sandbox from the OpenHands API."""
+    api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+    request = Request(
+        f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}",
+        headers={"X-Session-API-Key": os.environ["SESSION_API_KEY"]},
+    )
+    try:
+        with urlopen(request, timeout=90) as response:
+            return response.read().decode().strip()
+    except HTTPError as exc:
+        if exc.code == 404:
+            return None
+        raise
+
+
 def _load_secret(name: str) -> str:
-    """Read one named secret from the environment or configured Agent Server."""
+    """Read one named secret from the environment, or from the configured Agent
+    Server on a local run and the OpenHands API on a cloud one."""
     value = os.environ.get(name)
     if value:
         return value
 
-    from openhands.sdk.workspace import RemoteWorkspace
+    if is_cloud_run():
+        value = _load_cloud_secret(name)
+    else:
+        from openhands.sdk.workspace import RemoteWorkspace
 
-    workspace = RemoteWorkspace(
-        host=os.environ["AGENT_SERVER_URL"],
-        api_key=os.environ["SESSION_API_KEY"],
-        working_dir=os.environ.get("WORKSPACE_BASE", "/workspace"),
-    )
-    try:
-        secret = workspace.get_secrets([name]).get(name)
-        value = secret.get_value() if secret else None
-    finally:
-        workspace.reset_client()
+        workspace = RemoteWorkspace(
+            host=os.environ["AGENT_SERVER_URL"],
+            api_key=os.environ["SESSION_API_KEY"],
+            working_dir=os.environ.get("WORKSPACE_BASE", "/workspace"),
+        )
+        try:
+            secret = workspace.get_secrets([name]).get(name)
+            value = secret.get_value() if secret else None
+        finally:
+            workspace.reset_client()
     if not value:
         raise ValueError(f"The GitHub credential {name} is unavailable")
     return value
@@ -95,11 +133,22 @@ class GitHubRepository:
                 "Expected the environment variable containing the GitHub token"
             )
         self.token_name = github_token_secret
-        self.token = _load_secret(github_token_secret)
+        try:
+            self.token = _load_secret(github_token_secret)
+        except ValueError:
+            if not is_cloud_run():
+                raise
+            # No secret is saved under that name, so use the user's connected
+            # GitHub integration, under the name a conversation sees it by.
+            self.token = _load_cloud_secret(CLOUD_GITHUB_TOKEN_SECRET)
+            if not self.token:
+                raise
+            self.token_name = CLOUD_GITHUB_TOKEN_ENV
         self.conversation = conversation
         self.conversation_id = str(conversation.id) if conversation else None
         self.dispatcher = dispatcher
-        self.workspace = Path(os.environ["WORKSPACE_BASE"])
+        # A cloud run is not given a workspace base; its sandbox has /workspace.
+        self.workspace = Path(os.environ.get("WORKSPACE_BASE", "/workspace"))
         self.project = self.workspace
         self.evidence = self.workspace / "evidence"
         self.evidence.mkdir(exist_ok=True)
@@ -111,10 +160,13 @@ class GitHubRepository:
 
     @property
     def github_instructions(self):
+        # A cloud conversation runs in a sandbox of its own, so this run's
+        # workspace path means nothing to it.
+        where = "your working directory" if is_cloud_run() else self.project
         return (
             f"Use `GH_TOKEN=${self.token_name} gh api` for GitHub requests. "
             "Never print the credential value. "
-            f"Only {self.repository} is in scope. Work in {self.project}. "
+            f"Only {self.repository} is in scope. Work in {where}. "
             "Do not modify the automation bundle or its configuration."
         )
 

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.25.0"
+version = "0.26.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 dependencies = [

package/python/openhands_extensions/_version.py

@@ -18,7 +18,7 @@ from importlib.metadata import PackageNotFoundError, version
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
 #: release-please only rewrites a semver found on the annotated line itself, so
 #: the annotation must stay on the assignment; on its own line it is a no-op.
-_FALLBACK_VERSION = "0.25.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.26.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")

package/scripts/check_plugin_resources.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Fail if any plugin ships non-source noise in its SDK-visible resource dirs.
+
+The OpenHands SDK's skill loader (`openhands.sdk.skills`) walks a fixed set of
+directory names under each plugin and lists everything it finds in that plugin's
+`SkillResources` manifest:
+
+    >>> from openhands.sdk.skills import RESOURCE_DIRECTORIES
+    >>> RESOURCE_DIRECTORIES
+    ('scripts', 'references', 'assets')
+
+Anything that lands in one of those directories becomes visible to the agent at
+skill-load time. A stale ``__pycache__/warm_runtime_configs.cpython-313.pyc``
+left behind by a developer running tests in-tree therefore gets surfaced to
+every downstream consumer that loads the plugin as a skill.
+
+This check scans ``plugins/<name>/{scripts,references,assets}`` for files that
+clearly aren't skill content - Python bytecode caches, pytest caches, editor
+backups, OS litter - and exits 1 if any are found. Keep this list narrow: it
+should flag obvious noise, not police plugin contents.
+
+Usage:
+    python scripts/check_plugin_resources.py            # scan and report
+    python scripts/check_plugin_resources.py --fix      # also delete offenders
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import shutil
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+PLUGINS_DIR = REPO_ROOT / "plugins"
+
+# Mirrors openhands.sdk.skills.RESOURCE_DIRECTORIES. Pinned here rather than
+# imported so the check runs without the SDK installed in CI.
+RESOURCE_DIRECTORIES = ("scripts", "references", "assets")
+
+# Names (dirs or files) that should never appear under a resource directory.
+# Dir patterns match against directory basenames; file patterns are fnmatch'd
+# against file basenames.
+_FORBIDDEN_DIR_NAMES = frozenset({"__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache"})
+_FORBIDDEN_FILE_GLOBS = ("*.pyc", "*.pyo", "*.pyd", "*.swp", "*.swo", ".DS_Store", "Thumbs.db")
+
+
+def _is_forbidden_file(name: str) -> bool:
+    return any(fnmatch.fnmatchcase(name, pat) for pat in _FORBIDDEN_FILE_GLOBS)
+
+
+def scan() -> list[Path]:
+    offenders: list[Path] = []
+    if not PLUGINS_DIR.is_dir():
+        return offenders
+    for plugin_dir in sorted(PLUGINS_DIR.iterdir()):
+        if not plugin_dir.is_dir():
+            continue
+        for resource_name in RESOURCE_DIRECTORIES:
+            resource_dir = plugin_dir / resource_name
+            if not resource_dir.is_dir():
+                continue
+            for path in sorted(resource_dir.rglob("*")):
+                if path.is_dir() and path.name in _FORBIDDEN_DIR_NAMES:
+                    offenders.append(path)
+                elif path.is_file() and _is_forbidden_file(path.name):
+                    offenders.append(path)
+    return offenders
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--fix",
+        action="store_true",
+        help="Delete offending files/dirs instead of just failing.",
+    )
+    args = parser.parse_args()
+
+    offenders = scan()
+    if not offenders:
+        print(f"OK: no non-source files found under plugins/*/{{{','.join(RESOURCE_DIRECTORIES)}}}/")
+        return 0
+
+    print(
+        f"ERROR: {len(offenders)} non-source entries found under plugin resource "
+        f"directories. These would be surfaced to agents in SkillResources:",
+        file=sys.stderr,
+    )
+    for path in offenders:
+        kind = "dir " if path.is_dir() else "file"
+        print(f"  {kind}  {path.relative_to(REPO_ROOT)}", file=sys.stderr)
+
+    if args.fix:
+        # Delete deepest paths first so a child file inside a to-be-removed
+        # __pycache__ directory doesn't vanish out from under its own unlink.
+        for path in sorted(offenders, key=lambda p: len(p.parts), reverse=True):
+            if path.is_dir():
+                shutil.rmtree(path, ignore_errors=True)
+            else:
+                path.unlink(missing_ok=True)
+        print(f"\nRemoved {len(offenders)} entries.", file=sys.stderr)
+        return 0
+
+    print(
+        "\nRe-run with --fix to delete, or add the pattern to .gitignore and "
+        "clean your working tree. These are typically produced by running tests "
+        "in-tree without PYTHONDONTWRITEBYTECODE=1.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/sync_extensions.py

@@ -9,7 +9,8 @@ Four sync tasks, runnable individually or all at once:
   3. **coverage**  — warn when a skill/plugin directory is not listed in any
      marketplace, or a marketplace entry points to a missing directory.
   4. **symlinks**  — enforce ``.plugin/`` as the canonical manifest directory
-     with vendor symlinks (``.claude-plugin``, ``.codex-plugin``).
+     with vendor manifests (``.claude-plugin``, ``.codex-plugin``), each
+     either a symlink or a real directory mirroring ``plugin.json``.
 
 Usage:
     python scripts/sync_extensions.py                   # run all, write changes
@@ -375,13 +376,30 @@ def sync_coverage(*, check: bool) -> list[str]:
     return problems
 
 
-# ── 4. Vendor symlinks ────────────────────────────────────────────────
+# ── 4. Vendor manifests ─────────────────────────────────────────────────
 
 VENDOR_SYMLINKS = [".claude-plugin", ".codex-plugin"]  # add new vendors here
 
 
+def _vendor_manifest_matches(directory: Path, vendor: str) -> bool:
+    """True when a real vendor directory mirrors the canonical manifest."""
+    src = directory / ".plugin" / "plugin.json"
+    dst = directory / vendor / "plugin.json"
+    return (
+        src.is_file()
+        and dst.is_file()
+        and src.read_bytes() == dst.read_bytes()
+    )
+
+
 def _check_vendor_symlinks(directory: Path, check: bool) -> list[str]:
-    """Check/fix vendor symlinks for a single directory with .plugin/."""
+    """Check/fix vendor manifests for a single directory with .plugin/.
+
+    A vendor path is either a symlink to ``.plugin/`` or a real directory
+    whose ``plugin.json`` mirrors the canonical one. Real directories exist
+    because some installers (e.g. Codex ``plugin add``) drop symlinked
+    directories instead of copying them; see skills/iterate.
+    """
     problems: list[str] = []
     canon = directory / ".plugin"
     if not canon.is_dir():
@@ -393,6 +411,15 @@ def _check_vendor_symlinks(directory: Path, check: bool) -> list[str]:
             if target == canon.resolve():
                 continue
             problems.append(f"wrong target: {link.relative_to(REPO_ROOT)} → {link.readlink()}")
+        elif link.is_dir():
+            if _vendor_manifest_matches(directory, vendor):
+                continue
+            problems.append(f"stale manifest copy: {link.relative_to(REPO_ROOT)}")
+            if not check:
+                (link / "plugin.json").write_bytes(
+                    (canon / "plugin.json").read_bytes()
+                )
+            continue
         elif link.exists():
             problems.append(f"not a symlink: {link.relative_to(REPO_ROOT)}")
             continue
@@ -405,11 +432,11 @@ def _check_vendor_symlinks(directory: Path, check: bool) -> list[str]:
 
 
 def sync_symlinks(*, check: bool) -> list[str]:
-    """Ensure every directory with .plugin/ also has vendor symlinks.
+    """Ensure every directory with .plugin/ has discoverable vendor manifests.
 
     Scans both plugins/ and skills/ directories.  Skills that ship a
     ``.plugin/`` manifest (e.g. those with ``commands/``) need vendor
-    symlinks so that Codex and Claude Code can discover them.
+    manifests so that Codex and Claude Code can discover them.
     """
     problems: list[str] = []
     for base in SKILL_DIRS:

package/skills/canvas-extension-api/SKILL.md

@@ -22,7 +22,7 @@ Treat apps as trusted, same-realm browser code owned by the active Agent Server.
 
 ## Prefer the proven App authoring loop
 
-Treat an App as one authenticated browser dependency graph that Canvas imports from a Blob URL. Do not build a hosted SPA: the production result must be exactly one self-contained browser ESM entrypoint that exports `activate(host)`. Always ship this UI package even when it uses a separately installed Sidecar; make the App page the guided UI for Sidecar setup after the App is opened. Never treat a Sidecar as another browser chunk or an automatic extension install hook.
+Treat an App as one authenticated browser dependency graph that Canvas imports from a Blob URL. Do not build a hosted SPA: the production result must be exactly one self-contained browser ESM entrypoint that exports `activate(host)`. Always ship this UI package even when it uses an optional package-owned managed backend or a manual/deployment-owned Sidecar. Make the App page the guided UI for service setup after the App is opened. Never treat a service as another browser chunk or an automatic extension install hook.
 
 For a new App, create an independent package in the target repository and implement its own UI, tests, and build tooling. Follow the Vite library-build reference in `references/packaging-recipes.md`; do not copy a shared starter or introduce a repository-wide runtime/workspace unless the target repository explicitly requires it.
 
@@ -41,7 +41,9 @@ Treat the static validator as a gate, not a replacement for the browser Blob smo
 
 Start by locating the target directory instead of assuming the current workspace. Inspect repository instructions, existing package management, build tooling, tests, and git status before editing.
 
-Make an early architecture decision: browser-only App, Agent Server-integrated App, Sidecar-backed App, or explicitly deployment-specific App. Keep the portable host API 1 surface separate from deployment-owned capabilities.
+Make an early architecture decision: browser-only App, Agent Server-integrated App, package-owned managed-backend App, manual/deployment-owned Sidecar App, or explicitly deployment-specific App. Keep the portable host API 1 surface separate from optional Agent Server/host capabilities and deployment-owned behavior.
+
+Use the package-owned managed-backend path only when the target stack includes the lifecycle contract from [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3`, the bridge contract from [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`, and the host version named in `references/v1-contract.md`. Until a release containing both SDK PRs lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` and `app_backend_ingress_url` through `GET /server_info`; absence is an actionable unsupported state. Do not convert manual Sidecars into managed backends unless the App owns checksum-pinned artifacts for every supported platform.
 
 Clarify only choices that materially affect implementation:
 
@@ -99,6 +101,33 @@ Use this minimal manifest shape:
 }
 ```
 
+For an optional package-owned managed backend, add this top-level sibling of `contributes`:
+
+```json
+"backend": {
+  "schema_version": 1,
+  "artifacts": {
+    "linux-amd64": {
+      "path": "backend/linux-amd64.tar.gz",
+      "sha256": "<64 lowercase hex characters>"
+    },
+    "linux-arm64": {
+      "path": "backend/linux-arm64.tar.gz",
+      "sha256": "<64 lowercase hex characters>"
+    }
+  },
+  "argv": [
+    "{artifact_dir}/bin/server",
+    "--host=127.0.0.1",
+    "--port={port}",
+    "--data-dir={data_dir}"
+  ],
+  "health": { "path": "/health" }
+}
+```
+
+This declaration is optional. Omit it for browser-only Apps and manual/deployment-owned Sidecars. It never authorizes automatic preparation or startup. The server supports Linux amd64 and arm64 initially, verifies package-contained `.tar.gz` artifacts by SHA-256, and executes the structured argv without a shell. `argv[0]` must remain inside `{artifact_dir}`; allowed placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`.
+
 Follow these invariants:
 
 - Use lowercase letters, digits, and hyphens for app names and page IDs.
@@ -146,6 +175,8 @@ Prefer [`@openhands/typescript-client`](https://github.com/OpenHands/software-ag
 Respect the host API 1 connection boundary:
 
 - Treat `host.agentServer.request` as the portable Agent Server HTTP path; Canvas selects the active backend and supplies authentication.
+- For a managed-backend view, require the feature-detected host helper documented in `references/v1-contract.md`. The helper owns session creation, validated iframe isolation, retry/new-tab behavior, and revocation; the App never reads the app-scoped cookie or constructs the ingress URL. The ingress must be a separate browser origin from Canvas, and the host must preserve the server-returned sandbox including `allow-same-origin`.
+- Installing, enabling, activating, or mounting an App never prepares or starts a managed backend. Show the resolved revision and declaration, obtain explicit lifecycle consent, and call prepare then start with that exact revision. An update invalidates approval.
 - Do not derive an Agent Server URL from `window.location` or extract session keys from Canvas internals.
 - Do not send Automation service requests through `host.agentServer.request` unless the backend explicitly documents an Agent Server proxy for them. Automation is a separate service with deployment-provided base URL and authentication.
 - Do not open a direct Agent Server WebSocket from a portable v1 app. The host currently exposes neither the owning server origin nor a WebSocket/auth capability. Poll through `host.agentServer.request`, add a backend-owned bridge, or feature-detect a future host subscription API.
@@ -211,7 +242,7 @@ Treat validator warnings as prompts for inspection, not proof of invalidity. The
 
 ## Install and verify safely
 
-Install only when requested. Installation and enablement are separate product actions: installation must leave the app disabled, and enabling executes trusted same-realm code.
+Install only when requested. Installation and enablement are separate product actions: installation must leave the app disabled, and enabling executes trusted same-realm code. Managed-backend preparation and startup are additional explicit actions tied to the resolved revision; installation, enablement, activation, and ordinary page mounts never execute backend code.
 
 For a backend-local app, install the path as interpreted on the Agent Server machine. For a Git-hosted app, provide `source`, optional `ref`, and optional `repo_path`. Never assume a frontend-local path exists inside a remote or containerized backend.
 

package/skills/canvas-extension-api/references/backend-safety.md

@@ -7,3 +7,17 @@ For command-backed Apps, expose fixed command templates only. Validate paths, pa
 Keep browser-local data namespaced by App name and backend ID in IndexedDB/OPFS/localStorage. Put backend-shared mutable state below `<agent-server-home>/.openhands/apps/<app-name>/`, after discovering the home through `GET /api/file/home` and validating the absolute path. Never write mutable state beside the installed manifest or bundle.
 
 For a CLI, binary, compiler, database, or Sidecar, read [sidecar-pattern.md](sidecar-pattern.md). Probe without mutation; disclose exact downloads, builds, data paths, checksums, and process behavior; and gate installation behind acknowledgement. Do not expose general command execution, shell interpolation, silent or unpinned downloads, unauthenticated non-loopback binding, mutable state beside the installed bundle, or automatic data deletion when an App is removed.
+
+## Package-owned managed backends
+
+The managed-backend contract requires the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Until a release containing both lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` through `GET /server_info`; never infer support from an endpoint failure, Canvas internals, or a guessed port. Use the host helper only at the minimum host version documented in [v1-contract.md](v1-contract.md).
+
+A managed backend is declarative, not an install hook. Installation, enablement, activation, and ordinary page mounts never prepare or start it. Show the resolved revision and backend declaration, then require explicit user consent before calling prepare and start with that exact revision. Updating or replacing the package invalidates approval. Never put a credential in the manifest, argv, browser bundle, URL, or log.
+
+For embedded backend views, require the configured ingress to be a separate browser origin from Canvas. That origin is the isolation boundary. Apply the server-returned sandbox exactly, including `allow-same-origin`; removing it breaks Origin validation, partitioned-cookie delivery, and Worker creation in Chromium. Do not replace origin isolation with an opaque sandbox origin.
+
+The Agent Server selects the current platform artifact, verifies its lowercase SHA-256 checksum, extracts it safely to immutable content-addressed storage, and runs only the declared structured argv without a shell. The executable must remain inside `{artifact_dir}`. Supported placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`. Inherited environment names are restricted to the server's non-credential allowlist; ambient Agent Server credentials do not flow to the child.
+
+Only local Linux amd64 and arm64 artifacts are supported initially. Treat `unsupported` as an explicit UI state. The owned process is constrained by its launch contract and process group but is not OS-isolated; run untrusted backend code only inside a suitably isolated Agent Server runtime.
+
+Backend data belongs to the service independently of the installed bundle. Disable and uninstall stop the owned process and revoke browser sessions but preserve mutable data. Data deletion is a separate explicit action. Installed Apps and their backends belong to one Agent Server; do not assume a service or its data is shared across isolated conversation runtimes.

package/skills/canvas-extension-api/references/connections.md

@@ -48,6 +48,30 @@ Supply the actual Agent Server origin, including any reverse-proxy path prefix.
 
 If typed high-level clients cover the operation, prefer those over the generic `HttpClient`. Use the generic client for uncovered Agent Server endpoints, not as a reason to duplicate authentication and error handling with `fetch`.
 
+## Managed App backend views
+
+The managed-backend bridge requires the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Until a release containing both lands, those exact revisions are the minimum Agent Server implementation. Read `GET /server_info`: support is present only when `capabilities` contains `canvas_app_backend_bridge_v1` and `app_backend_ingress_url` supplies the separately configured browser origin. If either is absent, render an actionable unsupported state. Never guess localhost, derive an origin from `window.location`, or read Canvas credentials.
+
+The typed `CanvasExtensionsClient`, constructed with the normal Agent Server host and API key plus `appBackendIngressUrl`, exposes `createAppBackendSession(name)` and `revokeAppBackendSession(name)`. Session creation returns `ingress_url`, `expires_at`, and `iframe_sandbox`. The app-scoped credential is an HttpOnly, Secure, SameSite=None, Partitioned cookie; it is not returned to browser JavaScript or placed in a URL.
+
+Control calls go to the configured ingress origin:
+
+- `POST /app-backends/{name}/session` creates a short-lived session for a ready owned backend.
+- `DELETE /app-backends/{name}/session` revokes it and active sockets.
+
+Both calls require normal `X-Session-API-Key` control authentication and an allowed Canvas `Origin`. Use the credential-free returned `ingress_url`, rooted at `/app-backends/{name}/`, for iframe assets, streaming, ranges, and relative WebSocket URLs. Apply the returned sandbox exactly; the v1 bridge returns `allow-forms allow-modals allow-popups allow-same-origin allow-scripts`. The configured ingress must be a separate browser origin from Canvas and is the isolation boundary. Do not remove `allow-same-origin`: real Chromium sends `Origin: null` for mutating fetches and WebSockets, drops the partitioned session cookie, and rejects same-site Worker creation with `SecurityError` when the frame has an opaque sandbox origin. HTTPS, or a loopback secure context, and browser partitioned-cookie support are required for third-party iframe operation.
+
+Apps consume this flow through optional `host.appBackendView`, not by calling the control API or constructing an iframe URL. Feature-detect it before rendering a managed view:
+
+```js
+const disposeView = host.appBackendView?.mount({ container });
+if (!disposeView) {
+  container.textContent = "This Canvas host cannot open the App backend view.";
+}
+```
+
+`mount({ container })` returns a disposer. Call it on page unmount; Canvas also disposes views on backend switch and extension deactivation. The helper owns session creation, URL and sandbox validation, loading, retry, safe new-tab fallback, and revocation. Mounting or remounting never starts or stops the service. Use the helper only at the minimum host version documented in [v1-contract.md](v1-contract.md).
+
 ## Automation backend
 
 Treat the Automation service as a separate backend. Its API is normally mounted under `/api/automation/v1`, but the origin, path prefix, and authentication mode are deployment-provided values rather than Agent Server defaults.

package/skills/canvas-extension-api/references/sidecar-pattern.md

@@ -1,29 +1,68 @@
 # Sidecar-backed Apps
 
-Use this reference when an App needs a separately installed service. Host API 1 supports a browser App package and authenticated Agent Server HTTP requests; it does not provide Sidecar installation, process management, connection brokering, Automation adaptation, arbitrary install hooks, or an Agent Server WebSocket capability.
+Use this reference when an App needs a service in addition to its browser bundle. Choose either an optional package-owned managed backend, when the target Agent Server and Canvas host expose that capability, or a manual/deployment-owned Sidecar. Browser-only Apps remain valid.
+
+The managed-backend contract is available on the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Until a release containing both lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` in `GET /server_info`; absence means the managed view path is unsupported, not that the App should guess a port or fall back to hidden Canvas state. Use the host helper only at the minimum host version documented in [v1-contract.md](v1-contract.md).
 
 ## Keep three boundaries
 
-1. **Canvas App package**: ship `canvas-extension.json` and exactly one self-contained browser ESM entrypoint exporting `activate(host)`. Bundle UI dependencies, CSS, and required assets into that entrypoint.
-2. **Sidecar distribution**: distribute the service, its versioned artifacts, and its service-specific installation and operation mechanism separately.
-3. **Onboarding and operator layer**: implement this as a guided UI in the App view. Present status, disclosures, explicit consent, and lifecycle actions there. Do not infer that installing or enabling the Canvas App authorizes any Sidecar mutation.
+1. **Canvas App UI**: always ship `canvas-extension.json` and exactly one self-contained browser ESM entrypoint exporting `activate(host)`. Bundle UI dependencies, CSS, and required assets into that entrypoint.
+2. **Service distribution and ownership**: for a managed backend, declare checksum-pinned platform artifacts in the same package and let the owning Agent Server prepare and run them. For a manual Sidecar, distribute and operate the service separately. Do not combine the models or add a general install hook.
+3. **Onboarding and operator layer**: implement this as guided UI in the App view. Present status, disclosures, explicit revision-bound consent, and lifecycle actions there. Installing or enabling the App never authorizes backend preparation or startup.
+
+## Declare a package-owned managed backend
+
+Add the optional `backend` block only when the App owns its service artifacts:
+
+```json
+{
+  "backend": {
+    "schema_version": 1,
+    "artifacts": {
+      "linux-amd64": {
+        "path": "backend/linux-amd64.tar.gz",
+        "sha256": "<64 lowercase hex characters>"
+      },
+      "linux-arm64": {
+        "path": "backend/linux-arm64.tar.gz",
+        "sha256": "<64 lowercase hex characters>"
+      }
+    },
+    "argv": [
+      "{artifact_dir}/bin/server",
+      "--host=127.0.0.1",
+      "--port={port}",
+      "--data-dir={data_dir}"
+    ],
+    "health": {
+      "path": "/health",
+      "timeout_seconds": 30,
+      "interval_seconds": 0.1
+    },
+    "inherit_environment": ["LANG", "PATH", "TZ"]
+  }
+}
+```
+
+Artifact paths are package-relative `.tar.gz` files. The executable in `argv[0]` must resolve inside `{artifact_dir}`. The argv is a structured string list, never shell source; supported placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`. The current server supports Linux amd64 and arm64 and reports other platforms as `unsupported`.
 
 ## Choose a connection boundary
 
 Prefer connection patterns in this order:
 
-1. **Narrow Agent Server bridge**: add a backend-owned, authenticated endpoint for the required Sidecar operations and call it through `host.agentServer.request` with root-relative paths. Keep Sidecar credentials and routing on the backend.
-2. **Documented future or deployment capability**: require a host or deployment adapter that deliberately exposes Sidecar access, feature-detect it, and document the required version and deployment contract.
-3. **Direct browser connection only when explicitly non-portable**: document its origin, authentication, exposure, and deployment ownership. Do not represent this design as a portable host API 1 App.
-4. **Bounded polling through the Agent Server**: use a narrow bridge for status where live events are unavailable in v1. Bound intervals, respect visibility, abort on disposal, and show stale state.
+1. **Managed backend view**: for a package-owned backend, feature-detect `host.appBackendView` and call `host.appBackendView.mount({ container })`. Canvas owns session creation, iframe isolation, ingress validation, and revocation.
+2. **Narrow Agent Server bridge**: for a manual Sidecar, add a backend-owned, authenticated endpoint for only the required operations and call it through `host.agentServer.request` with root-relative paths. Keep Sidecar credentials and routing on the backend.
+3. **Documented deployment capability**: require a deployment adapter that deliberately exposes Sidecar access, feature-detect it, and document its version and contract.
+4. **Direct browser connection only when explicitly non-portable**: document its origin, authentication, exposure, and deployment ownership. Do not represent this design as a portable host API 1 App.
+5. **Bounded polling through the Agent Server**: use a narrow bridge for status where live events are unavailable in v1. Bound intervals, respect visibility, abort on disposal, and show stale state.
 
 Reject guessed localhost names or ports, `window.location` derivation, Canvas internals, undocumented globals, and embedded credentials. Do not attempt to route a Sidecar or Automation call through `host.agentServer.request` without a documented Agent Server bridge.
 
 ## Model onboarding and operations
 
-Represent service state explicitly: `unknown`, `probing`, `missing`, `stopped`, `incompatible`, `ready`, and `unhealthy`. Preserve actionable failures and transition deliberately for consent, install, start, repair, upgrade, and stop failures. Treat unavailable Sidecar status as a supported UI state.
+For a managed backend, use the server states exactly: `missing`, `stopped`, `starting`, `ready`, `unhealthy`, and `unsupported`. For a manual Sidecar, model additional UI-only states such as `unknown`, `probing`, and `incompatible` when needed. Preserve actionable failures and transition deliberately for consent, prepare/install, start, repair, upgrade, and stop failures.
 
-Before any mutating action, disclose the source, version, checksum, install and data paths, ports and network exposure, process behavior, credentials, and rollback or uninstall behavior. Obtain explicit consent for each applicable action.
+Before any mutating action, disclose the source, resolved revision, version, checksums, install and data paths, ports and network exposure, process behavior, inherited environment names, and rollback or uninstall behavior. Obtain explicit consent for each applicable action. Managed-backend prepare and start calls carry the exact installed revision; updating the package invalidates prior approval.
 
 Keep these actions separate and idempotent where meaningful: