openhands-extensions 0.20.0__tar.gz → 0.22.0__tar.gz

{openhands_extensions-0.20.0 → openhands_extensions-0.22.0}/.github/workflows/check-extensions.yml

@@ -58,6 +58,8 @@ jobs:
         run: python scripts/sync_extensions.py --check
 
   sync-sdk-skill:
+    permissions:
+      contents: read
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -69,4 +71,6 @@ jobs:
           python-version: "3.12"
 
       - name: Check SDK skill is up to date
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
         run: python scripts/sync_openhands_sdk_skill.py --check

{openhands_extensions-0.20.0 → openhands_extensions-0.22.0}/.github/workflows/npm-publish.yml

@@ -56,14 +56,19 @@ jobs:
           fi
           echo "✓ npm $NPM_VERSION meets trusted publishing requirements"
 
-      # No install/test/build steps: @openhands/extensions ships source directly
-      # (plain ESM + hand-written .d.ts + JSON catalogs) with only peerDependencies,
-      # and has no build script, test suite, or lockfile.
+      # npm omits symlinks. Materialize shared resources in a release-only copy;
+      # retain the canonical linked source layout in the checkout.
+      - name: Stage package with linked resources
+        run: |
+          mkdir -p "$RUNNER_TEMP/extensions-package"
+          cp -RL . "$RUNNER_TEMP/extensions-package/"
 
       - name: Verify package contents
+        working-directory: ${{ runner.temp }}/extensions-package
         run: npm pack --dry-run
 
       - name: Validate package version matches release tag
+        working-directory: ${{ runner.temp }}/extensions-package
         env:
           # Pass inputs.tag via env var to prevent script injection from
           # GitHub Actions expression interpolation inside run blocks.
@@ -86,4 +91,5 @@ jobs:
           echo "✓ Version $PACKAGE_VERSION matches release tag"
 
       - name: Publish to npm with provenance
+        working-directory: ${{ runner.temp }}/extensions-package
         run: npm publish --access public --provenance

openhands_extensions-0.22.0/.github/workflows/pr-artifacts.yml

