@openhands/extensions 0.4.1 → 0.5.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.1"
+  ".": "0.5.0"
 }

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/automations/catalog/slack-channel-monitor.json

@@ -2,10 +2,10 @@
   "id": "slack-channel-monitor",
   "name": "Slack channel monitor",
   "category": "Team communication",
-  "description": "Watch Slack channels for @openhands mentions, open a conversation with the message context, and reply in the thread when the agent finishes.",
+  "description": "Watch Slack channels for @openhands mentions, open a conversation with the message context, reply when the agent finishes, and continue the same conversation from triggered Slack thread follow-ups.",
   "requiredIntegrationIds": ["slack"],
   "popularityRank": 92,
   "estimatedSetupMinutes": 7,
   "prompt": "/slack-monitor:poll",
-  "exampleImplementation": "Trigger: cron, every minute\nRequired secret: SLACK_BOT_TOKEN or SLACK_USER_TOKEN\n\n1. Poll up to 10 configured Slack channels for new messages since the last run.\n2. Match messages containing the trigger phrase (default: @openhands).\n3. React with 👀 and start an OpenHands conversation with the message and recent channel context.\n4. Post a thread reply with a link to the conversation.\n5. Forward subsequent thread replies to the running conversation and post the agent's response when done."
+  "exampleImplementation": "Trigger: cron, every minute\nRequired secret: SLACK_BOT_TOKEN or SLACK_USER_TOKEN\n\n1. Poll up to 10 configured Slack channels for new messages since the last run.\n2. Match messages containing the trigger phrase (default: @openhands).\n3. React with 👀 and start an OpenHands conversation with the message and recent channel context.\n4. Post a thread reply with a link to the conversation, then post the agent response when done.\n5. Keep the thread in a short follow-up watch window and forward only replies that repeat the trigger phrase to the same conversation, with per-thread backoff for quiet threads."
 }

package/integrations/catalog/github.json

@@ -12,7 +12,6 @@
     "code"
   ],
   "popularityRank": 100,
-  "installHint": "Requires Docker because the legacy npm package was deprecated upstream.",
   "kind": "mcp",
   "defaultConnectionOptionId": "api",
   "connectionOptions": [
@@ -20,31 +19,16 @@
       "id": "api",
       "provider": "mcp",
       "transport": {
-        "kind": "stdio",
-        "serverName": "github",
-        "command": "docker",
-        "args": [
-          "run",
-          "-i",
-          "--rm",
-          "-e",
-          "GITHUB_PERSONAL_ACCESS_TOKEN",
-          "ghcr.io/github/github-mcp-server"
-        ],
-        "envFields": [
-          {
-            "key": "GITHUB_PERSONAL_ACCESS_TOKEN",
-            "label": "Personal access token",
-            "type": "password",
-            "placeholder": "github_pat_...",
-            "required": true,
-            "helperText": "Classic or fine-grained personal access token from GitHub settings.",
-            "helperLink": "https://github.com/settings/tokens"
-          }
-        ]
+        "kind": "shttp",
+        "url": "https://api.githubcopilot.com/mcp/"
       },
       "auth": {
-        "strategy": "api_key"
+        "strategy": "api_key",
+        "credentialLabel": "Personal access token",
+        "credentialPlaceholder": "github_pat_...",
+        "credentialHelp": "Classic or fine-grained personal access token from GitHub settings.",
+        "credentialSecretName": "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "saveCredentialAsSecretByDefault": true
       }
     }
   ]

package/integrations/index.d.ts

