openhands-extensions 0.6.0__tar.gz

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

@@ -0,0 +1,25 @@
+---
+name: custom-codereview-guide
+description: Repository-specific code review guidelines for OpenHands/extensions
+triggers:
+- /codereview
+---
+
+# Extensions Repo — Code Review Guidelines
+
+## SDK Documentation Placement
+
+If a PR adds or modifies OpenHands SDK-specific documentation (API guides, SDK usage examples, SDK feature descriptions), flag it:
+
+- The canonical source of truth for SDK documentation is <https://docs.openhands.dev/sdk> and its `llms.txt` index.
+- The `skills/openhands-sdk/SKILL.md` in this repo is a thin pointer to the docs site. It should NOT contain duplicated SDK content.
+- **Push back**: ask the submitter to contribute SDK documentation changes to [OpenHands/docs](https://github.com/OpenHands/docs) instead.
+
+## Pre-release Integration Catalog Changes
+
+The `@openhands/extensions/mcps` catalog was experimental and pre-release. If a
+PR intentionally replaces it with the broader `integrations` catalog and updates
+known downstream consumers in the same coordinated stack, do not require
+backward-compatible `mcps` aliases or a deprecation window. Require migration
+documentation for consumers, but accept a clean breaking change for this
+pre-release surface.

openhands_extensions-0.6.0/.claude-plugin/marketplace.json

@@ -0,0 +1 @@
+../marketplaces/openhands-extensions.json

openhands_extensions-0.6.0/.github/pull_request_template.md

@@ -0,0 +1,38 @@
+<!-- Keep this PR as draft until it is ready for review. -->
+
+<!-- AI/LLM agents: be concise and specific. Do not check the box below. -->
+
+- [ ] A human has tested these changes.
+
+---
+
+## Why
+
+<!-- Describe problem, motivation, etc.-->
+
+## Summary
+
+<!-- 1-3 bullets describing what changed. -->
+-
+
+## Issue Number
+<!-- Required if there is a relevant issue to this PR. -->
+
+## How to Test
+
+<!--
+Required. Share the steps for the reviewer to be able to test your PR. e.g. You can test by running `npm install` then `npm build dev`.
+
+If you could not test this, say why.
+-->
+
+## Video/Screenshots
+
+<!--
+Provide a video or screenshots of testing your PR. e.g. you added a new feature to the gui, show us the video of you testing it successfully.
+
+-->
+
+## Notes
+
+<!-- Optional: migrations, config changes, rollout concerns, follow-ups, or anything reviewers should know. -->

openhands_extensions-0.6.0/.github/release.yml

@@ -0,0 +1,14 @@
+changelog:
+  categories:
+    - title: Features
+      labels: ["type: feat"]
+    - title: Bug Fixes
+      labels: ["type: fix"]
+    - title: Performance
+      labels: ["type: perf"]
+    - title: Documentation
+      labels: ["type: docs"]
+    - title: Maintenance
+      labels: ["type: chore", "type: build", "type: ci", "type: refactor", "type: style", "type: test", "type: revert"]
+    - title: Other Changes
+      labels: ["*"]

openhands_extensions-0.6.0/.github/workflows/check-extensions.yml

@@ -0,0 +1,72 @@
+name: Check Extensions
+
+on:
+  pull_request:
+    branches: ["*"]
+  push:
+    branches: ["main", "master"]
+
+jobs:
+  validate-claude-code:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Validate all plugins with Claude Code
+        run: |
+          failed=0
+          for plugin_dir in plugins/*/; do
+            if [ -d "${plugin_dir}.plugin" ]; then
+              echo "Validating ${plugin_dir}..."
+              if ! claude plugin validate "${plugin_dir}"; then
+                echo "❌ Validation failed for ${plugin_dir}"
+                failed=1
+              else
+                echo "✅ ${plugin_dir} is valid"
+              fi
+            fi
+          done
+          if [ "$failed" -ne 0 ]; then
+            echo "::error::One or more plugins failed Claude Code validation"
+            exit 1
+          fi
+
+  sync-extensions:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Check extensions are in sync
+        run: python scripts/sync_extensions.py --check
+
+  sync-sdk-skill:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Check SDK skill is up to date
+        run: python scripts/sync_openhands_sdk_skill.py --check

openhands_extensions-0.6.0/.github/workflows/npm-publish.yml

@@ -0,0 +1,89 @@
+name: Publish to npm
+
+# Publishes @openhands/extensions to npm via OIDC trusted publishing (no token).
+# Fires when release-please pushes a version tag (v*) cut from main; the manual
+# dispatch path re-publishes a specific tag. Trusted publishing must be
+# configured for this package on npmjs.com (this repo + this workflow file).
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to publish (e.g. v0.1.0)'
+        required: true
+        type: string
+
+concurrency:
+  group: npm-publish-${{ inputs.tag || github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        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
+        with:
+          node-version: '24'
+          registry-url: https://registry.npmjs.org
+
+      - name: Verify npm version supports trusted publishing
+        run: |
+          echo "Node version: $(node --version)"
+          echo "npm version: $(npm --version)"
+          NPM_VERSION=$(npm --version)
+          NPM_MAJOR=$(echo $NPM_VERSION | cut -d. -f1)
+          NPM_MINOR=$(echo $NPM_VERSION | cut -d. -f2)
+          if [ "$NPM_MAJOR" -lt 11 ] || ([ "$NPM_MAJOR" -eq 11 ] && [ "$NPM_MINOR" -lt 5 ]); then
+            echo "Error: npm 11.5.1+ required for trusted publishing, got $NPM_VERSION"
+            exit 1
+          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.
+
+      - name: Verify package contents
+        run: npm pack --dry-run
+
+      - name: Validate package version matches release tag
+        env:
+          # Pass inputs.tag via env var to prevent script injection from
+          # GitHub Actions expression interpolation inside run blocks.
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          # Resolve tag: prefer workflow_dispatch input, fall back to push-event GITHUB_REF
+          if [ -n "$INPUT_TAG" ]; then
+            RAW_TAG="$INPUT_TAG"
+          else
+            RAW_TAG="${GITHUB_REF#refs/tags/}"
+          fi
+          TAG_VERSION="${RAW_TAG#v}"
+          echo "Package version: $PACKAGE_VERSION"
+          echo "Release tag version: $TAG_VERSION"
+          if [ "$PACKAGE_VERSION" != "$TAG_VERSION" ]; then
+            echo "Error: package.json version ($PACKAGE_VERSION) doesn't match release tag ($TAG_VERSION)"
+            exit 1
+          fi
+          echo "✓ Version $PACKAGE_VERSION matches release tag"
+
+      - name: Publish to npm with provenance
+        run: npm publish --access public --provenance

openhands_extensions-0.6.0/.github/workflows/pr.yml

@@ -0,0 +1,30 @@
+name: pr
+
+# Caller workflow for the shared PR-title lint/label in OpenHands/release-actions.
+#
+# Trigger is pull_request_target (NOT pull_request) so the lint/label also runs
+# on PRs from forks — e.g. external contributors who aren't org members. On a
+# fork-originated `pull_request`, GITHUB_TOKEN is read-only, so the label step
+# (which needs pull-requests: write) would fail; pull_request_target runs in the
+# base repo's context with a writable token.
+#
+# pull_request_target is safe here — and only stays safe — because of two
+# invariants enforced by the reusable workflow:
+#   1. It NEVER checks out or executes any code from the PR. It only reads the
+#      PR title from the event payload, so fork code never runs with the base
+#      repo's token/secrets. Do not add a checkout step.
+#   2. This caller does NOT pass `secrets: inherit`, so the release App's
+#      credentials are not in scope for the title workflow — it runs on the
+#      default GITHUB_TOKEN alone. Do not add `secrets: inherit`.
+on:
+  pull_request_target:
+    # synchronize is needed alongside the title events: required status checks
+    # attach to a head SHA, and release-please force-pushes new commits to its
+    # release PR, so the lint must re-run on each update to stay green.
+    types: [opened, edited, reopened, synchronize]
+
+jobs:
+  pr-title:
+    permissions:
+      pull-requests: write
+    uses: OpenHands/release-actions/.github/workflows/pr-title.yml@main

openhands_extensions-0.6.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,104 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+concurrency:
+  group: pypi-publish-${{ github.event.release.tag_name || github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build Python distributions
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Extract version
+        id: extract_version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            VERSION="${RELEASE_TAG#v}"
+          else
+            VERSION=$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          print(tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"])
+          PY
+          )
+          fi
+
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "📦 Version: $VERSION"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: latest
+          python-version: '3.12'
+
+      - name: Validate package version matches release tag
+        if: github.event_name == 'release'
+        env:
+          VERSION: ${{ steps.extract_version.outputs.version }}
+        run: |
+          PACKAGE_VERSION=$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          print(tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"])
+          PY
+          )
+
+          echo "Package version: $PACKAGE_VERSION"
+          echo "Release tag version: $VERSION"
+          if [ "$PACKAGE_VERSION" != "$VERSION" ]; then
+            echo "Error: pyproject.toml version ($PACKAGE_VERSION) doesn't match release tag ($VERSION)"
+            exit 1
+          fi
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish openhands-extensions to PyPI
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      !github.event.release.prerelease
+    needs: build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/openhands-extensions
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

openhands_extensions-0.6.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: release
+
+# Caller workflow for the shared release automation in OpenHands/release-actions.
+# This file owns the trigger; the reusable workflow owns the logic.
+on:
+  push:
+    branches:
+      - main
+      # Maintenance/freeze branches (e.g. release/0.2). The reusable workflow
+      # scopes the release to whichever branch triggered this run.
+      - 'release/**'
+
+jobs:
+  release-please:
+    # The caller must grant the permissions the reusable workflow needs; the
+    # effective token is the intersection of the two.
+    permissions:
+      contents: write
+      pull-requests: write
+    # Passes the org-level RELEASE_APP_ID / RELEASE_APP_PRIVATE_KEY through so the
+    # reusable workflow can mint the GitHub App token. These are org secrets —
+    # nothing to create per-repo.
+    secrets: inherit
+    uses: OpenHands/release-actions/.github/workflows/release-please.yml@main

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

@@ -0,0 +1,31 @@
+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@v4
+
+      - 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@v4
+        with:
+          node-version: "20"
+
+      - name: Run tests
+        run: uv run --group test pytest tests/
+        env:
+          PYTHONPATH: ${{ github.workspace }}

openhands_extensions-0.6.0/.github/workflows/vulnerability-scan.yml

@@ -0,0 +1,87 @@
+# Vulnerability Scan and Remediation Workflow
+#
+# This is a thin wrapper that uses the OpenHands vulnerability-remediation action.
+# It auto-updates when the action in OpenHands/extensions is updated.
+#
+# INSTALLATION:
+#   curl -o .github/workflows/vulnerability-scan.yml \
+#     https://raw.githubusercontent.com/OpenHands/extensions/main/plugins/vulnerability-remediation/workflows/vulnerability-scan.yml
+#
+# REQUIRED SECRETS:
+#   - LLM_API_KEY: API key for your LLM provider (OpenAI, Anthropic, etc.)
+#
+# OPTIONAL SECRETS:
+#   - PAT_TOKEN: GitHub PAT for creating PRs (uses GITHUB_TOKEN if not set)
+#
+# The action will:
+#   1. Run a Trivy security scan
+#   2. Skip agent if no vulnerabilities found (saves costs)
+#   3. Create PRs for fixable vulnerabilities
+
+name: Vulnerability Scan and Remediation
+
+on:
+    # Run weekly on Monday at 9am UTC
+    schedule:
+        - cron: '0 9 * * 1'
+
+    # Allow manual trigger
+    workflow_dispatch:
+        inputs:
+            severity_threshold:
+                description: 'Minimum severity to remediate'
+                required: false
+                default: 'HIGH'
+                type: choice
+                options:
+                    - CRITICAL
+                    - HIGH
+                    - MEDIUM
+                    - LOW
+            max_vulnerabilities:
+                description: 'Maximum vulnerabilities to fix (0 = unlimited)'
+                required: false
+                default: '5'
+                type: string
+            llm_model:
+                description: 'LLM model to use for remediation'
+                required: false
+                default: 'anthropic/claude-sonnet-4-5-20250929'
+                type: string
+            llm_base_url:
+                description: 'Custom LLM base URL (optional)'
+                required: false
+                default: ''
+                type: string
+
+permissions:
+    contents: write
+    pull-requests: write
+    security-events: read
+
+jobs:
+    scan-and-remediate:
+        runs-on: ubuntu-latest
+        timeout-minutes: 60
+
+        steps:
+            # Uses @main to auto-update when the action is improved
+            - name: Run Vulnerability Remediation
+              id: remediate
+              uses: OpenHands/extensions/plugins/vulnerability-remediation@main
+              with:
+                  severity-threshold: ${{ inputs.severity_threshold || 'HIGH' }}
+                  max-vulnerabilities: ${{ inputs.max_vulnerabilities || '5' }}
+                  llm-model: ${{ inputs.llm_model || 'anthropic/claude-sonnet-4-5-20250929' }}
+                  llm-base-url: ${{ inputs.llm_base_url || '' }}
+                  llm-api-key: ${{ secrets.LLM_API_KEY }}
+                  github-token: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC || secrets.GITHUB_TOKEN }}
+
+            - name: Summary
+              run: |
+                  echo "### Vulnerability Scan Results" >> $GITHUB_STEP_SUMMARY
+                  if [ "${{ steps.remediate.outputs.scan-only }}" == "true" ]; then
+                    echo "✅ No vulnerabilities found that need remediation." >> $GITHUB_STEP_SUMMARY
+                  else
+                    echo "🔍 Found ${{ steps.remediate.outputs.vulnerabilities-found }} vulnerabilities to remediate." >> $GITHUB_STEP_SUMMARY
+                  fi

openhands_extensions-0.6.0/.gitignore

@@ -0,0 +1,32 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# pytest cache
+.pytest_cache/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+.agents/*
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/custom-codereview-guide.md
+
+# uv lock file (no application code in this repo)
+uv.lock
+
+# npm pack artifacts (also keeps stray tarballs out of the published package)
+*.tgz

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

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