@openhands/extensions 0.27.0 → 0.28.0

package/automations/catalog/github-issue-to-pr/manifest.json

@@ -98,7 +98,7 @@
       }
     },
     "bundle": {
-      "version": "1.2.1",
+      "version": "1.2.2",
       "entrypoint": "python3 worker.py",
       "timeout": 300,
       "files": {
@@ -117,5 +117,5 @@
     },
     "message": "Configure the repositories, labels, branch prefix, pull request mode, agent profile, and schedule."
   },
-  "version": "1.2.1"
+  "version": "1.2.2"
 }

package/automations/catalog/github-issue-triage/manifest.json

@@ -1,6 +1,6 @@
 {
   "id": "github-issue-triage",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "name": "GitHub issue triage",
   "category": "Project management",
   "description": "Prioritize open issues and establish acceptance criteria before marking them ready for development.",
@@ -54,7 +54,7 @@
       }
     },
     "bundle": {
-      "version": "1.3.0",
+      "version": "1.3.1",
       "entrypoint": "python3 worker.py",
       "timeout": 300,
       "files": {

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

@@ -1,6 +1,6 @@
 {
   "id": "github-pr-reviewer",
-  "version": "1.8.1",
+  "version": "1.9.2",
   "name": "GitHub code review",
   "category": "Code review",
   "description": "Review requested pull-request heads, resume an outstanding reviewer request on a schedule once its checks are green, classify all open non-draft pull requests that nobody requested and review eligible green heads, drain the backlog oldest-first under a small per-scan new-conversation bound, record exact-head decisions, stop early on out-of-scope changes, and optionally request a code-aware human maintainer after approval or a maintainer-decision scope stop.",
@@ -135,7 +135,7 @@
       }
     },
     "bundle": {
-      "version": "1.8.1",
+      "version": "1.9.2",
       "entrypoint": "python3 worker.py",
       "timeout": 300,
       "files": {

package/marketplaces/openhands-extensions.json

@@ -830,6 +830,15 @@
         "technical-writing"
       ]
     },
+    {
+      "name": "simplified-technical-english",
+      "source": "./skills/simplified-technical-english",
+      "description": "Write explanations and chat in the style of ASD-STE100 Simplified Technical English: short active sentences, one idea each, plain consistent words. Applies to prose only, never to code.",
+      "category": "writing",
+      "keywords": [
+        "simplified-technical-english"
+      ]
+    },
     {
       "name": "plain-english-content",
       "source": "./skills/plain-english-content",

package/package.json

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

package/plugins/openhands/skills/openhands-automation/README.md

@@ -16,13 +16,13 @@ This skill is activated by keywords:
 
 ## Features
 
-- **Prompt-based creation**: Create automations from a natural language prompt (recommended)
+- **Prompt-based creation**: Create automations from a natural language prompt, for tasks that benefit from agent reasoning
+- **Custom scripts**: Run your own code, with or without an LLM — the cheaper, more reliable fit for deterministic tasks (fixed data, scheduled HTTP calls, templated messages), and for custom dependencies or full control (see [references/custom-automation.md](references/custom-automation.md))
 - **Event-triggered automations**: Trigger on GitHub events (PR opened, issue commented, push, etc.)
 - **Custom webhooks**: Register webhooks for any service (Stripe, Slack, Linear, etc.)
 - **JMESPath filters**: Match events based on payload content (labels, mentions, repos)
 - **Automation management**: List, update, enable/disable, and delete automations
 - **Manual dispatch**: Trigger automation runs on-demand
-- **Custom automations**: For advanced users who need full control (see [references/custom-automation.md](references/custom-automation.md))
 
 ## API Base URL
 
@@ -30,6 +30,8 @@ Use an explicitly provided host first. When a local Agent Canvas automation serv
 
 ## Quick Start
 
+The examples below use the prompt preset, which suits tasks that need reasoning or judgment. For a deterministic task that needs no LLM, use a custom script instead — see the *Custom Script Example (No LLM)* in [SKILL.md](SKILL.md).
+
 ### Cron-Triggered Automation
 
 ```bash
@@ -81,9 +83,9 @@ curl -X POST "https://app.all-hands.dev/api/automation/v1/preset/prompt" \
   }'
 ```
 
-The service handles SDK code generation, tarball packaging, upload, and automation creation automatically.
+For preset automations, the service handles SDK code generation, tarball packaging, upload, and automation creation automatically.
 
 ## See Also
 
 - [SKILL.md](SKILL.md) — Full API reference, agent behavior rules, event keys, filters, and examples
-- [references/custom-automation.md](references/custom-automation.md) — Reference for custom automations with user-provided SDK scripts
+- [references/custom-automation.md](references/custom-automation.md) — Reference for custom automations with user-provided scripts, SDK-based or deterministic (no LLM)

package/plugins/openhands/skills/openhands-automation/SKILL.md

@@ -64,14 +64,14 @@ The agent server typically runs inside a **sandbox** (a Docker or Kubernetes con
 > 1. **For LLM-appropriate work, default to preset endpoints.** They handle all SDK boilerplate, tarball packaging, and upload automatically:
 >    - **Prompt preset** (`POST /v1/preset/prompt`) — for tasks expressed as a natural language prompt that benefit from agent reasoning
 >    - **Plugin preset** (`POST /v1/preset/plugin`) — when plugins with skills, MCP configs, or commands are needed
-> 2. **Do not silently create custom scripts.** Do not generate Python code, `setup.sh` files, or tarball uploads without user consent. But *do* proactively recommend the custom path (per rule 0) when the task is deterministic or high-frequency — surface the option and let the user choose.
-> 3. **If neither preset is the right fit**, do NOT silently fall back to custom automation. Instead, explain the available options to the user:
->    - **Prompt preset** — natural language prompt execution (LLM-driven)
->    - **Plugin preset** — load plugins with extended capabilities (skills, MCP, hooks, commands)
->    - **Custom script** — full control over code, with or without LLM; point them to `references/custom-automation.md`
->    - Let the user choose which approach to use.
-> 4. **Only create custom scripts after the user agrees to that path.** Refer to `references/custom-automation.md` for the full reference.
-> 5. **Before suggesting event-triggered (webhook) automations, check whether the deployment is publicly reachable.** Check `RUNTIME_URL`. Webhooks require an internet-accessible URL so that external services (GitHub, Slack, Linear, etc.) can deliver events to the automation service. If `RUNTIME_URL` is unset, empty, or resolves to a local or private address (`localhost`, `127.0.0.1`, `0.0.0.0`, or any RFC 1918 range: `10.x.x.x`, `192.168.x.x`, `172.16–31.x.x`), the service cannot receive inbound webhook traffic from the public internet. In that case:
+> 2. **Present the options, then build the one the user picks.** Whenever rule 0 applies, or neither preset is a clean fit (custom Python dependencies, a non-Python entrypoint, a multi-file project, direct SDK lifecycle control), lay the choices out side by side with a one-line note on cost and reliability for each, and let the user choose:
+>    - **Prompt preset** - natural language prompt execution (LLM-driven)
+>    - **Plugin preset** - load plugins with extended capabilities (skills, MCP, hooks, commands)
+>    - **Custom script** - full control over code, with or without an LLM; see `references/custom-automation.md`
+>
+>    Do not silently fall back to either side. The "ready to deploy?" confirmation in the creation process applies to every path equally; a custom script needs no extra permission beyond it, and a preset gets no pass on it.
+> 3. **Building a custom script:** follow `references/custom-automation.md` for tarball packaging, validation, and upload. The *Custom Script Example (No LLM)* below shows the whole flow end to end.
+> 4. **Before suggesting event-triggered (webhook) automations, check whether the deployment is publicly reachable.** Check `RUNTIME_URL`. Webhooks require an internet-accessible URL so that external services (GitHub, Slack, Linear, etc.) can deliver events to the automation service. If `RUNTIME_URL` is unset, empty, or resolves to a local or private address (`localhost`, `127.0.0.1`, `0.0.0.0`, or any RFC 1918 range: `10.x.x.x`, `192.168.x.x`, `172.16–31.x.x`), the service cannot receive inbound webhook traffic from the public internet. In that case:
 >    - **Recommend a cron-based polling automation instead.** Have the automation run on a schedule and call the external service's API (e.g., the GitHub REST API) to check for new events since the last run.
 >    - Explain the limitation clearly to the user: "Because this is a local deployment, external services can't reach the webhook endpoint. I'll set up a polling automation using a cron schedule instead."
 
@@ -255,8 +255,10 @@ curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
 Write the prompt as an instruction to an AI agent. The prompt executes inside a sandbox with full tool access (bash, file editing, etc.), the user's configured LLM, stored secrets, and MCP server integrations. Examples:
 
 - `"Generate a weekly status report summarizing the team's GitHub activity and post it to Slack"`
-- `"Check the production API health endpoint every hour and alert if it returns non-200"`
-- `"Pull the latest data from our analytics API and update the dashboard spreadsheet"`
+- `"Read yesterday's new error reports in Sentry, group them by likely root cause, and open one GitHub issue per new failure pattern with a proposed fix"`
+- `"Go through support tickets tagged 'bug' since the last run, try to reproduce each against main, and comment on the ticket with what you found"`
+
+Each of these needs judgment: deciding what counts as a pattern, whether a reproduction succeeded, what is worth reporting. A task whose output could be written as a fixed template right now belongs in a custom script instead (see *Custom Script Example (No LLM)* below).
 
 #### Cron Schedule
 
@@ -296,24 +298,105 @@ curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   }'
 ```
 
-**Weekly cleanup:**
+**Weekly dependency review:**
 ```bash
 curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
-    "name": "Weekly Cleanup",
-    "prompt": "Clean up temporary files older than 7 days and send a summary of what was removed",
+    "name": "Weekly Dependency Review",
+    "prompt": "Check the repository dependencies for new releases. Read each changelog, open one PR with the upgrades that look safe, and list any release with breaking changes in the PR description so a human can decide on it",
     "trigger": {"type": "cron", "schedule": "0 2 * * 0", "timezone": "UTC"},
-    "timeout": 300
+    "timeout": 1800
   }'
 ```
 
+### Custom Script Example (No LLM)
+
+The same shape as the prompt preset, for a task that needs no reasoning: check a URL on a schedule and post to Slack only when it fails. Every run takes a moment and costs no tokens. This is the complete flow; `get_secret` and `fire_callback` are the helpers from *No-LLM Script Helpers* above.
+
+```bash
+mkdir healthcheck && cd healthcheck
+
+cat > main.py << 'PYEOF'
+"""Hourly health check: alert Slack on a non-200 response. No LLM, no SDK."""
+import json, os, sys, urllib.request
+
+URL = "https://api.example.com/health"
+CHANNEL = "C12345678"
+
+def get_secret(name):
+    url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
+    key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
+    if url:  # local Agent Canvas
+        url = f"{url}/api/settings/secrets/{name}"
+    else:  # OpenHands Cloud / Enterprise
+        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
+    req = urllib.request.Request(url,
+        headers={"X-Session-API-Key": key})
+    with urllib.request.urlopen(req) as r:
+        return r.read().decode().strip()
+
+def fire_callback(status="COMPLETED", error=None):
+    url = os.environ.get("AUTOMATION_CALLBACK_URL", "")
+    if not url: return
+    body = {"status": status, "run_id": os.environ.get("AUTOMATION_RUN_ID", "")}
+    if error: body["error"] = error
+    req = urllib.request.Request(url, data=json.dumps(body).encode(), headers={
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {os.environ.get('AUTOMATION_CALLBACK_API_KEY', '')}",
+    })
+    try: urllib.request.urlopen(req)
+    except Exception as e: print(f"Callback error: {e}")
+
+def slack(text):
+    token = get_secret("SLACK_BOT_TOKEN")
+    req = urllib.request.Request("https://slack.com/api/chat.postMessage",
+        data=json.dumps({"channel": CHANNEL, "text": text}).encode(),
+        headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"})
+    urllib.request.urlopen(req)
+
+try:
+    try:
+        status = urllib.request.urlopen(URL, timeout=10).status
+    except Exception as e:
+        status = f"error: {e}"
+    if status != 200:
+        slack(f":rotating_light: {URL} returned {status}")
+    print(f"{URL} -> {status}")
+    fire_callback("COMPLETED")
+except Exception as e:
+    print(f"ERROR: {e}", file=sys.stderr)
+    fire_callback("FAILED", str(e))
+    sys.exit(1)
+PYEOF
+
+tar -czf ../healthcheck.tar.gz .
+
+TARBALL_PATH=$(curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/uploads?name=healthcheck" \
+  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
+  -H "Content-Type: application/gzip" \
+  --data-binary @../healthcheck.tar.gz | jq -r '.tarball_path')
+
+curl -X POST "${OPENHANDS_HOST}/api/automation/v1" \
+  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"name\": \"Hourly Health Check\",
+    \"trigger\": {\"type\": \"cron\", \"schedule\": \"0 * * * *\", \"timezone\": \"UTC\"},
+    \"tarball_path\": \"$TARBALL_PATH\",
+    \"entrypoint\": \"python3 main.py\"
+  }"
+```
+
+For state between runs (last alert time, last seen event), use the KV store helpers in `references/custom-automation.md#state-persistence-kv-store`.
+
 ---
 
 ## Polling as a Webhook Alternative
 
-When the deployment cannot receive inbound webhook traffic (see rule 5), use a cron-triggered automation that calls the external service’s API on a schedule to check for new events.
+When the deployment cannot receive inbound webhook traffic (see rule 4), use a cron-triggered automation that calls the external service’s API on a schedule to check for new events.
 
 ### Polling vs. Webhooks at a Glance
 
@@ -442,15 +525,15 @@ curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   }'
 ```
 
-#### GitHub: Run tests on push to main
+#### GitHub: Flag risky changes pushed to main
 
 ```bash
 curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
