openhands-extensions 0.24.0__tar.gz → 0.26.0__tar.gz

{openhands_extensions-0.24.0 → openhands_extensions-0.26.0}/.github/pull_request_template.md

@@ -1,11 +1,26 @@
 <!-- Keep this PR as draft until it is ready for review. -->
 
-<!-- AI/LLM agents: be concise and specific. Do not check the box below. -->
+<!-- AI/LLM agents:
+Do not edit the HUMAN section.
+-->
+
+HUMAN:
 
-- [ ] A human has tested these changes.
+<!--
+Human author: please replace this comment with a short note (at least 20 visible
+characters) before marking ready for review.
+AI agents: you must not edit this section.
+-->
 
 ---
 
+AGENT:
+<!-- AI/LLM agents:
+In the AGENT section and the template fields below, provide evidence that the
+code runs properly end-to-end. Just running unit tests is NOT sufficient. Explain
+exactly what command you ran and include logs, screenshots, or reproduction notes.
+-->
+
 ## Why
 
 <!-- Describe problem, motivation, etc.-->

{openhands_extensions-0.24.0 → openhands_extensions-0.26.0}/.github/scripts/check_pr_description.py

@@ -1,12 +1,17 @@
 """Validate a pull request description against the repository PR template.
 
-Two gates:
+Three gates:
 
-1. Template sections: the `## Why`, `## Summary`, and `## How to Test`
+1. Human/agent authorship: the first visible line must be `HUMAN:`, it must be
+   followed by a short human-written note before the `AGENT:` marker, and the
+   `AGENT:` marker itself must remain. This keeps the human attestation
+   distinguishable from agent-authored content.
+
+2. Template sections: the `## Why`, `## Summary`, and `## How to Test`
    sections from `.github/pull_request_template.md` must be present and
    filled in.
 
-2. Linked-issue readiness: every issue linked via a closing keyword
+3. Linked-issue readiness: every issue linked via a closing keyword
    (`Fixes #123`, `Closes #123`, `Resolves #123`) or referenced in the
    `## Issue Number` section must exist and, unless it predates the
    `ready-for-dev` rollout, carry the `ready-for-dev` label. This blocks
@@ -30,12 +35,25 @@ import urllib.error
 import urllib.request
 from pathlib import Path
 
+# `markdown_sections` is a sibling in this directory, which is not on sys.path
+# when the module is imported from a file location (the loader-based tests).
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from markdown_sections import find_headings, without_fenced_code_blocks
+
 
+# Reject placeholders while allowing a concise human-written sentence.
+MIN_HUMAN_NOTE_CHARS = 20
 # These are the only PR-template sections that must remain and contain content.
 REQUIRED_TEMPLATE_FIELDS: tuple[str, ...] = ("Why", "Summary", "How to Test")
 
 HTML_COMMENT_RE = re.compile(r"<!--[\s\S]*?-->")
-HEADING_RE = re.compile(r"(?m)^##\s+(.+?)\s*$")
+HEADING_RE = re.compile(r"(?m)^##[ \t]+(.+?)[ \t]*$")
+# `\r?$` rather than `\s*$`: these run against masked text too, and there is no
+# capture group here to absorb the `\r` of a CRLF body, so it is matched
+# explicitly.
+HUMAN_HEADING_RE = re.compile(r"(?im)^[ \t]*HUMAN:[ \t]*\r?$")
+AGENT_HEADING_RE = re.compile(r"(?im)^[ \t]*AGENT:[ \t]*\r?$")
 ISSUE_REF_RE = re.compile(r"(?i)\b(?:fix|clos|resolv)(?:e?(?:s|d)?|ing)?\s+#(\d+)")
 BARE_ISSUE_REF_RE = re.compile(r"(?<!\w)#(\d+)")
 READY_FOR_DEV_LABEL = "ready-for-dev"
@@ -59,8 +77,36 @@ def visible_text(text: str) -> str:
     return "\n".join(lines).strip()
 
 
+def first_visible_line(text: str) -> str:
+    for line in HTML_COMMENT_RE.sub("", text).splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return ""
+
+
+def extract_human_note(body: str) -> str:
+    """Return human-written text in the required location before `AGENT:`.
+
+    The markers are located outside fenced code blocks so that quoting the
+    template does not stand in for filling it out. Offsets are preserved by the
+    masking, so the note itself is still read from the original body.
+    """
+    outside_fences = without_fenced_code_blocks(body)
+
+    human_match = HUMAN_HEADING_RE.search(outside_fences)
+    if human_match is None:
+        return ""
+
+    agent_match = AGENT_HEADING_RE.search(outside_fences, human_match.end())
+    if agent_match is None:
+        return ""
+
+    return visible_text(body[human_match.end() : agent_match.start()])
+
+
 def extract_sections(body: str) -> dict[str, str]:
-    matches = list(HEADING_RE.finditer(body))
+    matches = find_headings(body, HEADING_RE)
     sections: dict[str, str] = {}
     for index, match in enumerate(matches):
         start = match.end()
@@ -153,6 +199,19 @@ def validate_linked_issue_ready(
 def validate_pr_body(body: str) -> list[str]:
     errors: list[str] = []
 
+    if first_visible_line(body) != "HUMAN:":
+        errors.append("The first visible line of the PR description must be `HUMAN:`.")
+
+    human_note = extract_human_note(body)
+    if len(human_note) < MIN_HUMAN_NOTE_CHARS:
+        errors.append(
+            f"Add a short human-written note (at least {MIN_HUMAN_NOTE_CHARS} "
+            "characters) between `HUMAN:` and `AGENT:`."
+        )
+
+    if AGENT_HEADING_RE.search(without_fenced_code_blocks(body)) is None:
+        errors.append("Keep the `AGENT:` marker from the PR template.")
+
     sections = extract_sections(body)
     for section in REQUIRED_TEMPLATE_FIELDS:
         if section not in sections:

openhands_extensions-0.26.0/.github/scripts/markdown_sections.py

@@ -0,0 +1,95 @@
+"""Helpers for parsing Markdown sections in GitHub issue and PR bodies."""
+
+import re
+from dataclasses import dataclass
+
+
+# CommonMark allows an opening fence to carry leading indentation, and inside a
+# list item that indentation is measured from the list's content column rather
+# than the left margin. Rather than parse lists, accept any indentation on the
+# opening fence and bound the closing fence relative to it (below).
+FENCE_LINE_RE = re.compile(
+    r"^(?P<indent>[ ]*)(?P<marker>`{3,}|~{3,})(?P<rest>[^\r\n]*)"
+)
+
+# CommonMark lets a closing fence sit up to three spaces further in than the
+# fence it closes; beyond that it is content, not a terminator.
+MAX_CLOSING_INDENT_OFFSET = 3
+
+
+def _mask_line(line: str) -> str:
+    """Replace line content while preserving offsets and line endings."""
+    return "".join(char if char in "\r\n" else " " for char in line)
+
+
+@dataclass(frozen=True)
+class _Fence:
+    """The marker used to open a fenced Markdown code block."""
+
+    char: str
+    length: int
+    indent: int
+
+    @classmethod
+    def opened_by(cls, line: str) -> "_Fence | None":
+        """Return the fence opened by ``line``, if any."""
+        match = FENCE_LINE_RE.match(line)
+        if match is None:
+            return None
+        marker = match.group("marker")
+        return cls(
+            char=marker[0],
+            length=len(marker),
+            indent=len(match.group("indent")),
+        )
+
+    def closed_by(self, line: str) -> bool:
+        """Return whether ``line`` closes this fence."""
+        match = FENCE_LINE_RE.match(line)
+        if match is None:
+            return False
+        marker = match.group("marker")
+        return (
+            marker[0] == self.char
+            and len(marker) >= self.length
+            and len(match.group("indent")) <= self.indent + MAX_CLOSING_INDENT_OFFSET
+            and not match.group("rest").strip()
+        )
+
+
+def without_fenced_code_blocks(body: str) -> str:
+    """Mask fenced code blocks without changing character offsets.
+
+    A fence that is never closed is left untouched. CommonMark would run it to
+    the end of the document, but these parsers gate contributions: one stray
+    marker in a pasted log would hide every heading after it and reject a report
+    whose sections are plainly there. Masking only balanced fences keeps the
+    failure on the side of accepting.
+    """
+    masked_lines: list[str] = []
+    fenced_lines: list[str] = []
+    fence: _Fence | None = None
+
+    for line in body.splitlines(keepends=True):
+        if fence is None:
+            fence = _Fence.opened_by(line)
+            if fence is None:
+                masked_lines.append(line)
+            else:
+                fenced_lines.append(line)
+        else:
+            fenced_lines.append(line)
+            if fence.closed_by(line):
+                masked_lines.extend(_mask_line(text) for text in fenced_lines)
+                fenced_lines.clear()
+                fence = None
+
+    # Whatever is left belongs to an unclosed fence, so it stays as written.
+    masked_lines.extend(fenced_lines)
+
+    return "".join(masked_lines)
+
+
+def find_headings(body: str, heading_re: re.Pattern[str]) -> list[re.Match[str]]:
+    """Return heading matches outside fenced code blocks."""
+    return list(heading_re.finditer(without_fenced_code_blocks(body)))

openhands_extensions-0.26.0/.github/workflows/build-vscode-app.yml

@@ -0,0 +1,30 @@
+name: Build VS Code App
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - apps/vscode/**
+      - .github/workflows/build-vscode-app.yml
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Build installable App package
+        run: node apps/vscode/scripts/package.mjs
+      - name: Validate package files
+        run: |
+          test -f dist/apps/vscode/canvas-extension.json
+          test -f dist/apps/vscode/extension.js
+          test -f dist/apps/vscode/backend/openvscode-linux-amd64.tar.gz
+          test -f dist/apps/vscode/backend/openvscode-linux-arm64.tar.gz
+      - uses: actions/upload-artifact@v4
+        with:
+          name: vscode-app-${{ github.sha }}
+          path: dist/apps/vscode
+          if-no-files-found: error

{openhands_extensions-0.24.0 → openhands_extensions-0.26.0}/.github/workflows/check-extensions.yml

@@ -57,6 +57,9 @@ jobs:
       - name: Check extensions are in sync
         run: python scripts/sync_extensions.py --check
 
+      - name: Check plugin resource dirs are clean
+        run: python scripts/check_plugin_resources.py
+
   sync-sdk-skill:
     permissions:
       contents: read

openhands_extensions-0.26.0/.github/workflows/tests.yml

@@ -0,0 +1,57 @@
+name: Tests
+
+# NOTE: pull_request (not pull_request_target) so checks run against the PR head.
+on:
+  pull_request:
+    branches: ["*"]
+  push:
+    branches: ["main", "master"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: "20"
+
+      - name: Run tests
+        run: uv run --group test pytest tests/
+        env:
+          PYTHONPATH: ${{ github.workspace }}
+
+      # Plugins under plugins/<name>/tests are self-contained (stdlib-only unit
+      # tests that import the plugin's own scripts via importlib). Run them in
+      # a separate step so a plugin failure is attributed to the plugin, not
+      # the root suite. shopt -s nullglob leaves the array empty when no
+      # plugin ships tests, so this step is a no-op in that case.
+      #
+      # PYTHONDONTWRITEBYTECODE=1 keeps __pycache__/*.pyc from being written
+      # next to the plugin's scripts/ directory, which would otherwise leak
+      # into the agent-visible SkillResources manifest the next time the
+      # plugin is loaded via openhands.sdk.skills. See
+      # scripts/check_plugin_resources.py for the matching CI guard.
+      - name: Run plugin tests
+        shell: bash
+        env:
+          PYTHONDONTWRITEBYTECODE: "1"
+        run: |
+          shopt -s nullglob
+          plugin_tests=(plugins/*/tests)
+          if [ ${#plugin_tests[@]} -eq 0 ]; then
+            echo "No plugin tests found; skipping."
+            exit 0
+          fi
+          echo "Discovered plugin test dirs:"
+          printf '  %s\n' "${plugin_tests[@]}"
+          uv run --group test pytest "${plugin_tests[@]}"

openhands_extensions-0.26.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.26.0"
+}

{openhands_extensions-0.24.0 → openhands_extensions-0.26.0}/AGENTS.md

@@ -44,7 +44,8 @@ Before opening a PR:
   - `skills/<skill-name>/README.md` — optional extra docs/examples for humans
 
 - `plugins/` — a catalog of plugins with executable code components.
-  - `plugins/<plugin-name>/SKILL.md` — the plugin definition
+  - `plugins/<plugin-name>/.plugin/plugin.json` — the plugin manifest (the canonical location; `.claude-plugin` and `.codex-plugin` are vendor symlinks to `.plugin`)
+  - `plugins/<plugin-name>/SKILL.md` — the plugin definition (optional; present only on plugins that are also loadable as a skill)
   - `plugins/<plugin-name>/hooks/` — lifecycle hooks (optional)
   - `plugins/<plugin-name>/scripts/` — utility scripts (optional)
 
@@ -165,7 +166,7 @@ Important notes:
 
 ## CI / validation gotchas
 
-- The test suite expects **every directory under `skills/`** to be listed in a marketplace. If you add a new skill (or rebase onto a main branch that added skills), update the appropriate marketplace file or CI will fail with `Skills missing from marketplace: [...]`.
+- The test suite expects **every directory under `skills/`** to be listed in a marketplace. If you add a new skill (or rebase onto a main branch that added skills), update the appropriate marketplace file or CI will fail with `Skills not in any marketplace: [...]` (`test_marketplace_includes_all_skills` in `tests/test_sdk_loading.py`). The `coverage` task in `scripts/sync_extensions.py` checks the same mapping for both `skills/` and `plugins/`, but reports gaps as a non-blocking warning instead of failing.
 - `scripts/sync_extensions.py` keeps generated artifacts in sync: Claude Code command files, README catalog section, coverage checks, and vendor symlinks. Run `python scripts/sync_extensions.py --check` (or just push — CI runs it) to verify everything is consistent. Run without `--check` to auto-fix. The "Quick Start" section in `README.md` (OpenHands SDK, Claude Code, and Codex setup instructions) is **manually maintained** above the auto-generated catalog markers and is intentionally not generated by the sync script.
 - The sync script uses PyYAML to parse SKILL.md frontmatter. If you add a skill with a slash trigger (e.g., `triggers: ["/mycommand"]`), the script auto-generates `commands/mycommand.md`. **Note:** Slash triggers in SKILL.md frontmatter are deprecated — prefer adding a `commands/command-name.md` file to the plugin's `commands/` directory instead. Keyword triggers (non-slash) remain the recommended way to activate skills by topic.
 

{openhands_extensions-0.24.0 → openhands_extensions-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openhands-extensions
-Version: 0.24.0
+Version: 0.26.0
 Summary: OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)
 License-File: LICENSE
 Requires-Python: >=3.12

{openhands_extensions-0.24.0 → openhands_extensions-0.26.0}/README.md

@@ -1,7 +1,7 @@
 # OpenHands Extensions
 
 This repository is the **public extensions registry** for [OpenHands](https://github.com/OpenHands/OpenHands).
-It contains reusable, shareable skills and plugins that customize agent behavior.
+It contains reusable, shareable skills, plugins, and Agent Canvas Apps that customize agent behavior and interfaces.
 
 - Skills overview docs: https://docs.openhands.dev/overview/skills
 - SDK skill guide: https://docs.openhands.dev/sdk/guides/skill
@@ -36,6 +36,10 @@ They live under `plugins/`, **one directory per plugin**:
 
 Browse available plugins in [`plugins/`](plugins/).
 
+### Apps
+
+Apps are installable interfaces that bring dashboards, internal tools, and workflows directly into Agent Canvas without requiring a fork. They are powered by the beta Canvas Extensions API. Browse [`apps/`](apps/) and read its package conventions before contributing. Enabling an App executes trusted JavaScript in the Agent Canvas browser context and permits authenticated requests to the active Agent Server, so review its source and resolved revision first. Apps are distinct from skills and plugins: they provide Canvas interfaces rather than agent instructions or capabilities.
+
 ### NPM Package
 
 This repository also publishes catalog data through the `@openhands/extensions` package. It requires Node.js 18.20.0 or newer because the catalog entry points import JSON modules with import attributes.
@@ -96,7 +100,7 @@ The JS and Python versions are kept in lock-step by `release-please` and guarded
 ## Extensions Catalog
 
 <!-- BEGIN AUTO-GENERATED CATALOG -->
-This repository contains **2 marketplace(s)** with **73 extensions** (63 skills, 10 plugins).
+This repository contains **2 marketplace(s)** with **76 extensions** (65 skills, 11 plugins).
 
 ### large-codebase
 
@@ -115,7 +119,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases
 
 Official skills and plugins for OpenHands — the open-source AI software engineer.
 
-**69 extensions** (61 skills, 8 plugins)
+**72 extensions** (63 skills, 9 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
@@ -148,6 +152,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | github-pr-review | skill | Post structured PR reviews to GitHub with inline comments/suggestions in a single API call. | `/github-pr-review` |
 | github-pr-reviewer | skill | Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed fi... | `/pr-reviewer:setup` |
 | github-repo-monitor | skill | Create a cron automation that polls a GitHub repository for issue and PR comments containing a configurable trigger p... | `/github-monitor:poll` |
+| github-stale-ci-pr-closer | skill | Warn and close abandoned pull requests whose required CI remains failing. | `/github-stale-ci-pr-closer` |
 | gitlab | skill | Interact with GitLab repositories, merge requests, and APIs using the GITLAB_TOKEN environment variable. Use when wor... | — |
 | gitlab-issue-to-mr | skill | Create an automation that implements GitLab issues when a configurable trigger label is applied. Clones the default b... | `/issue-to-mr:setup` |
 | incident-retrospective | skill | Create an automation that drafts incident retrospectives by gathering incident-channel messages from Slack, collectin... | `/incident-retro:setup` |
@@ -175,6 +180,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | qa-changes | plugin | Validate pull request changes by actually running the code — setting up the environment, exercising changed behavior,... | — |
 | release-notes | plugin | Generate consistent, well-structured release notes from git history. Produces categorized changelog with breaking cha... | `/release-notes` |
 | research-brief | skill | Create a recurring automation that researches a topic using Tavily web search and publishes a structured brief to Not... | `/research-brief:setup` |
+| runtime-api-configs | plugin | Manage warm sandbox pools on OpenHands Enterprise from a Python CLI: list, template, save, and delete warm runtime co... | — |
 | security | skill | Security best practices for secure coding, authentication, authorization, and data protection. Use when developing fe... | — |
 | skill-creator | skill | Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an ex... | — |
 | slack-channel-monitor | skill | Create a cron automation that polls up to 10 Slack channels every minute and starts an OpenHands conversation when a ... | `/slack-monitor:poll` |
@@ -185,6 +191,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | theme-factory | skill | Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc.... | — |
 | ticket-to-code-change | skill | Set up Jira or Linear ticket-to-code-change automations for GitHub, GitLab, and Bitbucket. | `/ticket-to-code-change:setup` |
 | upstream-fork-sync | skill | Keep a long-lived fork in sync with its upstream. Creates a cron automation that fetches upstream changes, rebases lo... | `/upstream-fork-sync:setup` |
+| use-jev | skill | Use Jev, a general classifier, for typed choices, scores, and yes/no probabilities in software. | — |
 | uv | skill | Common project, dependency, and environment operations using uv. | — |
 | vercel | skill | Deploy and manage applications on Vercel, including preview deployments and deployment protection. | — |
 | vulnerability-remediation | plugin | Automated security vulnerability scanning and AI-powered remediation. Scans repositories, skips when no issues found,... | — |

openhands_extensions-0.26.0/apps/README.md

@@ -0,0 +1,20 @@
+# Agent Canvas Apps
+
+Apps are installable interfaces that bring dashboards, internal tools, and workflows directly into Agent Canvas without requiring a fork. They are powered by the Canvas Extensions API, which is currently beta.
+
+## Package convention
+
+Each App occupies one directory under `apps/` and is a self-contained Canvas Extension package:
+
+- `canvas-extension.json` declares the package, its routed pages, and an optional package-owned managed backend, following the manifest schema 1 documented in `skills/canvas-extension-api/references/v1-contract.md`. An App that needs a service either declares that managed `backend` or ships a manual/deployment-owned Sidecar, per `skills/canvas-extension-api/references/sidecar-pattern.md`.
+- The manifest's `entrypoint` is a browser ESM module that exports `activate(host)`.
+- App-specific documentation and assets may live beside the manifest and entrypoint.
+- Build output must remain self-contained: browser entrypoints must not import package dependencies at runtime.
+
+The registry catalog is `apps/catalog.json`, exposed to JavaScript consumers as `APPS_CATALOG` from `@openhands/extensions/apps`. Add one catalog entry when adding an App; keep its `source` and `manifest` paths relative to this repository.
+
+## Trust and installation
+
+Enabling an App executes its trusted JavaScript in the Agent Canvas browser context. An App can make authenticated requests to the active Agent Server through the host API. Review the source, manifest, and resolved revision before enabling an App. Apps are not skills or plugins: an App provides a Canvas interface, a skill provides agent instructions, and a plugin provides agent capabilities and configuration.
+
+The host currently supports routed custom pages through the beta Canvas Extensions API. Follow the API documentation and validate packages with the repository's Canvas App validator before submitting a pull request.

openhands_extensions-0.26.0/apps/catalog.json

@@ -0,0 +1,10 @@
+[
+  {
+    "id": "vscode",
+    "name": "VS Code",
+    "description": "A managed full-height OpenVSCode editor for the selected Agent Canvas workspace.",
+    "source": "./apps/vscode",
+    "manifest": "./apps/vscode/canvas-extension.json",
+    "beta": true
+  }
+]

openhands_extensions-0.26.0/apps/index.d.ts

@@ -0,0 +1,11 @@
+export interface AppCatalogEntry {
+  id: string;
+  name: string;
+  description: string;
+  source: string;
+  manifest: string;
+  beta: boolean;
+}
+
+export const APPS_CATALOG: AppCatalogEntry[];
+export default APPS_CATALOG;

openhands_extensions-0.26.0/apps/index.js

@@ -0,0 +1,5 @@
+import catalog from "./catalog.json" with { type: "json" };
+
+/** Discoverable Agent Canvas Apps from this registry. */
+export const APPS_CATALOG = catalog;
+export default APPS_CATALOG;

openhands_extensions-0.26.0/apps/vscode/README.md

@@ -0,0 +1,13 @@
+# VS Code App
+
+This App provides a full-height OpenVSCode editor. Before the backend is ready, the App shows backend status, an explicit workspace-folder input, and revision-bound prepare/start/stop/refresh actions. Once ready, the page contains only the editor iframe. The folder is persisted in browser storage and sent as an optional `query.folder` mount parameter; it is a user convenience, not OS sandboxing.
+
+## Artifact delivery
+
+The repository intentionally contains no OpenVSCode binaries. `scripts/package.mjs` downloads the pinned upstream OpenVSCode Server `v1.109.5` Linux amd64 and arm64 archives, verifies their upstream checksums, normalizes the archive layout and metadata, and writes the package-contained archives required by `canvas-extension.json`. The GitHub Actions workflow publishes the resulting `vscode-app-<commit>` artifact; that archive is the installable coordinate for this revision.
+
+The package is not a release until reviewed and merged. The workflow artifact is a development delivery coordinate, not a published release or a version pin for Agent Server. This App depends on the Canvas consumer change that adds optional `mount({ container, query: { folder } })` support; until that consumer PR lands, setup works but the selected folder is not forwarded to OpenVSCode.
+
+The backend uses app-owned data directories for user data and extensions and receives only the manifest allowlisted environment. It does not receive Agent Server credentials. OpenVSCode starts at the existing app-owned `{data_dir}` by default; the optional folder query changes the editor folder only when the Canvas consumer supports it. Folder selection is not OS sandboxing.
+
+The real ngrok editor/save/terminal click-through GIF is maintained in the Agent Canvas implementation PR as development-stack evidence. It is not bundled here and is not a release or package test.

openhands_extensions-0.26.0/apps/vscode/canvas-extension.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": 1,
+  "name": "vscode",
+  "display_name": "VS Code",
+  "version": "0.1.0",
+  "description": "A managed OpenVSCode editor for the selected Agent Canvas workspace.",
+  "entrypoint": "extension.js",
+  "contributes": {"pages": [{"id": "editor", "title": "VS Code", "path": "/editor"}]},
+  "backend": {
+    "schema_version": 1,
+    "artifacts": {
+      "linux-amd64": {"path": "backend/openvscode-linux-amd64.tar.gz", "sha256": "5ad14274cc5e5ed938ffecf1dd53c0e58272828d8b50cb5da93b6d9e5d2cd9d5"},
+      "linux-arm64": {"path": "backend/openvscode-linux-arm64.tar.gz", "sha256": "91876160f1b549020204e3909ad42a80d22ef0ebf66a62306cdf60ca5d44524b"}
+    },
+    "argv": ["{artifact_dir}/bin/openvscode-bootstrap", "--host", "127.0.0.1", "--port", "{port}", "--without-connection-token", "--accept-server-license-terms", "--telemetry-level", "off", "--user-data-dir", "{data_dir}/user", "--extensions-dir", "{data_dir}/extensions", "--server-base-path", "/app-backends/vscode", "{data_dir}"],
+    "health": {"path": "/", "timeout_seconds": 90, "interval_seconds": 0.5},
+    "inherit_environment": ["PATH", "LANG", "LC_ALL", "TMPDIR"]
+  }
+}

openhands_extensions-0.26.0/apps/vscode/extension.js

@@ -0,0 +1,114 @@
+const BACKEND = "/api/canvas-extensions/installed/vscode/backend";
+const FOLDER_KEY_PREFIX = "openhands.apps.vscode.folder";
+
+function folderKey(host) {
+  return `${FOLDER_KEY_PREFIX}:${host.backend.id}:${host.backend.orgId || "local"}:${host.extension.name}`;
+}
+
+function button(label, onClick) {
+  const element = document.createElement("button");
+  element.type = "button";
+  element.textContent = label;
+  element.addEventListener("click", onClick);
+  return element;
+}
+
+export function activate(host) {
+  return host.registerPage("editor", async ({ container }) => {
+    container.style.minHeight = "100vh";
+    const shell = document.createElement("div");
+    shell.style.cssText = "height:100vh;min-height:100vh;width:100%;display:flex;flex-direction:column";
+    container.replaceChildren(shell);
+
+    if (!host.appBackendView) {
+      const error = document.createElement("p");
+      error.setAttribute("role", "alert");
+      error.textContent = "VS Code is unavailable because this Agent Server does not support managed App backends.";
+      shell.append(error);
+      return () => container.replaceChildren();
+    }
+
+    let disposed = false;
+    let mounted;
+    const storageKey = folderKey(host);
+    const request = (method, path = BACKEND, body) => host.agentServer.request({ method, path, ...(body ? { body } : {}) });
+    const cleanup = () => {
+      disposed = true;
+      mounted?.();
+      mounted = undefined;
+      container.replaceChildren();
+    };
+
+    const render = (status) => {
+      if (disposed) return;
+      shell.replaceChildren();
+      if (status.state === "ready") {
+        const editor = document.createElement("div");
+        editor.style.cssText = "flex:1;min-height:100vh;width:100%;overflow:hidden";
+        shell.append(editor);
+        const folder = localStorage.getItem(storageKey)?.trim();
+        mounted = host.appBackendView.mount({
+          container: editor,
+          ...(folder ? { query: { folder } } : {}),
+        });
+        return;
+      }
+
+      const panel = document.createElement("section");
+      panel.setAttribute("aria-live", "polite");
+      const heading = document.createElement("h2");
+      heading.textContent = "VS Code setup";
+      const detail = document.createElement("p");
+      detail.textContent = status.detail || `Backend status: ${status.state}.`;
+      panel.append(heading, detail);
+      const folder = document.createElement("input");
+      folder.type = "text";
+      folder.placeholder = "Workspace folder path (optional)";
+      folder.value = localStorage.getItem(storageKey) || "";
+      folder.setAttribute("aria-label", "Workspace folder path");
+      panel.append(folder);
+      const actions = document.createElement("p");
+      if (status.state === "missing" || status.state === "stopped" || status.state === "unhealthy") {
+        actions.append(button("Prepare and start", async () => {
+          const selectedFolder = folder.value.trim();
+          if (selectedFolder) localStorage.setItem(storageKey, selectedFolder);
+          else localStorage.removeItem(storageKey);
+          actions.replaceChildren(document.createTextNode("Preparing..."));
+          try {
+            let approval = status;
+            if (!approval.revision) approval = await request("GET");
+            if (!approval.revision) throw new Error("The backend did not report an immutable revision.");
+            try {
+              await request("POST", `${BACKEND}/prepare`, { revision: approval.revision });
+            } catch (error) {
+              if (error?.status !== 409) throw error;
+              approval = await request("GET");
+              if (!approval.revision) throw error;
+              await request("POST", `${BACKEND}/prepare`, { revision: approval.revision });
+            }
+            await request("POST", `${BACKEND}/start`, { revision: approval.revision });
+            render(await request("GET"));
+          } catch (error) {
+            detail.textContent = `Setup failed: ${error.message}`;
+            actions.replaceChildren(button("Prepare and start", () => render(status)));
+          }
+        }));
+      }
+      if (status.state === "ready" || status.state === "starting") {
+        actions.append(button("Stop", async () => render(await request("POST", `${BACKEND}/stop`))));
+      }
+      actions.append(button("Refresh", async () => render(await request("GET"))));
+      panel.append(actions);
+      shell.append(panel);
+    };
+
+    try { render(await request("GET")); }
+    catch (error) {
+      const failure = document.createElement("p");
+      failure.setAttribute("role", "alert");
+      failure.textContent = `Unable to read VS Code backend status: ${error.message}`;
+      shell.replaceChildren(failure);
+    }
+    return cleanup;
+  });
+}