@@ -0,0 +1,294 @@
+---
+name: PR Artifacts
+
+on:
+    workflow_dispatch: # Manual trigger for testing
+    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.
+    check-pr-artifacts:
+        if: >-
+            github.event_name == 'pull_request_target' &&
+            github.event.action != 'closed'
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            pull-requests: write
+        steps:
+            - name: Post or update PR comment
+              uses: actions/github-script@v9
+              with:
+                  script: |
+                      const marker = '<!-- pr-artifacts-notice -->';
+                      const pullRequest = context.payload.pull_request;
+                      const headRepository = pullRequest.head.repo;
+                      let exists = true;
+
+                      try {
+                        await github.rest.repos.getContent({
+                          owner: headRepository.owner.login,
+                          repo: headRepository.name,
+                          path: '.pr',
+                          ref: pullRequest.head.sha,
+                        });
+                      } catch (error) {
+                        if (error.status === 404) {
+                          exists = false;
+                        } else {
+                          throw error;
+                        }
+                      }
+
+                      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 (!exists) {
+                        if (existing) {
+                          await github.rest.issues.updateComment({
+                            owner: context.repo.owner,
+                            repo: context.repo.repo,
+                            comment_id: existing.id,
+                            body: `${marker}
+                            ✅ **PR Artifacts Cleaned Up**
+
+                            The \`.pr/\` directory is no longer present.
+                            `,
+                          });
+                        }
+                        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}
+                      `;
+
+                      core.warning('.pr/ directory contains temporary PR-only artifacts');
+                      if (existing) {
+                        await github.rest.issues.updateComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          comment_id: existing.id,
+                          body: body,
+                        });
+                      } else {
+                        await github.rest.issues.createComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          issue_number: context.issue.number,
+                          body: body,
+                        });
+                      }
+
+  # Fork branches cannot be modified reliably. If artifacts reach the trusted base,
+  # remove them through a pull request so branch protections remain enforced.
+    cleanup-after-merge:
+        concurrency:
+            group: cleanup-pr-artifacts-${{ github.event.pull_request.base.ref }}
+            cancel-in-progress: false
+        if: >-
+            github.event_name == 'pull_request_target' &&
+            github.event.action == 'closed' &&
+            github.event.pull_request.merged == true
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+            pull-requests: write
+        steps:
+            - uses: actions/checkout@v7
+              with:
+                  ref: ${{ github.event.pull_request.base.ref }}
+                  token: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC }}
+
+            - name: Create or update cleanup PR
+              id: cleanup
+              env:
+                  BASE_REF: ${{ github.event.pull_request.base.ref }}
+                  CLEANUP_BRANCH: automation/remove-pr-artifacts
+                  GH_TOKEN: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC }}
+              run: |
+                  if [ ! -d ".pr" ]; then
+                    echo "created=false" >> "$GITHUB_OUTPUT"
+                    echo "::notice::No .pr/ directory to remove from $BASE_REF"
+                    exit 0
+                  fi
+
+                  git config user.name "allhands-bot"
+                  git config user.email "allhands-bot@users.noreply.github.com"
+                  git fetch origin \
+                    "+refs/heads/$CLEANUP_BRANCH:refs/remotes/origin/$CLEANUP_BRANCH" || true
+                  git checkout -B "$CLEANUP_BRANCH"
+                  git rm -rf .pr/
+                  git commit \
+                    -m "chore: remove merged PR artifacts" \
+                    -m "Co-authored-by: openhands <openhands@all-hands.dev>"
+                  git push --force-with-lease origin "HEAD:$CLEANUP_BRANCH"
+
+                  cleanup_pr_url=$(gh pr list \
+                    --base "$BASE_REF" \
+                    --head "$CLEANUP_BRANCH" \
+                    --state open \
+                    --json url \
+                    --jq '.[0].url')
+
+                  if [ -z "$cleanup_pr_url" ]; then
+                    cleanup_pr_url=$(gh pr create \
+                      --base "$BASE_REF" \
+                      --head "$CLEANUP_BRANCH" \
+                      --title "chore: remove merged PR artifacts" \
+                      --body-file - <<EOF
+                  ## Why
+
+                  Temporary \`.pr/\` artifacts reached \`$BASE_REF\` through one or more merged PRs.
+
+                  ## Summary
+
+                  - Remove the temporary \`.pr/\` directory from \`$BASE_REF\`.
+
+                  ## How to Test
+
+                  - Confirm this PR only deletes files under \`.pr/\`.
+                  - Let the required checks validate the cleanup commit.
+
+                  ---
+
+                  _This PR was automatically created by the PR Artifacts workflow._
+                  EOF
+                    )
+                  fi
+
+                  echo "created=true" >> "$GITHUB_OUTPUT"
+                  echo "pr_url=$cleanup_pr_url" >> "$GITHUB_OUTPUT"
+                  echo "::notice::Cleanup PR ready: $cleanup_pr_url"
+
+            - name: Update source PR comment
+              if: steps.cleanup.outputs.created == 'true'
+              uses: actions/github-script@v9
+              env:
+                  CLEANUP_PR_URL: ${{ steps.cleanup.outputs.pr_url }}
+              with:
+                  script: |
+                      const marker = '<!-- pr-artifacts-notice -->';
+                      const body = `${marker}
+                      🧹 **PR Artifact Cleanup Queued**
+
+                      The \`.pr/\` directory reached \`${context.payload.pull_request.base.ref}\` after merge. A cleanup PR has been opened or updated: ${process.env.CLEANUP_PR_URL}
+                      `;
+
+                      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,
+                        });
+                      } else {
+                        await github.rest.issues.createComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          issue_number: context.issue.number,
+                          body: body,
+                        });
+                      }

{openhands_extensions-0.20.0 → openhands_extensions-0.22.0}/.github/workflows/pr-description-check.yml

@@ -17,13 +17,15 @@ jobs:
     validate-pr-description:
         name: Validate PR description
         # Draft PRs may still have incomplete descriptions; validate when review starts.
-        # Release PRs are generated by the trusted prepare-release workflow without
+        # Release and artifact-cleanup PRs are generated by trusted workflows without
         # the standard human-authored PR template.
         if: >-
             github.event.pull_request.draft == false &&
             github.event.pull_request.user.login != 'dependabot[bot]' &&
             !(github.event.pull_request.head.repo.full_name == github.repository &&
-            startsWith(github.event.pull_request.head.ref, 'release-please-'))
+            (startsWith(github.event.pull_request.head.ref, 'release-please-') ||
+            (github.event.pull_request.base.ref == 'main' &&
+            github.event.pull_request.head.ref == 'automation/remove-pr-artifacts')))
         runs-on: ubuntu-latest
         steps:
             - name: Checkout trusted workflow scripts

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

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

