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

openhands_extensions-0.24.0/.agents/skills/custom-codereview-guide.md

@@ -0,0 +1,101 @@
+---
+name: custom-codereview-guide
+description: Repository-specific review guidance for OpenHands/extensions.
+triggers:
+- /codereview
+---
+
+# OpenHands/extensions review guide
+
+Apply this guide with the general code-review skill and `AGENTS.md`. Approve the
+current head when it has no material correctness, security, compatibility, or
+acceptance-criterion defect. Comment only on concrete failures; do not withhold
+approval for optional refactors, tone, style, or speculative improvements.
+
+## Repository scope
+
+This repository owns reusable extensions: skills, plugins, and automation
+bundles that use existing public host and runtime interfaces. Out of scope here,
+because another repository owns the contract or machinery:
+
+- SDK, agent-server, and client contracts — `OpenHands/software-agent-sdk`;
+- generic automation scheduling, state, dispatch, and profile machinery —
+  `OpenHands/automation`;
+- Canvas product and UI integration — `OpenHands/OpenHands`.
+
+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
+
+### Executable instructions and runtime parity
+
+Commands, imports, environment variables, endpoints, and setup steps in extension
+content are executable contracts. Verify them against the released packages and
+the actual local and cloud environments that claim support. Do not approve an
+example that relies on an unreleased API, a developer-only dependency, a private
+path, or a variable that the production runtime does not provide.
+
+For a changed skill, plugin, hook, or automation, follow its documented entrypoint
+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.
+
+### Untrusted triggers and credentials
+
+Treat repository events, issue and PR comments, chat messages, catalog fields,
+and extension-provided arguments as untrusted. Verify who may trigger the action,
+whose identity it runs as, which repository or organization it can affect, and
+which secrets it receives. A trigger phrase alone is not authorization. Require
+an explicit allowlist, permission check, or repository policy before performing
+mutating or credentialed work.
+
+Use only the minimum documented credential set. Never place secret values in
+prompts, logs, generated files, examples, or persisted state.
+
+### Sources of truth and generated artifacts
+
+Identify the hand-authored source before reviewing a catalog or generated file.
+A change should update that source once and regenerate every derived artifact
+with the repository's existing sync/build command. Documentation must describe
+the real direction of generation; do not call a generated asset the source of
+truth or claim two runtimes read one asset when they do not.
+
+Check the marketplace entry and generated command/catalog coverage required by
+`AGENTS.md`. Do not add a parallel catalog, provider-specific copy, or manual
+compatibility layer when the repository already has a generator or schema.
+
+### Documentation claims
+
+Test copy-paste commands and verify named tools, flags, package exports, URLs, and
+installation mechanisms from authoritative sources. A plausible command is not
+evidence. Documentation that teaches the wrong data flow or setup is a material
+finding because agents execute it directly.
+
+SDK documentation belongs in `docs.openhands.dev/sdk`; the generated
+`skills/openhands-sdk/SKILL.md` remains a thin synchronized entrypoint. The
+former `@openhands/extensions/mcps` catalog was experimental and pre-release, so
+an explicitly coordinated replacement with the `integrations` catalog needs
+consumer migration documentation but not compatibility aliases or a deprecation
+window.
+
+### Dependencies and supply chain
+
+Apply the general seven-day release-recency guard to the exact dependency version,
+regardless of the package's age or popularity. Validate installation with the
+package manager and runtime used by the extension. Temporary git pins and
+unreleased package APIs are blockers for merge unless the PR is an explicit,
+coordinated stack that will replace them before release.
+
+## Evidence and comment discipline
+
+Evidence should exercise the extension as users invoke it: run the command, hook,
+plugin, or automation entrypoint and show the relevant result. Static text checks
+alone do not validate executable instructions. Require only the environments and
+paths the change affects.
+
+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.

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

@@ -11,10 +11,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version: "20"
 
@@ -44,10 +44,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
@@ -63,10 +63,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 

{openhands_extensions-0.22.1 → openhands_extensions-0.24.0}/.github/workflows/deprecation-check.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7

openhands_extensions-0.24.0/.github/workflows/issue-readiness-check.yml

