@openhands/extensions 0.29.0 → 0.31.0

package/.agents/skills/custom-codereview-guide.md

@@ -27,7 +27,32 @@ Cross-repository work is acceptable when this PR contains only the
 extensions-owned portion and relies on public interfaces from the owning
 repository.
 
-## Blocking checkpoints
+## Issue triage
+
+Issue readiness means the work is clear enough to start—not that the fix is
+complete. Do not require a PR, passing implementation tests, or before-and-after
+fix evidence. Reconsider readiness when new information leaves scope or expected
+behavior unresolved. Read the issue, linked discussion, applicable `AGENTS.md`,
+and adjacent source before asking questions.
+
+For API failures, compare the extension request with the provider's reported or
+supported version, not upstream main. Use dependency pins or deployment evidence.
+Instructions, request arguments, response parsing, and scanner policy belong
+here; use the ownership boundaries above for other failures. State required
+cross-repository changes and their order. An independent upstream defect need
+not block this work. Naming an owner does not authorize edits or duplicate tickets.
+
+Define the smallest useful outcome and explicit non-goals. Cover only affected
+entrypoints, environments, and permissions. For scanners, state whether discovery,
+commenting, and dispatch are allowed for ineligible candidates or after a cap.
+Discovery alone does not authorize unsolicited comments.
+
+Request visual evidence only when needed; otherwise use logs, minimal
+reproductions, or failing tests. Do not repeat answered questions. Match managed
+criteria to current human decisions and authoritative readiness policy. Report
+conflicts instead of repeatedly adding a label that policy removes.
+
+## Implementation review checkpoints
 
 ### Executable instructions and runtime parity
 
@@ -42,6 +67,16 @@ in a clean environment far enough to exercise the changed behavior. Keep local
 and cloud behavior identical unless the documentation names and explains a real
 platform capability difference.
 
+For provider changes, inspect the supported implementation; mocks and local types
+alone do not establish an API contract. Separate static/helper tests, tests with
+simulated services, and real integration evidence. If the version or runtime is
+unavailable, report that limit, not an assumed defect. For packaging changes,
+check source, shipped bundle, and deployed files separately.
+
+For scanners, check eligibility, permissions, caps, retries, unchanged runs, and
+recovery for each action listed under triage. A launch cap does not permit
+unlimited gate comments.
+
 ### Untrusted triggers and credentials
 
 Treat repository events, issue and PR comments, chat messages, catalog fields,
@@ -111,10 +146,9 @@ deep change lacks it, weigh the gap by risk:
   the diff would materially slow or weaken the review.
 - **LOW** risk: never block on missing design context alone.
 
-Approving a same-repository PR removes its `.pr/` directory. If a temporary
-`.pr/` page is the only design explanation, submit a COMMENT review instead of
-approving, so the page remains for the human maintainer's decision, unless the
-PR description already carries the durable equivalent.
+Temporary `.pr/` artifacts remain available during review and are removed through
+a cleanup PR after merge to `main`. Preserve any design explanation needed beyond
+that cleanup in the PR description or permanent documentation.
 
 Design context aids review; it does not excuse correctness, security,
 architecture, or repository-ownership problems.
@@ -130,3 +164,11 @@ Do not comment on punctuation, preferred prose tone, optional DRY cleanup, or
 hypothetical non-standard configurations without a supported failure mode. Before
 raising a finding, verify that the referenced file and behavior are present in
 the current PR head and have not already been addressed in review history.
+
+## Review verdict
+
+Do not approve material code defects or unmet blocking merge/evidence checks.
+Distinguish code defects from missing merge requirements and optional follow-up.
+If GitHub forbids self-approval of a clean PR, use COMMENT and explain why.
+Respect accepted scope and non-goals: block on a pre-existing limitation only if
+this change exposes it.

package/.claude-plugin/marketplace.json

@@ -92,6 +92,19 @@
         "openhands"
       ]
     },