@@ -59,6 +59,8 @@ export interface IntegrationAuthConfig {
   credentialLabel?: string;
   credentialPlaceholder?: string;
   credentialHelp?: string;
+  credentialSecretName?: string;
+  saveCredentialAsSecretByDefault?: boolean;
   apiKeyHeaderName?: string;
   apiKeyOptional?: boolean;
   oauth?: IntegrationOAuthConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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.1"
+version = "0.5.0"
 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,22 +1,23 @@
 ---
 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
 
-Create a cron automation that polls a GitHub repository, reviews each open
-pull request exactly once, and posts the AI review as a GitHub comment.
+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 fully deterministic: PR discovery, state tracking,
-and deduplication are handled in Python. The LLM is only invoked to write
-the review text for PRs not yet seen, never for orchestration.
+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.
 
 ---
 
@@ -24,12 +25,12 @@ the review text for PRs not yet seen, never for orchestration.
 
 ### Required secret
 
-Verify that the following secret is set in **OpenHands Settings → Secrets**:
+Verify that the following secret is set in **OpenHands Settings -> Secrets**:
 
 | Secret name | Token type | Minimum permissions |
 |---|---|---|
-| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` (private) or `public_repo` (public) |
-| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Pull requests: Read and Write |
+| `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 |
 
 Check with:
 ```bash
@@ -46,16 +47,16 @@ If the token is missing or invalid, inform the user and stop.
 
 Follow these steps in order.
 
-### Step 1 — Verify GITHUB_PERSONAL_ACCESS_TOKEN
+### 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.
+  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.
 
-### Step 2 — Collect repository
+### Step 2 - Collect repository
 
 Ask: *"Which GitHub repository should be monitored?
 (Format: `owner/repo`, e.g. `myorg/backend`)"*
@@ -76,26 +77,38 @@ else:
 
 Record `REPO = "{owner}/{repo}"`.
 
-### Step 3 — Collect review tone
+### 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
+  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. "hostile pirate") | `"thorough"` | the custom text verbatim |
+| Custom text, e.g. `strict but kind` | `"thorough"` | the custom text verbatim |
 
-### Step 4 — Collect cron schedule
+### Step 5 - Collect cron schedule
 
-Ask: *"How often should the automation poll for new PRs?
+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)"*
 
@@ -103,22 +116,26 @@ Default: `*/5 * * * *`.
 
 Record as `CRON_SCHEDULE`.
 
-### Step 5 — Generate the automation script
+### Step 6 - Generate the automation script
 
-Read `scripts/main.py` from this skill's directory. Apply exactly four
-constant substitutions near the top of the file:
+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 |
 
-Write the customised script to a temporary build directory:
+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 customised main.py to /tmp/pr-reviewer-build/main.py
+# write the customized main.py to /tmp/pr-reviewer-build/main.py
 ```
 
 Validate syntax before packaging:
@@ -128,7 +145,7 @@ python3 -m py_compile /tmp/pr-reviewer-build/main.py && echo "Syntax OK"
 
 Fix any syntax errors before proceeding.
 
-### Step 6 — Package and upload
+### Step 7 - Package and upload
 
 Determine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`
 block in your system context:
@@ -148,14 +165,14 @@ TARBALL_PATH=$(curl -s -X POST \
 echo "Uploaded: $TARBALL_PATH"
 ```
 
-### Step 7 — Register the automation
+### Step 8 - Register the automation
 
 ```bash
 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: {owner}/{repo}\",
+    \"name\": \"GitHub PR Reviewer: {owner}/{repo} label {trigger_label}\",
     \"trigger\": {\"type\": \"cron\", \"schedule\": \"{cron_schedule}\"},
     \"tarball_path\": \"$TARBALL_PATH\",
     \"entrypoint\": \"python3 main.py\",
@@ -165,7 +182,7 @@ curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1" \
 
 Record the returned `id`.
 
-### Step 8 — Confirm
+### Step 9 - Confirm
 
 Tell the user:
 
@@ -173,13 +190,14 @@ Tell the user:
 >
 > - Automation ID: `{id}`
 > - Repository: `{owner}/{repo}`
+> - Trigger label: `{trigger_label}`
 > - Review tone: `{tone}`
 > - Polling schedule: `{cron_schedule}`
-> - State file: `~/.openhands/workspaces/automation-state/github_pr_reviewer_{id}.json`
+> - State file: `~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_{id}.json`
 >
-> The next cron run will discover all currently open PRs and queue reviews.
-> Each PR is reviewed exactly once; state is stored in the JSON file above.
-> To force a re-review of all PRs, delete the state file.
+> 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.
 
 ---
 
@@ -187,36 +205,37 @@ Tell the user:
 
 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`** — aborts
-   immediately if absent or invalid.
-3. **Lists all open PRs** in the configured repository.
-4. **For each PR not yet in state**:
-   - Fetches the unified diff via the GitHub API.
-   - Skips PRs whose diff exceeds `MAX_DIFF_LINES_SKIP` (default 5000 lines)
-     and posts an explanatory comment.
-   - Truncates diffs larger than `MAX_DIFF_LINES` (default 500 lines) and
-     notes this in the prompt.
-   - Creates an OpenHands conversation with the PR metadata, diff, and
-     configured tone instructions as the initial message.
-   - Posts an acknowledgement comment on the PR with a link to the conversation.
-   - Records the PR in state with `status: "active"`.
-5. **For each active conversation**:
-   - Skips PRs that have been closed or merged (marks them closed silently).
-   - Checks the conversation's `execution_status`.
-   - When it reaches `idle`, `finished`, `error`, or `stuck`:
-     posts the agent's final response as a GitHub comment and marks the
-     conversation `closed`.
-6. **Saves updated state** and fires the completion callback.
+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 conversation lifecycle diagram.
-- **`scripts/main.py`** — The complete automation script. Customise the
-  four constants at the top before packaging.
+- **`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.
 
 ---
 
@@ -224,9 +243,9 @@ Each cron run executes `main.py`, which:
 
 | Symptom | Likely cause | Fix |
 |---|---|---|
-| Bot never posts reviews | `GITHUB_PERSONAL_ACCESS_TOKEN` missing or wrong scopes | Verify token; check Step 1 |
-| "Bad credentials" in run logs | Token expired | Rotate and update the secret |
+| 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 reviewed twice | State file deleted or corrupted | Check that the state file path is stable across runs |
-| Review never posted | Conversation stuck in `running` | Open the conversation in the OpenHands UI |
-| PR skipped silently | Diff too large | Raise `MAX_DIFF_LINES_SKIP` in the script or split the PR |
+| 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.