@@ -0,0 +1,73 @@
+---
+name: Ready-for-dev Label Policy
+
+# The issue-triage automation and repository writers may grant ready-for-dev.
+# Labels from any other actor are removed.
+
+on:
+    issues:
+        types: [labeled, unlabeled]
+
+concurrency:
+    group: ready-for-dev-policy-${{ github.event.issue.number }}
+    cancel-in-progress: false
+
+jobs:
+    enforce-label-policy:
+        name: Enforce ready-for-dev label policy
+        if: >-
+            github.event.issue.state == 'open'
+            && github.event.issue.pull_request == null
+            && github.event.label.name == 'ready-for-dev'
+        runs-on: ubuntu-latest
+        timeout-minutes: 5
+        permissions:
+            issues: write
+        outputs:
+            refresh-linked-prs: ${{ steps.policy.outputs.refresh-linked-prs }}
+        steps:
+            - name: Check label actor
+              id: policy
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  ACTION: ${{ github.event.action }}
+                  ACTOR: ${{ github.event.sender.login }}
+                  REPOSITORY: ${{ github.repository }}
+                  ISSUE_NUMBER: ${{ github.event.issue.number }}
+              run: |
+                  set -euo pipefail
+
+                  if [ "$ACTION" = "unlabeled" ]; then
+                    echo "refresh-linked-prs=true" >> "$GITHUB_OUTPUT"
+                    exit 0
+                  fi
+
+                  permission="$(gh api "repos/$REPOSITORY/collaborators/$ACTOR/permission" --jq .permission 2>/dev/null || true)"
+                  case "$permission" in
+                    write|maintain|admin)
+                      echo "refresh-linked-prs=true" >> "$GITHUB_OUTPUT"
+                      ;;
+                    *)
+                      gh issue edit "$ISSUE_NUMBER" --repo "$REPOSITORY" --remove-label ready-for-dev
+                      echo "refresh-linked-prs=false" >> "$GITHUB_OUTPUT"
+                      ;;
+                  esac
+
+    refresh-linked-pr-gates:
+        name: Refresh PR gates for linked issues
+        needs: enforce-label-policy
+        if: needs.enforce-label-policy.outputs.refresh-linked-prs == 'true'
+        runs-on: ubuntu-latest
+        timeout-minutes: 10
+        permissions:
+            contents: read
+            pull-requests: read
+            actions: write
+        steps:
+            - name: Checkout trusted workflow scripts
+              uses: actions/checkout@v7
+
+            - name: Re-run PR description checks for linked open PRs
+              env:
+                  GH_TOKEN: ${{ github.token }}
+              run: python .github/scripts/refresh_linked_pr_checks.py

{openhands_extensions-0.22.1 → openhands_extensions-0.24.0}/.github/workflows/npm-publish.yml

@@ -31,14 +31,14 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           ref: ${{ inputs.tag || github.ref }}
 
       # Trusted publishing requires Node 22.14.0+ and npm 11.5.1+
       # See: https://docs.npmjs.com/trusted-publishers/
       - name: Set up Node.js for npm trusted publishing
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7
         with:
           node-version: '24'
           registry-url: https://registry.npmjs.org

{openhands_extensions-0.22.1 → openhands_extensions-0.24.0}/.github/workflows/pr-description-check.yml

@@ -29,7 +29,7 @@ jobs:
         runs-on: ubuntu-latest
         steps:
             - name: Checkout trusted workflow scripts
-              uses: actions/checkout@v4
+              uses: actions/checkout@v7
               with:
                   ref: ${{ github.event.pull_request.base.sha }}
 

{openhands_extensions-0.22.1 → openhands_extensions-0.24.0}/.github/workflows/pypi-publish.yml

@@ -20,7 +20,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Extract version
         id: extract_version
@@ -72,7 +72,7 @@ jobs:
         run: uv build
 
       - name: Upload distributions
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: python-package-distributions
           path: dist/
@@ -95,7 +95,7 @@ jobs:
 
     steps:
       - name: Download distributions
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v8
         with:
           name: python-package-distributions
           path: dist/

{openhands_extensions-0.22.1 → openhands_extensions-0.24.0}/.github/workflows/tests.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -21,7 +21,7 @@ jobs:
           python-version: "3.12"
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version: "20"
 

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

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

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