{openhands_extensions-0.20.0 → openhands_extensions-0.22.0}/AGENTS.md

@@ -10,12 +10,11 @@ This repository owns the public registry of reusable OpenHands skills, plugins,
 
 Related repositories have distinct responsibilities:
 
-- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and canonical API.
-- [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns the browser-compatible typed Agent Server client.
+- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, canonical API, and browser-compatible TypeScript Agent Server client under `clients/typescript/`.
 - [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) owns Agent Canvas UI and local-stack orchestration.
 - [`OpenHands/automation`](https://github.com/OpenHands/automation) owns scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration.
 
-Put reusable skills, plugins, automations, and integrations here; put backend execution behavior in the SDK, typed API access in `typescript-client`, 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.
+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.
 
 ## What this repo contains
 
@@ -118,6 +117,31 @@ When editing or adding skills in this repo, follow these rules (and add new skil
 - `plugins/release-notes` now has a standalone validator at `plugins/release-notes/scripts/validate_release_notes.py`; it rebuilds the deterministic tag-range context, fails if a change bullet omits explicit PR/commit refs or matching author handles, and enforces full PR/author coverage by appending a compact `### 🔎 Small Fixes/Internal Changes` appendix grouped by author when the agent omits lower-signal items. New contributor detection in `generate_release_notes.py` should use merged PR history for human authors (excluding bots) rather than commit-author lookup.
 
 
+## 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.
+
+```bash
+mkdir -p .pr
+
+.pr/
+├── design.md       # Design decisions and architecture notes
+├── analysis.md     # Investigation or debugging notes
+└── notes.md        # Any other PR-specific content
+```
+
+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`.
+
+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`.
+
 ## 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: [...]`.

{openhands_extensions-0.20.0 → openhands_extensions-0.22.0}/PKG-INFO

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

{openhands_extensions-0.20.0 → openhands_extensions-0.22.0}/README.md

@@ -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 **68 extensions** (58 skills, 10 plugins).
+This repository contains **2 marketplace(s)** with **72 extensions** (62 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.
 
-**64 extensions** (56 skills, 8 plugins)
+**68 extensions** (60 skills, 8 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
@@ -141,11 +141,14 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | github | skill | Interact with GitHub repositories, pull requests, issues, and workflows using the GITHUB_TOKEN environment variable a... | — |
 | github-actions | skill | Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating wo... | — |
 | github-agents-md-maintainer | skill | Create an automation that keeps AGENTS.md current in one or more GitHub repositories. On a schedule an agent reads th... | `/agents-md:setup` |
+| github-delivery-watchdog | skill | Periodically check pull requests and merge only current heads with independent review, tests, and passing CI. | `/github-delivery-watchdog` |
 | github-issue-to-pr | skill | Create an automation that implements GitHub issues when a configurable trigger label is applied. Clones the default b... | `/issue-to-pr:setup` |
+| github-issue-triage | skill | Prioritize open issues and establish acceptance criteria before marking them ready for development. | `/github-issue-triage` |
 | 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` |
 | 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` |
 | 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... | — |
@@ -162,6 +165,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | openhands | plugin | Unified OpenHands plugin — bundles Cloud CLI, REST API (openhands-api), and Automations (openhands-automation) into a... | `/openhands-cloud` |
 | openhands-api | skill | Use the OpenHands Cloud REST API (V1) and agent-server APIs to create and manage Cloud or local backend conversations... | — |
 | openhands-automation | skill | Create and manage OpenHands automations - scheduled tasks that run in sandboxes. Use the prompt preset to create auto... | `/automation:create` |
+| openhands-enterprise-troubleshooting | skill | Diagnose and resolve common issues on OpenHands Enterprise self-hosted installations. Covers sandbox startup failures... | — |
 | openhands-sdk | skill | Reference skill for the OpenHands Software Agent SDK - build AI agents with custom tools, LLM configuration, conversa... | `/sdk` |
 | pdflatex | skill | Install and use pdflatex to compile LaTeX documents into PDFs on Linux. Use when generating academic papers, research... | — |
 | plain-english-content | skill | Write and edit clear, accessible prose in a plain English content style: active voice, front-loaded content, sentence... | — |