-    "name": "Run Tests on Main",
-    "prompt": "Clone the repository and run the test suite. Report any failures.",
+    "name": "Risky Change Watch",
+    "prompt": "Review the diff of this push. If it touches authentication, billing, data migrations, or anything that changes behavior for existing users, open an issue that explains the risk in plain terms and mentions the code owners. Otherwise do nothing.",
     "trigger": {
       "type": "event",
       "source": "github",
@@ -942,7 +1025,7 @@ The **prompt preset** is the right default for genuinely agent-shaped work — a
 
 **Watch for deterministic, high-frequency patterns.** Requests like "send a daily standup reminder", "ping a healthcheck URL every minute", "post a random quote every 5 minutes", or "rotate a fact-of-the-day message" do not need an LLM. Surface this to the user explicitly with a rough cost framing (e.g. "this schedule will invoke your LLM ~288 times/day") before defaulting to a preset. As a rule of thumb, any cron tighter than hourly deserves a deliberate "should this really be agent-driven?" check.
 
-**When neither preset is the right fit** (deterministic task, custom Python dependencies, non-Python entrypoint, multi-file project structure, direct SDK lifecycle control), explain the options to the user and let them decide. Do not attempt custom automation without explicit user agreement. If they choose the custom route, refer to `references/custom-automation.md`.
+**When neither preset is the right fit** (deterministic task, custom Python dependencies, non-Python entrypoint, multi-file project structure, direct SDK lifecycle control), explain the options and let the user decide, exactly as for any other automation. If they choose the custom route, follow `references/custom-automation.md` and the *Custom Script Example (No LLM)* above.
 
 ## Security Considerations
 
@@ -955,7 +1038,6 @@ See `references/security.md` — also covers narrowing triggers and sender-level
 
 ## Reference Files
 
-- **`references/custom-automation.md`** — Detailed guide for custom automations: tarball uploads, code structure (SDK and no-LLM), state persistence via the KV store, environment variables, validation rules, and complete examples. Consult this whenever you need to evaluate or recommend the custom path (including for deterministic / cost-sensitive tasks per rule 0). Only *implement* a custom automation after the user agrees to that path.
+- **`references/custom-automation.md`** — Detailed guide for custom automations: tarball uploads, code structure (SDK and no-LLM), state persistence via the KV store, environment variables, validation rules, and complete examples. Consult this whenever you need to evaluate, recommend, or build the custom path (including for deterministic / cost-sensitive tasks per rule 0).
 - **`references/ab-testing.md`** — A/B testing for plugin automations: defining variants with weights, experiment configuration, variant selection logic, observability via conversation tags, and complete examples. Consult this when a user wants to compare plugin versions or configurations.
-- **`references/security.md`** — Trust boundaries: untrusted content vs. verified sender, least-privilege secrets, trigger scoping, sender authorization, pre-deploy verification. Consult whenever an automation handles external input or forwards secrets to a spawned conversation.
 - **`references/security.md`** — Trust boundaries for automations: untrusted event content vs. verified sender, least-privilege secret scoping for spawned conversations, narrowing triggers, sender-level authorization, and verifying a script actually runs before deploying it. Consult this whenever an automation handles external/untrusted input (GitHub issues/PRs, Slack messages, any public-facing webhook) or forwards secrets to a spawned conversation.

package/plugins/openhands/skills/openhands-automation/references/custom-automation.md

@@ -1,13 +1,12 @@
 # Custom Automation Reference
 
-> **⚠️ Do NOT use this reference unless the user has explicitly requested a custom automation.** Always use the preset/prompt endpoint from the main SKILL.md first. If the preset approach cannot satisfy the requirement, explain the options to the user and let them decide.
-
 This file contains detailed documentation for creating custom automations with user-provided code, uploads, and entrypoints.
 
-**When to use custom automation (only if the user explicitly chooses this):**
+**When to use a custom automation:**
+- The task is deterministic and needs no LLM (fixed data, scheduled HTTP calls, templated messages), especially on a frequent schedule
 - Full control over the automation code structure is needed
 - Custom dependencies or a specific runtime are required
-- The user has confirmed that the prompt preset does not meet their requirements
+- The user picked this path after seeing the options side by side (see the agent behavior rules in `SKILL.md`)
 
 ## Table of Contents
 

package/plugins/openhands/skills/openhands-sdk/SKILL.md

@@ -131,10 +131,11 @@ print("All done!")
 - [Secret Registry](https://docs.openhands.dev/sdk/guides/secrets.md): Provide environment variables and secrets to agent workspace securely.
 - [Security & Action Confirmation](https://docs.openhands.dev/sdk/guides/security.md): Control agent action execution through confirmation policy and security analyzer.
 - [Send Message While Running](https://docs.openhands.dev/sdk/guides/convo-send-message-while-running.md): Interrupt running agents to provide additional context or corrections.
-- [Software Agent SDK](https://docs.openhands.dev/sdk.md): Build AI agents that write software. A clean, modular SDK with production-ready tools.
+- [Software Agent SDK](https://docs.openhands.dev/sdk/index.md): Build AI agents that write software. A clean, modular SDK with production-ready tools.
 - [Structured Output](https://docs.openhands.dev/sdk/guides/structured-output.md): Attach a schema to any tool so the LLM returns typed, validated fields alongside the tool's own arguments.
 - [Stuck Detector](https://docs.openhands.dev/sdk/guides/agent-stuck-detector.md): Detect and handle stuck agents automatically with timeout mechanisms.
 - [Task Tool Set](https://docs.openhands.dev/sdk/guides/task-tool-set.md): Delegate complex work to specialized sub-agents that run synchronously and return results to the parent agent.
+- [Task-Based Model Routing](https://docs.openhands.dev/sdk/guides/llm-task-routing.md): Let the agent pick the best saved LLM profile for the task at hand with the built-in route_task_to_model tool.
 - [Theory of Mind (TOM) Agent](https://docs.openhands.dev/sdk/guides/agent-tom-agent.md): Enable your agent to understand user intent and preferences through Theory of Mind capabilities, providing personalized guidance based on user modeling.
 - [TODO Management](https://docs.openhands.dev/sdk/guides/github-workflows/todo-management.md): Implement TODOs using OpenHands Agent
 

package/plugins/qa-changes/README.md

@@ -121,6 +121,10 @@ The agent posts a PR comment with this structure:
 ### Functional Verification
 [Commands run, outputs observed, screenshots, behavior verified]
 
+### Visual Evidence (frontend PRs only)
+[Screenshots of each affected state and a GIF of the key interaction, embedded
+inline or saved to the run's `openhands-qa-changes-logs` artifact]
+
 ### Unable to Verify (if applicable)
 [What could not be verified, what was attempted, suggested AGENTS.md guidance]
 

package/plugins/qa-changes/skills/qa-changes/README.md

@@ -14,5 +14,7 @@ The skill guides the agent through four phases:
 
 1. **Understand** — Classify changes and identify entry points
 2. **Setup** — Install dependencies, build, check CI status
-3. **Exercise** — Run the actual code as a user would (browser, CLI, API requests)
+3. **Exercise** — Run the actual code as a user would (browser, CLI, API requests).
+   For frontend changes, capture screenshots of each affected state and a GIF of
+   the key interaction (before/after where behavior changes)
 4. **Report** — Post a structured QA report with evidence and a verdict

package/plugins/qa-changes/skills/qa-changes/SKILL.md

@@ -75,6 +75,37 @@ This is the most important phase. **Actually use the software** the way a real u
 - Verify the visual change renders correctly. Take screenshots as evidence.
 - Test user interactions (clicks, form submissions, navigation).
 - Try at least one edge case (empty state, long text, missing data).
+- Then capture visual evidence and attach it to the PR (see next step).
+
+**Capture visual evidence (frontend PRs only):**
+
+If the PR has frontend work, run the affected screens from the branch's final
+state and record what a reviewer would otherwise have to imagine from the diff.
+The goal: the change can be reviewed **by observation, not by reading code.**
+
+1. **Screenshot each relevant state** of every affected screen - whichever
+   apply: *empty*, *loading*, *error*, and *populated*. Skip states the screen
+   genuinely cannot reach.
+2. **Record the key interaction end to end** - the main flow the PR changes,
+   driven the way a user would. Prefer a GIF: GitHub renders a GIF inline from
+   an image link, but only links a video file.
+3. **Where behavior changes, capture before/after** - the same state or
+   interaction on the base branch and on the PR branch, so the delta is
+   visible.
+4. **Attach it to the report.** Embed the images and GIF in the QA report so
+   they render inline, and label each one (screen and state, or before/after).
+   Do not push commits to the PR branch to host media: that changes the head
+   you are verifying, and the shipped QA workflow has read-only access to
+   repository contents. If you cannot upload media where the report is posted,
+   save the files where the run keeps its artifacts, say where to find them,
+   and describe in text what each capture shows. In the `qa-changes` GitHub
+   Action that is `$GITHUB_WORKSPACE/output/`, the parent of the PR checkout
+   you work in, which the action uploads as the `openhands-qa-changes-logs`
+   artifact; a relative `output/` inside the checkout is not uploaded.
+
+Keep it proportional: capture the screens the PR actually touches, not the whole
+app. If you cannot render a screen (missing data, an unreachable state, no
+browser), say so in the report rather than faking it.
 
 **For CLI changes:**
 - Run the CLI command with realistic arguments. Capture stdout and stderr.
@@ -181,6 +212,16 @@ prior state rather than reproducing a failure.}
 
 </details>
 
+<details><summary>Visual Evidence</summary>
+
+{Frontend PRs only. Embed the screenshots (per screen and state: empty,
+loading, error, populated) and the GIF of the key interaction so they
+render inline, or say where the captures are stored if they could not be
+uploaded. Where behavior changed, show before/after. Label each clearly.
+Omit this section entirely for non-frontend PRs.}
+
+</details>
+
 <details><summary>Unable to Verify</summary>
 
 {What could not be verified, what was attempted, and suggested
@@ -221,6 +262,7 @@ was verified.}
 - **Run the code, not the tests.** Execute the actual software — start servers, run CLI commands, make HTTP requests, open browsers. Do not run `pytest`, `npm test`, or equivalent test suites. That is CI's job.
 - **Do not analyze code.** Reading files and commenting on style, structure, or logic is code review's job. Your job is to exercise behavior, not read source files.
 - **Set a high bar.** If the change affects a UI, open it in a real browser. If it affects a CLI, run the actual CLI with real inputs. If it affects an API, make real HTTP requests.
+- **Make frontend changes reviewable by observation.** For UI PRs, attach screenshots of each relevant state and a GIF of the key interaction (before/after where behavior changes) so a reviewer can see the change, not infer it from the diff.
 - **Test what the PR claims.** The PR description is the specification. Verify the claim, not hypothetical scenarios.
 - **Leave CI to CI.** Do not re-run tests, linters, formatters, or type checkers. Note CI status, then focus entirely on functional verification that CI cannot do.
 - **Report evidence, not opinions.** Include exact commands, outputs, and error messages — inside collapsible blocks.

package/plugins/vulnerability-remediation/skills/github/README.md

@@ -11,6 +11,8 @@ This skill is activated by the following keywords:
 
 ## Details
 
+Use authenticated GitHub MCP tools first when they are available in the agent's environment. Detect the connection through tool availability rather than a particular server name. Fall back to the documented `GITHUB_TOKEN` and direct API flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with
 the GitHub API.
 
@@ -39,4 +41,6 @@ Here are some instructions for pushing, but ONLY do this if the user asks you to
 ```bash
 git remote -v && git branch # to find the current org, repo and branch
 git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
-```
+```
+
+When asked to merge a pull request, the skill uses GitHub's async merge API (`PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge-async`, then poll the returned UUID). It supports stacked PRs and merge queues. Docs: https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request-asynchronously

package/plugins/vulnerability-remediation/skills/github/SKILL.md

@@ -5,6 +5,10 @@ triggers:
 - github
 ---
 
+## Connection selection
+
+Use authenticated GitHub MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the token and direct API instructions below only when GitHub MCP tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with
 the GitHub API.
 
@@ -37,6 +41,29 @@ git remote -v && git branch # to find the current org, repo and branch
 git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
 ```
 
+## Merging Pull Requests (async merge API)
+
+IMPORTANT:
+Only merge if the user asks you to, without ambiguity.
+
+GitHub released an async merge API in October 2026; it is now the
+recommended way to merge PRs programmatically, and the only merge API that supports stacked PRs. It can also add a PR to a merge queue.
+Prefer it over `PUT .../pulls/{n}/merge` and the GraphQL `mergePullRequest` mutation.
+A GitHub MCP merge tool may still use the older synchronous endpoint; for stacked PRs or merge queues, use the calls below.
+Docs: https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request-asynchronously
+
+1. Request the merge (`merge_action`: `default` uses the merge queue if the branch has one, else merges directly; or `direct_merge` / `merge_queue`). `merge_method`, `commit_title` and `commit_message` apply only to direct merges:
+```bash
+gh api -X PUT repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/merge-async -f merge_method=squash -f sha=<HEAD_SHA>
+```
+2. A `202` returns `details.uuid`; poll it every few seconds until `status` is no longer `pending`:
+```bash
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/merge-async/<UUID>
+```
+
+Final `status` is `merged`, `enqueued` (added to the merge queue, NOT merged yet), or `failed` (see `details.message`).
+A `200` on the PUT means the PR is already merged or queued; a `409` means a merge request is already pending (its UUID is returned).
+
 ## Handling Review Comments
 
 - Critically evaluate each review comment before acting on it. Not all feedback is worth implementing:

package/plugins/vulnerability-remediation/skills/github/scripts/agent_conversation.py

@@ -32,6 +32,11 @@ _CLOUD_START_GRACE_SECONDS = 10 * 60
 # How long to wait for a paused conversation's sandbox to come back up.
 _CLOUD_RESUME_TIMEOUT_SECONDS = 120
 _CLOUD_POLL_SECONDS = 3
+# How many times a matched delivery whose conversation ended in ERROR is sent
+# again. The delivery key never changes for a stable subject, so without a
+# retry its work is stranded; without a bound, a conversation that fails the
+# same way every time would be re-run on every scan.
+_MAX_ERROR_RETRIES = 2
 
 
 def _register_tools() -> None:
@@ -204,14 +209,23 @@ class AgentConversationDispatcher:
 
         same_delivery = record.get("delivery") == delivery
         same_head = bool(head) and record.get("head") == head
+        # Error retries count against one delivery; a new delivery starts over.
+        error_retries = int(record.get("error_retries") or 0) if same_delivery else 0
+        can_retry = error_retries < _MAX_ERROR_RETRIES
 
         if self._cloud:
             disposition, conversation_id = self._deliver_cloud(
-                record, conversation_id, subject, prompt, same_delivery, same_head
+                record,
+                conversation_id,
+                subject,
+                prompt,
+                same_delivery,
+                same_head,
+                can_retry,
             )
         else:
             disposition = self._deliver_local(
-                conversation_id, prompt, same_delivery, same_head
+                conversation_id, prompt, same_delivery, same_head, can_retry
             )
 
         if disposition in ("deduplicated", "in_progress"):
@@ -228,6 +242,10 @@ class AgentConversationDispatcher:
         }
         if disposition == "created" and self._cloud:
             new_record["started_at"] = time.time()
+        if disposition == "retried":
+            error_retries += 1
+        if error_retries:
+            new_record["error_retries"] = error_retries
         _kv_request(state_key, "PUT", new_record)
         return {
             "disposition": disposition,
@@ -235,7 +253,14 @@ class AgentConversationDispatcher:
         }
 
     def _deliver_cloud(
-        self, record, conversation_id, subject, prompt, same_delivery, same_head
+        self,
+        record,
+        conversation_id,
+        subject,
+        prompt,
+        same_delivery,
+        same_head,
+        can_retry,
     ):
         """Deliver through the OpenHands API; return the disposition and the id.
 
@@ -272,11 +297,21 @@ class AgentConversationDispatcher:
             if status in ("idle", "paused"):
                 self._cloud.run(conversation)
                 return "resumed", current_id
+            if status == "error" and can_retry:
+                # The delivery matched but its conversation died before the work
+                # finished, so send the revision again rather than strand it.
+                # The API reports an execution status only while the sandbox
+                # runs, so an errored conversation whose sandbox was already
+                # paused is not seen here and keeps reporting deduplicated.
+                self._cloud.send(conversation, prompt)
+                return "retried", current_id
             return "deduplicated", current_id
         self._cloud.send(conversation, prompt)
         return "resumed", current_id
 
-    def _deliver_local(self, conversation_id, prompt, same_delivery, same_head) -> str:
+    def _deliver_local(
+        self, conversation_id, prompt, same_delivery, same_head, can_retry
+    ) -> str:
         if self._workspace is None:
             raise RuntimeError("AgentConversationDispatcher must be used as a context")
 
@@ -321,6 +356,18 @@ class AgentConversationDispatcher:
                     ):
                         conversation.update_secrets(self._secrets)
                         conversation.run(blocking=False)
+                    elif (
+                        conversation.state.execution_status
+                        == ConversationExecutionStatus.ERROR
+                        and can_retry
+                    ):
+                        # The delivery matched but its conversation died before
+                        # the work finished, so send the revision again rather
+                        # than strand it.
+                        conversation.update_secrets(self._secrets)
+                        conversation.send_message(prompt)
+                        conversation.run(blocking=False)
+                        disposition = "retried"
                     else:
                         disposition = "deduplicated"
                 else:

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.27.0"
+version = "0.28.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 dependencies = [

package/python/openhands_extensions/_version.py

@@ -18,7 +18,7 @@ from importlib.metadata import PackageNotFoundError, version
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
 #: release-please only rewrites a semver found on the annotated line itself, so
 #: the annotation must stay on the assignment; on its own line it is a no-op.
-_FALLBACK_VERSION = "0.27.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.28.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")