@@ -16,6 +16,27 @@ Related repositories have distinct responsibilities:
 
 Put reusable skills, plugins, automations, and integrations here; put backend execution behavior and typed API access in the SDK, application UI in Agent Canvas, and scheduling/dispatch lifecycle code in `automation`. If a PR is opened in the wrong repository, explicitly recommend closing and moving it to the owning repository. PRs must follow this repository's applicable contribution and code-review guidance.
 
+## Review-Facing Extension Checklist
+
+Before opening a PR:
+
+- Keep a content change focused on one skill, plugin, automation bundle, or
+  integration. Put shared product runtime behavior in the repository that owns
+  it instead of copying machinery into extension content.
+- Treat every command, import, environment variable, endpoint, setup step, and
+  package name as an executable contract. Test the documented entrypoint with
+  released packages in each local or cloud environment the extension claims to
+  support; do not rely on developer-only variables or private paths.
+- For event-, comment-, or message-triggered work, define who may trigger it,
+  whose identity executes it, what scope it may mutate, and which minimal secrets
+  it receives. A trigger phrase is not authorization.
+- Edit the hand-authored source once and regenerate derived catalogs, commands,
+  indexes, and package assets with the existing sync/build command. Document the
+  true generation direction and do not introduce a parallel source of truth.
+- Verify copy-paste commands and factual documentation claims against the actual
+  tool or authoritative source. Extension instructions are executed by agents,
+  so incorrect setup or data-flow documentation is a functional defect.
+
 ## What this repo contains
 
 - `skills/` — a catalog of skills, **one directory per skill**.
@@ -110,7 +131,7 @@ When editing or adding skills in this repo, follow these rules (and add new skil
 - Agent-driven plugins (for example `plugins/pr-review` and `plugins/release-notes`) use `uv run --with openhands-sdk --with openhands-tools ...` and require an `LLM_API_KEY` in addition to `GITHUB_TOKEN`.
 - For OpenHands Cloud API guidance, automations, and CLI integration, use `plugins/openhands`. It is the canonical unified OpenHands plugin covering the V1 Cloud API, Automations API, and CLI. The individual skills (`skills/openhands-api`, `skills/openhands-automation`) are also available standalone.
 - When reviewing or editing `skills/openhands-sdk`, validate copy-paste imports against the released packages with `uv run --with openhands-tools --with openhands-workspace --with openhands-agent-server python ...`. In the current released workspace package, the exported remote workspace classes are `APIRemoteWorkspace` / `OpenHandsCloudWorkspace`; `RemoteAPIWorkspace` is not available.
-- For agent-driven plugin scripts, prefer `from openhands.sdk.plugin import PluginSource` and pass `plugins=[PluginSource(source=...)]` into `Conversation`. In the current released SDK (`openhands-sdk` 1.18.x), `Plugin` is not exported from `openhands.sdk.plugin`, so direct `Plugin.load(...)` imports can break CI.
+- For agent-driven plugin scripts, prefer `from openhands.sdk.plugin import PluginSource` and pass `plugins=[PluginSource(source=...)]` into `Conversation`. The current released SDK (`openhands-sdk` 1.49.x) exports both `PluginSource` and `Plugin` from `openhands.sdk.plugin`, so `Plugin.load(...)` imports also work (used by `tests/test_skill_plugin_loading.py`).
 - `plugins/qa-changes/action.yml` now has a preflight guard for fork PRs in `pull_request` context: if the PR comes from a fork and `LLM_API_KEY` is unavailable (normal for forks), the action exits successfully with a clear skip notice instead of failing.
 - `skills/bitbucket` should not tell agents to rewrite remotes proactively. In OpenHands, `BITBUCKET_TOKEN` is commonly kept in unencoded `user:token` form for API calls like `curl --user "$BITBUCKET_TOKEN" ...`; only split and URL-encode it when constructing a non-interactive HTTPS Git remote URL.
 
@@ -148,7 +169,16 @@ Important notes:
 - `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.
 
-- The `ready-for-dev` gates live in `.github/workflows/issue-readiness-check.yml` and `.github/workflows/pr-description-check.yml`, backed by `.github/scripts/check_issue_readiness.py`, `check_pr_description.py`, `refresh_linked_pr_checks.py`, and `post-readiness-comment.mjs`. Issues labeled `bug` or `enhancement` must meet type-specific readiness criteria (reproducible command plus Acceptance Criteria checklist for bugs; Desired Behavior plus Acceptance Criteria checklist for enhancements) to receive the `ready-for-dev` label. Non-draft PRs must keep the `## Why`, `## Summary`, and `## How to Test` template sections filled, and any issue linked via a closing keyword or the `## Issue Number` section must carry `ready-for-dev` unless it predates the 2026-08-25 rollout. Label transitions on an issue re-run the PR Description Check for linked open PRs. Tests live in `tests/test_check_issue_readiness.py`, `tests/test_check_pr_description.py`, and `tests/test_refresh_linked_pr_checks.py`.
+- The GitHub issue-triage automation and repository writers may grant
+  `ready-for-dev`.
+  `.github/workflows/issue-readiness-check.yml` removes a newly applied label
+  unless a user with `write`, `maintain`, or `admin` permission applied it. An
+  `unlabeled` event then lets triage reassess the issue.
+  `.github/workflows/pr-description-check.yml` still requires linked issues to
+  be ready, and label transitions refresh that check through
+  `.github/scripts/refresh_linked_pr_checks.py`. Tests for the PR gates live in
+  `tests/test_check_pr_description.py` and
+  `tests/test_refresh_linked_pr_checks.py`.
 
 ## OpenHands SDK documentation policy
 

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: openhands-extensions
-Version: 0.22.1
+Version: 0.24.0
 Summary: OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)
 License-File: LICENSE
 Requires-Python: >=3.12
 Requires-Dist: deprecation<3,>=2.1