+    {
+      "name": "software-factory",
+      "source": "./skills/software-factory",
+      "description": "Set up a GitHub software factory fast: ask only for the repositories and the ticket source (GitHub issues, Jira or Linear), create a working issue-to-PR and PR-review pipeline from catalog automations with defaults, then let the user stop or extend it step by step.",
+      "category": "automations",
+      "keywords": [
+        "onboarding",
+        "software-factory",
+        "github",
+        "automation",
+        "pull-request"
+      ]
+    },
     {
       "name": "agent-canvas-environment",
       "source": "./skills/agent-canvas-environment",
@@ -752,7 +765,7 @@
     {
       "name": "gitlab-issue-to-mr",
       "source": "./skills/gitlab-issue-to-mr",
-      "description": "Create an automation that implements GitLab issues when a configurable trigger label is applied. Clones the default branch for the agent, then commits, pushes, and opens the merge request itself - the agent is handed no push credential.",
+      "description": "Create an automation that implements GitLab issues when a configurable trigger label is applied. Polls the projects deterministically and starts one conversation per label event; on OpenHands Cloud and Enterprise it reaches GitLab through the connected MCP server or integration, with no token to set up.",
       "category": "automations",
       "keywords": [
         "gitlab",
@@ -851,11 +864,14 @@
     {
       "name": "jira-issue-to-pr",
       "source": "./skills/jira-issue-to-pr",
-      "description": "Deploy a cron-based OpenHands automation that watches a Jira Cloud project for issues labeled with a configurable label (default: create-pr) and spawns an agent conversation to create a GitHub pull request for each new issue found. The target GitHub repo is read from the ticket body - no repo parameter required at deploy time.",
+      "description": "Deploy a cron-based OpenHands automation that opens a GitHub pull request, a GitLab merge request or a Bitbucket pull request for each Jira issue carrying a configurable label (default: create-pr). The target repository is read from the ticket body - no repo parameter required at deploy time.",
       "category": "automations",
       "keywords": [
         "jira",
-        "atlassian"
+        "atlassian",
+        "github",
+        "gitlab",
+        "bitbucket"
       ]
     },
     {
@@ -873,10 +889,9 @@
     {
       "name": "ticket-to-code-change",
       "source": "./skills/ticket-to-code-change",
-      "description": "Set up Jira or Linear ticket-to-code-change automations for GitHub, GitLab, and Bitbucket.",
+      "description": "Set up Linear ticket-to-code-change automations for GitHub, GitLab, and Bitbucket.",
       "category": "automations",
       "keywords": [
-        "jira",
         "linear",
         "github",
         "gitlab",

package/.codex-plugin/marketplace.json

@@ -92,6 +92,19 @@
         "openhands"
       ]
     },
+    {
+      "name": "software-factory",
+      "source": "./skills/software-factory",
+      "description": "Set up a GitHub software factory fast: ask only for the repositories and the ticket source (GitHub issues, Jira or Linear), create a working issue-to-PR and PR-review pipeline from catalog automations with defaults, then let the user stop or extend it step by step.",
+      "category": "automations",
+      "keywords": [
+        "onboarding",
+        "software-factory",
+        "github",
+        "automation",
+        "pull-request"
+      ]
+    },
     {
       "name": "agent-canvas-environment",
       "source": "./skills/agent-canvas-environment",
@@ -752,7 +765,7 @@
     {
       "name": "gitlab-issue-to-mr",
       "source": "./skills/gitlab-issue-to-mr",
-      "description": "Create an automation that implements GitLab issues when a configurable trigger label is applied. Clones the default branch for the agent, then commits, pushes, and opens the merge request itself - the agent is handed no push credential.",
+      "description": "Create an automation that implements GitLab issues when a configurable trigger label is applied. Polls the projects deterministically and starts one conversation per label event; on OpenHands Cloud and Enterprise it reaches GitLab through the connected MCP server or integration, with no token to set up.",
       "category": "automations",
       "keywords": [
         "gitlab",
@@ -851,11 +864,14 @@
     {
       "name": "jira-issue-to-pr",
       "source": "./skills/jira-issue-to-pr",
-      "description": "Deploy a cron-based OpenHands automation that watches a Jira Cloud project for issues labeled with a configurable label (default: create-pr) and spawns an agent conversation to create a GitHub pull request for each new issue found. The target GitHub repo is read from the ticket body - no repo parameter required at deploy time.",
+      "description": "Deploy a cron-based OpenHands automation that opens a GitHub pull request, a GitLab merge request or a Bitbucket pull request for each Jira issue carrying a configurable label (default: create-pr). The target repository is read from the ticket body - no repo parameter required at deploy time.",
       "category": "automations",
       "keywords": [
         "jira",
-        "atlassian"
+        "atlassian",
+        "github",
+        "gitlab",
+        "bitbucket"
       ]
     },
     {
@@ -873,10 +889,9 @@
     {
       "name": "ticket-to-code-change",
       "source": "./skills/ticket-to-code-change",
-      "description": "Set up Jira or Linear ticket-to-code-change automations for GitHub, GitLab, and Bitbucket.",
+      "description": "Set up Linear ticket-to-code-change automations for GitHub, GitLab, and Bitbucket.",
       "category": "automations",
       "keywords": [
-        "jira",
         "linear",
         "github",
         "gitlab",

package/.github/workflows/build-vscode-app.yml

@@ -14,15 +14,15 @@ jobs:
       - uses: actions/checkout@v7
       - uses: actions/setup-node@v7
         with:
-          node-version: "20"
+          node-version: "24"
       - 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
+          test -f dist/apps/vscode/README.md
+          test -z "$(find dist/apps/vscode -type f -name '*.tar.gz' -print -quit)"
       - uses: actions/upload-artifact@v7
         with:
           name: vscode-app-${{ github.sha }}

package/.github/workflows/check-extensions.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v7
         with:
-          node-version: "20"
+          node-version: "24"
 
       - name: Install Claude Code CLI
         run: npm install -g @anthropic-ai/claude-code

package/.github/workflows/pr-artifacts.yml

@@ -6,84 +6,9 @@ on:
     pull_request_target:
         types: [opened, synchronize, reopened, closed]
         branches: [main]
-    pull_request_review:
-        types: [submitted]
 
 jobs:
-  # Auto-remove .pr/ directory from same-repository PRs when approved.
-    cleanup-on-approval:
-        concurrency:
-            group: cleanup-pr-artifacts-${{ github.event.pull_request.number }}
-            cancel-in-progress: false
-        if: >-
-            github.event_name == 'pull_request_review' &&
-            github.event.review.state == 'approved' &&
-            github.event.pull_request.head.repo.full_name == github.repository
-        runs-on: ubuntu-latest
-        permissions:
-            contents: write
-            pull-requests: write
-        steps:
-            # Use PAT so the push triggers CI workflows that will complete and
-            # satisfy branch protection. We can't use [skip ci] because GitHub Apps
-            # can create stuck checks that block merging.
-            - uses: actions/checkout@v7
-              with:
-                  ref: ${{ github.event.pull_request.head.ref }}
-                  token: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC }}
-
-            - name: Remove .pr/ directory
-              id: remove
-              run: |
-                  if [ -d ".pr" ]; then
-                    git config user.name "allhands-bot"
-                    git config user.email "allhands-bot@users.noreply.github.com"
-                    git rm -rf .pr/
-                    git commit -m "chore: Remove PR-only artifacts [automated]"
-                    git push || {
-                      echo "::error::Failed to push cleanup commit. Check branch protection rules."
-                      exit 1
-                    }
-                    echo "removed=true" >> "$GITHUB_OUTPUT"
-                    echo "::notice::Removed .pr/ directory"
-                  else
-                    echo "removed=false" >> "$GITHUB_OUTPUT"
-                    echo "::notice::No .pr/ directory to remove"
-                  fi
-
-            - name: Update PR comment after cleanup
-              if: steps.remove.outputs.removed == 'true'
-              uses: actions/github-script@v9
-              with:
-                  script: |
-                      const marker = '<!-- pr-artifacts-notice -->';
-                      const body = `${marker}
-                      ✅ **PR Artifacts Cleaned Up**
-
-                      The \`.pr/\` directory has been automatically removed.
-                      `;
-
-                      const comments = await github.paginate(
-                        github.rest.issues.listComments,
-                        {
-                          owner: context.repo.owner,
-                          repo: context.repo.repo,
-                          issue_number: context.issue.number,
-                          per_page: 100,
-                        },
-                      );
-
-                      const existing = comments.find(c => c.body.includes(marker));
-                      if (existing) {
-                        await github.rest.issues.updateComment({
-                          owner: context.repo.owner,
-                          repo: context.repo.repo,
-                          comment_id: existing.id,
-                          body: body,
-                        });
-                      }
-
-  # Inspect the fork through the API; never check out untrusted code with a write token.
+  # Inspect PR artifacts through the API; never check out untrusted code with a write token.
     check-pr-artifacts:
         if: >-
             github.event_name == 'pull_request_target' &&
@@ -144,14 +69,10 @@ jobs:
                         return;
                       }
 
-                      const isFork = headRepository.full_name !== context.payload.repository.full_name;
-                      const cleanup = isFork
-                        ? 'Because this is a fork PR, the workflow will **open or update a cleanup PR against `main` after merge**.'
-                        : 'The directory will be **automatically removed when the PR is approved**.';
                       const body = `${marker}
                       📁 **PR Artifacts Notice**
 
-                      This PR contains a \`.pr/\` directory with temporary PR-specific documents. ${cleanup}
+                      This PR contains a \`.pr/\` directory with temporary PR-specific documents. The directory will be **automatically removed after this PR merges to \`main\`** through a cleanup PR opened or updated by this workflow.
                       `;
 
                       core.warning('.pr/ directory contains temporary PR-only artifacts');
@@ -171,8 +92,8 @@ jobs:
                         });
                       }
 
-  # Fork branches cannot be modified reliably. If artifacts reach the trusted base,
-  # remove them through a pull request so branch protections remain enforced.
+  # Remove artifacts from all merged PRs through the trusted base cleanup path,
+  # preserving branch protections and avoiding a cleanup push during review.
     cleanup-after-merge:
         concurrency:
             group: cleanup-pr-artifacts-${{ github.event.pull_request.base.ref }}

package/.github/workflows/tests.yml

@@ -14,6 +14,19 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
 
+      - name: Reject temporary artifacts in release PRs
+        if: >-
+          github.event_name == 'pull_request' &&
+          startsWith(github.head_ref, 'release-please--')
+        run: |
+          set -euo pipefail
+          artifacts="$(git ls-tree -r --name-only HEAD -- .pr)"
+          if [ -n "$artifacts" ]; then
+            echo "::error::Release PR contains temporary .pr artifacts. Merge the cleanup PR and let release-please update this PR before merging."
+            printf '%s\n' "$artifacts"
+            exit 1
+          fi
+
       - name: Install uv
         uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
@@ -23,7 +36,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v7
         with:
-          node-version: "20"
+          node-version: "24"
 
       - name: Run tests
         run: uv run --group test pytest tests/

package/.plugin/marketplace.json

@@ -92,6 +92,19 @@
         "openhands"
       ]
     },
+    {
+      "name": "software-factory",
+      "source": "./skills/software-factory",
+      "description": "Set up a GitHub software factory fast: ask only for the repositories and the ticket source (GitHub issues, Jira or Linear), create a working issue-to-PR and PR-review pipeline from catalog automations with defaults, then let the user stop or extend it step by step.",
+      "category": "automations",
+      "keywords": [
+        "onboarding",
+        "software-factory",
+        "github",
+        "automation",
+        "pull-request"
+      ]
+    },
     {
       "name": "agent-canvas-environment",
       "source": "./skills/agent-canvas-environment",
@@ -752,7 +765,7 @@
     {
       "name": "gitlab-issue-to-mr",
       "source": "./skills/gitlab-issue-to-mr",
-      "description": "Create an automation that implements GitLab issues when a configurable trigger label is applied. Clones the default branch for the agent, then commits, pushes, and opens the merge request itself - the agent is handed no push credential.",
+      "description": "Create an automation that implements GitLab issues when a configurable trigger label is applied. Polls the projects deterministically and starts one conversation per label event; on OpenHands Cloud and Enterprise it reaches GitLab through the connected MCP server or integration, with no token to set up.",
       "category": "automations",
       "keywords": [
         "gitlab",
@@ -851,11 +864,14 @@
     {
       "name": "jira-issue-to-pr",
       "source": "./skills/jira-issue-to-pr",
-      "description": "Deploy a cron-based OpenHands automation that watches a Jira Cloud project for issues labeled with a configurable label (default: create-pr) and spawns an agent conversation to create a GitHub pull request for each new issue found. The target GitHub repo is read from the ticket body - no repo parameter required at deploy time.",
+      "description": "Deploy a cron-based OpenHands automation that opens a GitHub pull request, a GitLab merge request or a Bitbucket pull request for each Jira issue carrying a configurable label (default: create-pr). The target repository is read from the ticket body - no repo parameter required at deploy time.",
       "category": "automations",
       "keywords": [
         "jira",
-        "atlassian"
+        "atlassian",
+        "github",
+        "gitlab",
+        "bitbucket"
       ]
     },
     {
@@ -873,10 +889,9 @@
     {
       "name": "ticket-to-code-change",
       "source": "./skills/ticket-to-code-change",
-      "description": "Set up Jira or Linear ticket-to-code-change automations for GitHub, GitLab, and Bitbucket.",
+      "description": "Set up Linear ticket-to-code-change automations for GitHub, GitLab, and Bitbucket.",
       "category": "automations",
       "keywords": [
-        "jira",
         "linear",
         "github",
         "gitlab",

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.29.0"
+  ".": "0.31.0"
 }

package/AGENTS.md

@@ -146,7 +146,7 @@ When editing or adding skills in this repo, follow these rules (and add new skil
 
 ## PR-specific documents (`.pr/`)
 
-When working on a PR that requires design documents, live-test logs, development-only scripts, or other temporary artifacts that should **not** be merged to `main`, store them in a `.pr/` directory at the repository root.
+When working on a PR that requires design documents, live-test logs, development-only scripts, or other temporary artifacts that should be removed after merging to `main`, store them in a `.pr/` directory at the repository root.
 
 ```bash
 mkdir -p .pr
@@ -160,14 +160,15 @@ mkdir -p .pr
 The `PR Artifacts` workflow (`.github/workflows/pr-artifacts.yml`) owns the lifecycle of this directory:
 
 1. **Notification**: When a PR contains `.pr/`, a single comment is posted to the PR conversation alerting reviewers.
-2. **Auto-cleanup on approval**: For same-repository PRs, the directory is automatically removed by a follow-up commit when the PR is approved.
-3. **Post-merge cleanup**: If artifacts reach `main`, including through a fork PR, the workflow opens or updates a cleanup PR against `main`.
+2. **Post-merge cleanup**: After a same-repository or fork PR merges to `main`, the workflow automatically opens or updates a cleanup PR to remove the directory from `main`.
 
 Important notes:
 
 - Do not put anything in `.pr/` that needs to be preserved.
 - The `.pr/` check is informational during development; it posts a notice rather than blocking the PR.
 - Cleanup PRs follow the normal review and required-check protections for `main`.
+- npm packaging excludes `.pr/` while its cleanup PR is pending, so temporary review artifacts do not ship in releases.
+- Release PRs fail the required `test` check while their committed tree contains `.pr/`. Merge the artifact-cleanup PR and let release-please update the release PR before merging it.
 
 ## CI / validation gotchas
 

package/README.md

@@ -100,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 **77 extensions** (66 skills, 11 plugins).
+This repository contains **2 marketplace(s)** with **78 extensions** (67 skills, 11 plugins).
 
 ### large-codebase
 
@@ -119,7 +119,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases
 
 Official skills and plugins for OpenHands — the open-source AI software engineer.
 
-**73 extensions** (64 skills, 9 plugins)
+**74 extensions** (65 skills, 9 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
@@ -154,10 +154,10 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | 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` |
+| gitlab-issue-to-mr | skill | Create an automation that implements GitLab issues when a configurable trigger label is applied. Polls the projects d... | `/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` |
 | iterate | skill | Iterate on a GitHub pull request — drive it through CI, code review, and QA until merge-ready. Monitors state, fixes ... | `/iterate`, `/verify`, `/babysit` |
-| jira-issue-to-pr | skill | Deploy a cron-based OpenHands automation that watches a Jira Cloud project for issues labeled with a configurable lab... | — |
+| jira-issue-to-pr | skill | Deploy a cron-based OpenHands automation that opens a GitHub pull request, a GitLab merge request or a Bitbucket pull... | — |
 | jupyter | skill | Read, modify, execute, and convert Jupyter notebooks programmatically. Use when working with .ipynb files for data sc... | — |
 | kubernetes | skill | Set up and manage local Kubernetes clusters using KIND (Kubernetes IN Docker). Use when testing Kubernetes applicatio... | — |
 | learn-from-code-review | skill | Distill code review feedback from GitHub PRs into reusable skills and guidelines. Use when users ask to learn from co... | `/learn-from-reviews` |
@@ -186,11 +186,12 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | 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` |
 | slack-standup-digest | skill | Create an automation that generates an async standup digest from Slack. Searches selected channels for messages since... | `/standup-digest:setup` |
+| software-factory | skill | Set up a GitHub software factory fast: ask only for the repositories and the ticket source (GitHub issues, Jira or Li... | `/software-factory` |
 | ssh | skill | Establish and manage SSH connections to remote machines, including key generation, configuration, and file transfers.... | — |
 | swift-linux | skill | Install and configure Swift programming language on Debian Linux for server-side development. Use when building Swift... | — |
 | technical-writing | skill | Write and revise technical explanations in flowing, direct, conversational prose that stays concise without becoming ... | — |
 | 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` |
+| ticket-to-code-change | skill | Set up 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. | — |

package/apps/vscode/README.md

@@ -1,13 +1,15 @@
 # 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.
+Install this App in Agent Canvas by opening **Apps → Add App** and entering:
 
-## Artifact delivery
+```text
+https://github.com/OpenHands/extensions/tree/main/apps/vscode
+```
 
-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 App provides a full-height OpenVSCode editor. Before the backend is ready, it shows backend status, an optional workspace-folder input, and revision-bound prepare/start/stop/refresh actions. Once ready, the page contains only the editor iframe.
 
-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.
+## Artifact delivery
 
-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 repository contains no OpenVSCode binaries. During the explicit **Prepare and start** step, Agent Server downloads only the current platform's pinned OpenVSCode Server `v1.109.5` archive from its public GitHub Release, verifies the manifest-pinned SHA-256 digest, safely extracts it into an App-owned content-addressed cache, and starts it with App-owned home, user-data, and extensions directories. It does not send Agent Server or repository credentials to the artifact host.
 
-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.
+The optional folder is persisted in browser storage and forwarded as the editor folder. It is a user convenience, not OS sandboxing.

package/apps/vscode/canvas-extension.json

@@ -9,10 +9,18 @@
   "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"}
+      "linux-amd64": {
+        "url": "https://github.com/gitpod-io/openvscode-server/releases/download/openvscode-server-v1.109.5/openvscode-server-v1.109.5-linux-x64.tar.gz",
+        "sha256": "b433bf4f0227321a7014d8460d10a8f958adc0f45aa79bd889e84e65e8f88363",
+        "strip_components": 1
+      },
+      "linux-arm64": {
+        "url": "https://github.com/gitpod-io/openvscode-server/releases/download/openvscode-server-v1.109.5/openvscode-server-v1.109.5-linux-arm64.tar.gz",
+        "sha256": "36d9c14036489b63de84ebace837fcacf7e60e669a0dc715802c5443684ea4dc",
+        "strip_components": 1
+      }
     },
-    "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}"],
+    "argv": ["{artifact_dir}/bin/openvscode-server", "--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"]
   }