@openhands/extensions 0.4.0 → 0.4.2

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.0"
+  ".": "0.4.2"
 }

package/automations/catalog/github-pr-reviewer.json

@@ -2,12 +2,12 @@
   "id": "github-pr-reviewer",
   "name": "GitHub Code Review Agent",
   "category": "Code review",
-  "description": "Watch pull requests, inspect the diff, and leave a concise review with risks and suggested follow-ups.",
+  "description": "Watch for a configurable label on GitHub pull requests, inspect full PR and repository context, and post an AI review comment once per label event.",
   "requiredIntegrationIds": [
     "github"
   ],
   "popularityRank": 100,
   "estimatedSetupMinutes": 4,
   "prompt": "/pr-reviewer:setup",
-  "exampleImplementation": "Trigger: github.pull_request.opened and github.pull_request.synchronize\nRequired MCP: GitHub\n\n1. Read repository, pull_request, and sender from the event payload.\n2. Fetch the PR diff and related comments through the GitHub MCP.\n3. Run a review rubric focused on bugs, security, tests, and maintainability.\n4. TODO: decide whether to publish inline comments, a summary comment, or a draft artifact.\n5. Post or save the review with links back to the exact files and lines."
+  "exampleImplementation": "Trigger: cron polling for open GitHub PRs with a configured label such as openhands-review\nRequired secret: GITHUB_PERSONAL_ACCESS_TOKEN\n\n1. Read repository, trigger label, review tone, and polling schedule from setup.\n2. List open PRs and find the latest matching GitHub labeled issue event for each labeled PR.\n3. Deduplicate on the label event ID so every label application queues exactly one review.\n4. Start an OpenHands conversation that clones the repo, checks out the exact PR head SHA, and inspects PR discussion, review comments, changed files, diff, and surrounding code.\n5. Post an acknowledgement with the conversation link, then post the final AI review comment only if the PR is still open and the head SHA has not changed."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",

package/plugins/qa-changes/action.yml

@@ -160,7 +160,7 @@ runs:
         # so we enforce the time limit via the coreutils timeout command.
         TIMEOUT_SECONDS=$((TIMEOUT_MINUTES * 60))
         timeout "${TIMEOUT_SECONDS}" \
-          uv run --no-project --with openhands-sdk --with openhands-tools --with lmnr \
+          uv run --no-project --with openhands-sdk --with openhands-tools --with 'lmnr<0.7.53' \
             python ../extensions/plugins/qa-changes/scripts/agent_script.py
 
     - name: Upload logs as artifact

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "extensions"
-version = "0.4.0"
+version = "0.4.2"
 description = "OpenHands extensions, plugins, and skills"
 requires-python = ">=3.12"
 

package/skills/github-pr-reviewer/.plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "github-pr-reviewer",
   "version": "1.0.0",