-Requires-Dist: packaging<26,>=24
+Requires-Dist: packaging<27,>=24
 Requires-Dist: pydantic<3,>=2.10

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

@@ -9,7 +9,7 @@ It contains reusable, shareable skills and plugins that customize agent behavior
 
 ## Repository boundaries
 
-`OpenHands/extensions` is the public registry for reusable skills, plugins, automations, and integrations. [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns Agent Server execution and the canonical API, [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns typed browser access to that API, [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) owns Agent Canvas UI, and [`OpenHands/automation`](https://github.com/OpenHands/automation) owns scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration.
+`OpenHands/extensions` is the public registry for reusable skills, plugins, automations, and integrations. [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns Agent Server execution, the canonical API, and typed browser access to it under `clients/typescript/`, [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) owns Agent Canvas UI, and [`OpenHands/automation`](https://github.com/OpenHands/automation) owns scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration.
 
 Put reusable extension artifacts here rather than in application repositories. If a PR is opened in the wrong repository, close and move it to the repository that owns the change.
 
@@ -96,7 +96,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 **72 extensions** (62 skills, 10 plugins).
+This repository contains **2 marketplace(s)** with **73 extensions** (63 skills, 10 plugins).
 
 ### large-codebase
 
@@ -115,7 +115,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases
 
 Official skills and plugins for OpenHands — the open-source AI software engineer.
 
-**68 extensions** (60 skills, 8 plugins)
+**69 extensions** (61 skills, 8 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
@@ -128,6 +128,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | bitbucket | skill | Bitbucket integration hub. Detects whether the repository is on Bitbucket Cloud or Bitbucket Data Center and directs ... | — |
 | bitbucket-cloud | skill | Bitbucket Cloud (bitbucket.org) specifics — authenticate with BITBUCKET_TOKEN, use the REST API v2, workspace/repo_sl... | — |
 | bitbucket-data-center | skill | Bitbucket Data Center (self-hosted Bitbucket Server) specifics — authenticate with BITBUCKET_DATA_CENTER_TOKEN, use t... | — |
+| canvas-extension-api | skill | Build and validate Apps for Agent Canvas using the supported Canvas Extensions API v1 routed-page contract. | — |
 | city-weather | plugin | Get current weather, time, and precipitation forecast for any city using the free Open-Meteo API. Provides slash comm... | — |
 | code-review | skill | Rigorous code review focusing on data structures, simplicity, security, pragmatism, and risk/safety evaluation. Provi... | `/codereview`, `/codereview-roasted` |
 | code-simplifier | skill | Simplifies and refines code across three dimensions - code reuse, code quality, and efficiency - while preserving all... | `/simplify` |