-  "description": "Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed files, tests, and existing discussion via GitHub MCP, then posts a concise review highlighting risks, security issues, missing tests, and next steps.",
+  "description": "Create an automation that reviews GitHub pull requests when a configurable trigger label is applied. It starts one OpenHands review conversation per label event, inspects full PR and repository context, and posts the final review comment back to GitHub.",
   "author": {
     "name": "OpenHands",
     "email": "contact@all-hands.dev"

package/skills/github-pr-reviewer/README.md

@@ -1,34 +1,40 @@
 # GitHub PR Reviewer
 
-Create an automation that reviews GitHub pull requests on open or update.
+Create an automation that reviews GitHub pull requests when a configurable
+trigger label is applied.
 
-## Triggers
+## Trigger
 
-This skill is activated by keywords:
+This skill is activated by:
 
-- `review pull requests`
-- `PR review automation`
-- `auto-review PRs`
+- `/pr-reviewer:setup`
 
 ## Features
 
-- **Inspects PR diff, changed files, and test coverage**
-- **Posts review with correctness risks, security issues, missing tests**
-- **Supports event-based (webhook) or cron-based (polling) triggers**
-- **Configurable review tone (thorough, concise, friendly)**
-- **Auto-post or draft mode for human approval**
+- Reviews PRs on demand by watching for a GitHub label event
+- Processes each label application exactly once, with persistent state
+- Re-review support by removing and re-applying the label
+- Suppresses stale reviews when the PR head commit changes mid-review
+- Uses a real cloned checkout and full PR context instead of only a truncated diff
+- Posts acknowledgement and final review comments with AI disclosure
+- Configurable review tone and polling schedule
 
 ## Prerequisites
 
-GitHub MCP installed in Settings → MCP
+Set `GITHUB_PERSONAL_ACCESS_TOKEN` in OpenHands Settings -> Secrets. The token
+must be able to read the repository, read pull requests, read issue events, and
+write issue comments.
 
 ## Quick Start
 
 Ask OpenHands:
 
-> "Set up a PR review automation for my myorg/backend repo that posts
-> concise reviews when PRs are opened"
+> "Set up a PR review automation for my `myorg/backend` repo using the
+> `openhands-review` label and concise reviews."
+
+After setup, apply the configured label to a pull request to queue a review. To
+request another review later, remove and re-apply the label.
 
 ## See Also
 
-- [SKILL.md](SKILL.md) — Full setup workflow reference
+- [SKILL.md](SKILL.md) - Full setup workflow reference

package/skills/github-pr-reviewer/SKILL.md

@@ -1,89 +1,251 @@
 ---
 name: github-pr-reviewer
 description: >
-  Create an automation that reviews GitHub pull requests when they are opened
-  or updated. Inspects the diff, changed files, tests, and existing discussion
-  via GitHub MCP, then posts a concise review highlighting risks, security
-  issues, missing tests, and next steps.
+  Create an automation that reviews GitHub pull requests when a configurable
+  trigger label is applied. Polls GitHub deterministically, starts one
+  OpenHands review conversation per label event, inspects full repository and
+  PR context, and posts the final review comment back to GitHub.
 triggers:
   - /pr-reviewer:setup
 ---
 
 # GitHub PR Reviewer Automation
 
-Set up a cron or event-triggered automation that reviews GitHub pull requests.
+Create a cron automation that watches a GitHub repository for pull requests
+with a review trigger label, starts an OpenHands review conversation once per
+label event, and posts the AI review as a GitHub comment.
+
+The automation script is deterministic: PR discovery, label-event tracking,
+state persistence, stale-result suppression, and GitHub comment posting are
+handled in Python. The LLM is invoked only for the review itself.
 
 ---
 
 ## Prerequisites
 
-### Required integration
+### Required secret
 
-- **GitHub MCP** must be installed in Settings → MCP.
+Verify that the following secret is set in **OpenHands Settings -> Secrets**:
 
-### Information to collect
+| Secret name | Token type | Minimum permissions |
+|---|---|---|
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` for private repos or `public_repo` for public repos |
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Contents: Read, Metadata: Read, Pull requests: Read, Issues: Read and Write |
 
-Ask the user for:
+Check with:
+```bash
+curl -s https://api.github.com/user \
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))"
+```
 
-1. **Repositories** — which repos should be watched (e.g. `myorg/backend`, `myorg/frontend`)
-2. **Trigger type** — event-based (reacts to `pull_request.opened` / `pull_request.synchronize`) or cron-based polling
-3. **Review tone** — thorough, concise, or friendly
-4. **Auto-post or draft** — should reviews be posted as GitHub comments automatically, or saved as draft artifacts for human approval first?
-5. **Filters** — any label, branch, or author filters (e.g. skip drafts, only review PRs with `needs-review` label)
+If the token is missing or invalid, inform the user and stop.
 
 ---
 
 ## Setup Workflow
 
-### Step 1 — Verify GitHub MCP access
+Follow these steps in order.
+
+### Step 1 - Verify `GITHUB_PERSONAL_ACCESS_TOKEN`
+
+Run the `curl` check above.
+
+- If absent: *"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in
+  OpenHands Settings -> Secrets."* Stop.
+- If the API returns `{"message": "Bad credentials"}`: tell the user the
+  token is invalid and ask them to update it. Stop.
 
-Confirm the GitHub MCP integration is working:
+### Step 2 - Collect repository
+
+Ask: *"Which GitHub repository should be monitored?
+(Format: `owner/repo`, e.g. `myorg/backend`)"*
+
+Validate access:
+```bash
+curl -s "https://api.github.com/repos/{owner}/{repo}" \
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
+  | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+if 'message' in d:
+    print('ERROR:', d['message'])
+else:
+    print(f\"Accessible. Private: {d.get('private')}. Permissions: {d.get('permissions')}\")
+"
 ```
-Use the GitHub MCP to list recent pull requests in one of the target repositories.
+
+Record `REPO = "{owner}/{repo}"`.
+
+### Step 3 - Collect trigger label
+
+Ask: *"Which PR label should trigger a review?
+(Press Enter for the default: `openhands-review`.)"*
+
+Record the answer as `TRIGGER_LABEL`. If the label does not exist yet, tell the
+user that GitHub will still record the event once the label is created and
+applied to a PR.
+
+The automation reviews a PR when it sees the latest matching `labeled` event for
+that label. To request another review later, remove and re-apply the label.
+
+### Step 4 - Collect review tone
+
+Ask: *"What review tone should the reviewer use?
+  1. Thorough (default) - comprehensive coverage of correctness, security, tests, style
+  2. Concise - high-signal only, skips minor style feedback
+  3. Friendly - constructive and encouraging
+(Press Enter for Thorough, or type your choice or any custom style description)"*
+
+Map the choice to `REVIEW_TONE`:
+
+| Answer | `REVIEW_TONE` | `REVIEW_STYLE_INSTRUCTIONS` |
+|---|---|---|
+| 1 / Enter | `"thorough"` | `""` |
+| 2 | `"concise"` | `""` |
+| 3 | `"friendly"` | `""` |
+| Custom text, e.g. `strict but kind` | `"thorough"` | the custom text verbatim |
+
+### Step 5 - Collect cron schedule
+
+Ask: *"How often should the automation poll for labeled PRs?
+(Press Enter for the default: every 5 minutes.
+Use a cron expression for a different interval, e.g. `0 * * * *` = hourly)"*
+
+Default: `*/5 * * * *`.
+
+Record as `CRON_SCHEDULE`.
+
+### Step 6 - Generate the automation script
+
+Read `scripts/main.py` from this skill's directory. Apply exactly five constant
+substitutions near the top of the file:
+
+| Placeholder | Replace with |
+|---|---|
+| `REPO = "owner/repo"` | `REPO = "{owner_repo}"` |
+| `TRIGGER_LABEL = "openhands-review"` | `TRIGGER_LABEL = "{trigger_label}"` |
+| `REVIEW_TONE = "thorough"` | `REVIEW_TONE = "{review_tone}"` |
+| `REVIEW_STYLE_INSTRUCTIONS = ""` | `REVIEW_STYLE_INSTRUCTIONS = "{style_instructions}"` |
+| `DEFAULT_OPENHANDS_URL = "http://localhost:8000"` | leave unchanged unless the user has a preference |
+
+Use a safe string writer such as `json.dumps(value)` when inserting user-provided
+repository names, labels, or style instructions into Python string literals.
+
+Write the customized script to a temporary build directory:
+```bash
+mkdir -p /tmp/pr-reviewer-build
+# write the customized main.py to /tmp/pr-reviewer-build/main.py
 ```
 
-If it fails, tell the user to install the GitHub MCP integration first.
+Validate syntax before packaging:
+```bash
+python3 -m py_compile /tmp/pr-reviewer-build/main.py && echo "Syntax OK"
+```
 
-### Step 2 — Determine trigger type
+Fix any syntax errors before proceeding.
 
-**Event-based (recommended if publicly reachable):**
-Check `<RUNTIME_SERVICES>` for deployment reachability. If the deployment has a public URL, recommend an event trigger on `pull_request.opened` and `pull_request.synchronize`.
+### Step 7 - Package and upload
 
-**Cron-based (local/private deployments):**
-If the deployment is local, set up a cron schedule (e.g. every 5 minutes) that polls for recently updated PRs.
+Determine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`
+block in your system context:
+- **OPENHANDS_HOST**: the Automation backend `url_from_agent`
+- **Auth**: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`
 
-### Step 3 — Build the review prompt
+```bash
+tar -czf /tmp/pr-reviewer.tar.gz -C /tmp/pr-reviewer-build .
 
-Construct a prompt for the automation that includes:
-- The user's chosen repositories
-- Review focus areas (correctness, security, tests, maintainability)
-- Review tone preference
-- Whether to auto-post or draft
+TARBALL_PATH=$(curl -s -X POST \
+  "${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-pr-reviewer" \
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "Content-Type: application/gzip" \
+  --data-binary @/tmp/pr-reviewer.tar.gz \
+  | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")
 
-### Step 4 — Create the automation
+echo "Uploaded: $TARBALL_PATH"
+```
 
-Read the Automation backend URL and auth from `<RUNTIME_SERVICES>`:
-- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`
-- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`
+### Step 8 - Register the automation
 
-Use the **prompt preset** endpoint:
 ```bash
-curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
+curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1" \
   -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{
-    "name": "GitHub PR Reviewer",
-    "prompt": "<constructed review prompt>",
-    "trigger": <trigger config from step 2>
-  }'
+  -d "{
+    \"name\": \"GitHub PR Reviewer: {owner}/{repo} label {trigger_label}\",
+    \"trigger\": {\"type\": \"cron\", \"schedule\": \"{cron_schedule}\"},
+    \"tarball_path\": \"$TARBALL_PATH\",
+    \"entrypoint\": \"python3 main.py\",
+    \"timeout\": 300
+  }" | python3 -m json.tool
 ```
 
-### Step 5 — Confirm
+Record the returned `id`.
+
+### Step 9 - Confirm
 
 Tell the user:
+
 > ✅ **GitHub PR Reviewer** is running!
 >
 > - Automation ID: `{id}`
-> - Repositories: `{repo list}`
-> - Trigger: `{trigger description}`
-> - Review style: `{tone}`, `{auto-post or draft}`
+> - Repository: `{owner}/{repo}`
+> - Trigger label: `{trigger_label}`
+> - Review tone: `{tone}`
+> - Polling schedule: `{cron_schedule}`
+> - State file: `~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_{id}.json`
+>
+> Apply the `{trigger_label}` label to a pull request to queue a review. Each
+> label event is processed once. To request another review, remove and re-apply
+> the label.
+
+---
+
+## Runtime Behaviour (per poll)
+
+Each cron run executes `main.py`, which:
+
+1. Loads state from the JSON file (see `references/state-schema.md`).
+2. Resolves and validates `GITHUB_PERSONAL_ACCESS_TOKEN` and repository access.
+3. Lists open PRs, newest-updated first.
+4. For each open PR carrying `TRIGGER_LABEL`:
+   - Refetches current PR metadata to avoid acting on stale list data.
+   - Finds the latest matching GitHub `labeled` issue event.
+   - Skips the event if it has already been tracked.
+   - Starts an OpenHands conversation with a review prompt that includes PR
+     metadata, the exact head SHA, label event details, and instructions to
+     clone the repo, inspect PR discussion, review comments, changed files,
+     diff, and surrounding code.
+   - Posts an acknowledgement comment with the label event, head SHA, and
+     conversation link.
+   - Records the label-event review in state with `status: "active"`.
+5. For each active review conversation:
+   - Marks it closed without posting if the PR has closed or merged.
+   - Suppresses stale results if the PR head SHA changed after the review was
+     queued.
+   - When the conversation reaches `idle`, `finished`, `error`, or `stuck`,
+     posts the agent's final response as a GitHub comment and marks the review
+     closed.
+6. Saves state atomically and fires the completion callback.
+
+---
+
+## Additional Resources
+
+- **`references/state-schema.md`** - State JSON schema, field definitions, and
+  review lifecycle diagram.
+- **`scripts/main.py`** - The complete automation script. Customize the five
+  constants at the top before packaging.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Bot never queues reviews | Trigger label not present or no matching `labeled` event | Apply the configured label to the PR |
+| "Bad credentials" in run logs | Token expired | Rotate and update `GITHUB_PERSONAL_ACCESS_TOKEN` |
+| 404 on repo access | Repo name wrong or no access | Re-check `owner/repo` and token permissions |
+| Same PR not reviewed after new commits | Label event was already processed | Remove and re-apply the trigger label |
+| Review result never posts | Conversation still running or stuck | Open the conversation link from the acknowledgement comment |
+| Stale review suppressed | PR head SHA changed while the agent was reviewing | Re-apply the trigger label after the latest commit |

package/skills/github-pr-reviewer/commands/pr-reviewer-setup.md

@@ -1,6 +1,6 @@
 ---
 # auto-generated by sync_extensions.py
-description: Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed files, tests, and existing discussion via GitHub MCP, then posts a concise review highlighting risks, security issues, missing tests, and next steps.
+description: Create an automation that reviews GitHub pull requests when a configurable trigger label is applied. Polls GitHub deterministically, starts one OpenHands review conversation per label event, inspects full repository and PR context, and posts the final review comment back to GitHub.
 ---
 
 Read and follow the complete instructions in the SKILL.md file located in this skill's directory.

package/skills/github-pr-reviewer/references/state-schema.md

@@ -0,0 +1,126 @@
+# State File Schema
+
+The automation maintains a JSON state file that persists across polling runs.
+It is the source of truth for which trigger-label events have queued reviews
+and which conversations are still active.
+
+---
+
+## File Location
+
+```
+{WORKSPACE_BASE_ROOT}/automation-state/github_pr_reviewer_label_event_{automation_id}.json
+```
+
+`WORKSPACE_BASE_ROOT` is derived by going two levels up from the `WORKSPACE_BASE`
+environment variable, stripping `automation-runs/{run_id}`.
+
+Example on a local install:
+
+```
+~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_abc12345-....json
+```
+
+The `automation_id` is read from the `AUTOMATION_EVENT_PAYLOAD` environment
+variable, field `automation_id`.
+
+---
+
+## Top-Level Schema
+
+```jsonc
+{
+  "version": 2,
+  "repo": "owner/repo",
+  "trigger_label": "openhands-review",
+  "updated_at": 1717200000.0,
+  "reviews": {},
+  "prs": {}
+}
+```
+
+---
+
+## `reviews` Map
+
+Key: `"{pr_number}:label:{label_event_id}"`. This makes the latest GitHub
+`labeled` event the idempotency key. Re-applying the trigger label creates a new
+GitHub event and therefore a new review request.
+
+Value: **ReviewRecord**
+
+```jsonc
+{
+  "pr_number": 42,
+  "head_sha": "0123456789abcdef...",
+  "trigger_label_event_id": 123456789,
+  "trigger_label_event_created_at": "2026-06-12T00:00:00Z",
+  "html_url": "https://github.com/owner/repo/pull/42",
+  "status": "active",
+  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
+  "last_activity": 1717200000.0
+}
+```
+
+`status` values:
+
+| Status | Meaning |
+|---|---|
+| `active` | Review conversation is running or waiting to be collected |
+| `closed` | Final result was posted, or the PR closed before collection |
+| `stale` | PR head SHA changed before the review completed, so the result was suppressed |
+
+When a review becomes stale, `stale_reason` records the old and new head SHAs.
+When a review closes after posting, `completed_at` records the completion time.
+
+---
+
+## `prs` Map
+
+Key: `"{pr_number}"`.
+
+Value: latest PR snapshot observed during polling:
+
+```jsonc
+{
+  "head_sha": "0123456789abcdef...",
+  "label_present": true,
+  "labels": ["openhands-review", "bug"],
+  "last_seen": 1717200000.0
+}
+```
+
+This snapshot is informational and helps diagnose whether a PR was skipped
+because the trigger label was absent.
+
+---
+
+## Review Lifecycle
+
+```
+Trigger label applied on GitHub
+        |
+        v
+[active]  - conversation created, acknowledgement comment posted
+        |
+        +-- PR closes/merges before collection --> [closed] without posting
+        |
+        +-- PR head SHA changes before collection --> [stale] without posting
+        |
+        v
+[closed]  - final review comment posted
+```
+
+---
+
+## Resetting State
+
+To force the automation to reconsider previous label events, delete the state
+file:
+
+```bash
+rm ~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_<id>.json
+```
+
+Usually, prefer removing and re-applying the trigger label. That preserves
+history while creating a new review request.