@openhands/extensions 0.26.0 → 0.28.0

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

@@ -61,6 +61,11 @@ This skill is activated by:
   checkout when the review ends, so nothing accumulates between runs
 - Publishes a real pull request review, with inline comments where a finding
   maps to a changed line, and verifies on GitHub that it landed
+- Requires live evidence from the real app before approving a user-visible UI
+  change when the repository's guidance demands it: unit tests, CSS-token
+  assertions, generated mockups, and reconstructed captures cannot substitute.
+  Missing evidence yields a COMMENT review that names the gap, so no approval
+  and no maintainer handoff
 - Posts acknowledgement comments with AI disclosure
 - Configurable review tone and polling schedule
 - Optional human handoff after an exact-head approval. The scanner ranks the

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

@@ -189,6 +189,18 @@ handler recognizes the verdict and requests one configured maintainer through th
 same handoff used after an approval. An in-scope change continues the existing
 review unchanged.
 
+Before approving a change to user-visible UI behavior, the prompt requires live
+evidence from a real running application when the repository's guidance demands
+it: a screenshot, screen recording, or equivalent capture of the running app
+that exercises the production-facing path. Unit tests, CSS-token or contract
+assertions, generated mockups, and reconstructed captures may support the review
+but cannot substitute for that evidence. When the required evidence is missing,
+the reviewer publishes one `event: COMMENT` review naming exactly what is
+missing and ends with `🔄 CHANGES REQUESTED`, so approval is withheld and the
+deterministic maintainer handoff does not fire. Non-UI changes keep the existing
+requirement of the real command and its observed output, with tests insufficient
+as sole proof.
+
 The script prepares each review's workspace before the agent starts: the pull
 request's head commit is downloaded as a tarball and extracted to a directory of
 its own, which becomes the conversation's working directory. The agent is told

package/skills/github-pr-reviewer/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/skills/github-pr-reviewer/scripts/main.py

@@ -847,7 +847,21 @@ def _build_review_prompt(
         "credential, configuration, or external state stayed unchanged. Do not add speculative or "
         "out-of-scope notes: every blocking or non-blocking observation must identify demonstrated "
         "behavior on the current head and explain why it matters to the merge decision.\n"
-        f"7. Publish one review with `POST /repos/{repo}/pulls/{number}/reviews`, using "
+        "7. LIVE EVIDENCE GATE - if the change alters user-visible UI behavior and the repository "
+        "guidance requires live evidence for it, you must not approve unless that evidence is from a "
+        "real running application and exercises the production-facing path. Live evidence means a "
+        "screenshot, screen recording, or equivalent capture of the running app, not the source, a "
+        "diff, or a description of what it should render. Unit tests, CSS-token or contract "
+        "assertions, generated mockups, and reconstructed or hand-built captures may support the "
+        "review but never substitute for the required live evidence. When the repository guidance "
+        "requires that evidence and only non-live evidence is available, do not approve: publish "
+        "exactly one review with `event: COMMENT` that names exactly which live evidence is missing, "
+        "and end its body with the verdict on its own line: `🔄 CHANGES REQUESTED`. State the gap as "
+        "a blocking finding, not a note, and never let a passing test suite stand in for the missing "
+        "capture. A UI change that does supply compliant live evidence, and any non-UI change "
+        "(backend, API, CLI, script) that follows the existing requirement of the real command and "
+        "its observed output, continues to step 8.\n"
+        f"8. Publish one review with `POST /repos/{repo}/pulls/{number}/reviews`, using "
         "`commit_id` equal to the Head SHA above. Use `event: APPROVE` when there are "
         "no material findings; otherwise use `event: COMMENT`. Never use "
         "`REQUEST_CHANGES`.\n"
@@ -858,19 +872,19 @@ def _build_review_prompt(
         "   Put the overall assessment in `body`, and each line-specific finding in the `comments` "
         "array with `path`, `line`, `side: RIGHT`, and `body`.\n"
         "   Only create inline comments for actionable findings; do not open praise or nitpick threads.\n"
-        "8. If a finding cannot be attached to a changed line, put it in the review body instead. "
+        "9. If a finding cannot be attached to a changed line, put it in the review body instead. "
         "If the API rejects the inline positions, retry with every finding in the body and no `comments` array. "
         "If GitHub forbids the configured bot from approving its own PR, retry the clean review with "
         "`event: COMMENT` and keep the approved verdict.\n"
-        "9. Begin the review body with this disclosure: "
+        "10. Begin the review body with this disclosure: "
         "`_This review was posted by an AI agent (OpenHands)._`\n"
-        "10. End the review body with a verdict on its own line: either `✅ APPROVED` "
+        "11. End the review body with a verdict on its own line: either `✅ APPROVED` "
         "or `🔄 CHANGES REQUESTED`.\n"
-        "11. If there are no material issues, still publish a review saying so, with the "
+        "12. If there are no material issues, still publish a review saying so, with the "
         "disclosure and the verdict.\n"
         f"\nReview instructions:\n{tone}{extra}{guide_section}\n\n"
         "After GitHub accepts the review, output exactly `GITHUB_REVIEW_POSTED`. "
-        "If publishing still fails after the fallback in step 8, output the complete review text "
+        "If publishing still fails after the fallback in step 9, output the complete review text "
         "so it can be posted as a comment instead."
     )
 

package/skills/github-pr-reviewer/scripts/worker.py

@@ -27,6 +27,11 @@ from maintainer_handoff import (
 # every current-head check and workflow run, so a red head still blocks.
 CHECK_GATE_MARKER = "<!-- openhands-review-gate:"
 NON_BLOCKING_CHECK_CONCLUSIONS = frozenset({"success", "neutral", "skipped"})
+# GitHub parks a fork head's workflow runs at this conclusion until a maintainer
+# approves them. Such a run is waiting on a person, not failing, so the gate
+# lists it as waiting with this note and its explanation asks for the approval.
+AWAITING_APPROVAL_CONCLUSION = "action_required"
+AWAITING_APPROVAL_NOTE = " (awaiting maintainer approval)"
 # The gate is deterministic; this disclosure is what tells a reader no model ran.
 WORKFLOW_DISCLOSURE = "no AI was used to generate this comment"
 
@@ -98,7 +103,8 @@ class ReviewIntake:
                     flush=True,
                 )
                 continue
-            if result["disposition"] == "created":
+            # A retried conversation runs again, so it uses a slot like a new one.
+            if result["disposition"] in ("created", "retried"):
                 self._started += 1
         if failures:
             raise RuntimeError(
@@ -283,7 +289,7 @@ class PullRequestReviewer(GitHubRepository):
             f"second result.{self_review_note}"
         )
 
-    def _finish_completed_review(self, pr, trigger, label=None):
+    def _finish_completed_review(self, pr, trigger, label=None, submitted_review=None):
         """Complete an exact-head review, including an optional human handoff.
 
         `trigger` is the event the current work is keyed on. It is None for an
@@ -291,7 +297,11 @@ class PullRequestReviewer(GitHubRepository):
         is the whole key, so any submitted review by this account on the current
         head is the completion of that work. That is what lets an unrequested
         review the scan started be reconciled and handed off on a later scan
-        instead of being restarted.
+        instead of being restarted. `submitted_review` is the review a
+        `submitted` delivery reports. It can predate the latest
+        `review_requested` event, so it is found by id rather than by the
+        trigger window; this account's later reviews of the head still count, so
+        a newer verdict supersedes it. A dismissed review completes nothing.
         """
         head_sha = pr["head"]["sha"]
         if trigger is not None:
@@ -299,14 +309,35 @@ class PullRequestReviewer(GitHubRepository):
         else:
             triggered_at = ""
         reviews = self.gh_pages(f"/pulls/{pr['number']}/reviews")
-        completed = [
+        mine = [
             review
             for review in reviews
             if review.get("commit_id") == head_sha
             and ((review.get("user") or {}).get("login") or "").lower()
             == self.github_login.lower()
-            and (review.get("submitted_at") or "") > triggered_at
+            and (review.get("state") or "").upper() != "DISMISSED"
         ]
+        if submitted_review and submitted_review.get("id") is not None:
+            reported = next(
+                (review for review in mine if review.get("id") == submitted_review["id"]),
+                None,
+            )
+            reported_at = (reported or {}).get("submitted_at") or ""
+            completed = (
+                []
+                if reported is None
+                else [
+                    review
+                    for review in mine
+                    if (review.get("submitted_at") or "") >= reported_at
+                ]
+            )
+        else:
+            completed = [
+                review
+                for review in mine
+                if (review.get("submitted_at") or "") > triggered_at
+            ]
         if not completed:
             return False
         approved = None
@@ -482,16 +513,19 @@ class PullRequestReviewer(GitHubRepository):
 
         A completed run whose conclusion is neither blocking nor explicitly
         non-blocking fails closed, so an unknown conclusion cannot silently
-        approve a PR. A run that has not completed means waiting, never
-        approval.
+        approve a PR. A run that has not completed, or one awaiting a
+        maintainer's approval to run, means waiting, never approval.
         """
         blocking, pending = [], []
         for run in reporters:
             name = run.get("name") or "unnamed check"
             status = (run.get("status") or "").lower()
+            conclusion = (run.get("conclusion") or "").lower()
             if status != "completed":
                 pending.append(name)
-            elif (run.get("conclusion") or "").lower() in NON_BLOCKING_CHECK_CONCLUSIONS:
+            elif conclusion == AWAITING_APPROVAL_CONCLUSION:
+                pending.append(f"{name}{AWAITING_APPROVAL_NOTE}")
+            elif conclusion in NON_BLOCKING_CHECK_CONCLUSIONS:
                 continue
             else:
                 blocking.append(name)
@@ -650,10 +684,10 @@ class PullRequestReviewer(GitHubRepository):
         short = sha[:12]
         listed = "\n".join(f"- `{name}`" for name in names)
         if state == "blocked":
-            heading = "### ⚠️ Review paused: current-head checks failed"
+            heading = "### ⚠️ Review paused: current-head checks did not pass"
             lead = (
-                f"The current head `{short}` has failing checks, so no review "
-                "conversation was started:"
+                f"The current head `{short}` has checks that did not pass, so no "
+                "review conversation was started:"
             )
             action = (
                 "Fix the checks above and push. The scheduled scan then starts "
@@ -665,6 +699,25 @@ class PullRequestReviewer(GitHubRepository):
                 "second request while the first is still outstanding. The review "
                 "starts on the updated head."
             )
+        elif any(name.endswith(AWAITING_APPROVAL_NOTE) for name in names):
+            heading = "### ⏳ Review waiting on workflow approval"
+            lead = (
+                f"The current head `{short}` has workflow runs that GitHub holds "
+                "until a maintainer approves them, or checks that have not "
+                "finished, so no review conversation was started:"
+            )
+            action = (
+                "A maintainer needs to approve the workflow runs marked above. "
+                "The scheduled scan retries once every check on the head reports "
+                "a conclusion."
+                if scheduled
+                else "A maintainer needs to approve the workflow runs marked "
+                "above. Once every check on the head reports a conclusion, "
+                f"remove the outstanding `{self.trigger_reviewer}` request and "
+                f"request `{self.trigger_reviewer}` again: GitHub will not "
+                "accept a second request while the first is still outstanding. "
+                "That starts the review."
+            )
         else:
             heading = "### ⏳ Review waiting on checks"
             lead = (
@@ -858,6 +911,11 @@ class PullRequestReviewer(GitHubRepository):
         for candidate in prs:
             try:
                 pr = self.gh("GET", f"/pulls/{candidate['number']}")
+                submitted_review = (
+                    payload.get("review")
+                    if event_mode and payload.get("action") == "submitted"
+                    else None
+                )
                 has_label = label in {
                     item["name"] for item in pr.get("labels", [])
                 }
@@ -894,7 +952,11 @@ class PullRequestReviewer(GitHubRepository):
                     delivery_key = self._unrequested_head(pr)
                     unrequested_candidate = True
                 if trigger is None and delivery_key is None:
-                    continue
+                    # A submitted review is its own completion signal: its
+                    # request can predate the issue-event window, and that
+                    # review must still be reconciled.
+                    if submitted_review is None:
+                        continue
                 # A head this account already reviewed, with no clarifying
                 # comment since, is done: another conversation would publish a
                 # second review of identical code. This must come before the
@@ -918,7 +980,7 @@ class PullRequestReviewer(GitHubRepository):
                         ),
                         flush=True,
                     )
-                    if trigger is not None:
+                    if trigger is not None or submitted_review is not None:
                         # Reconcile the completed review (clearing the label and
                         # running the maintainer handoff) where the review is
                         # this trigger's result. When it predates the trigger -
@@ -927,7 +989,7 @@ class PullRequestReviewer(GitHubRepository):
                         # otherwise the label stays and every later scan re-reads
                         # this head and re-logs with no effect.
                         if not self._finish_completed_review(
-                            pr, trigger, trigger_label
+                            pr, trigger, trigger_label, submitted_review
                         ) and trigger_label:
                             self.gh(
                                 "DELETE",
@@ -936,7 +998,7 @@ class PullRequestReviewer(GitHubRepository):
                             )
                     continue
                 if delivery_key is None and self._finish_completed_review(
-                    pr, trigger, trigger_label
+                    pr, trigger, trigger_label, submitted_review
                 ):
                     continue
                 if event_mode and payload.get("action") == "submitted":

package/skills/github-pr-reviewer/tests/test_main.py

@@ -538,6 +538,29 @@ class TestRepoReviewGuide(unittest.TestCase):
         self.assertIn("Do not add speculative or out-of-scope notes", prompt)
         self.assertIn("forbids the configured bot from approving its own PR", prompt)
 
+    def test_prompt_requires_live_ui_evidence_before_approval(self):
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        # The gate sits after the finding-quality rules and before the review is
+        # published, so a missing capture is a blocking finding, not a note.
+        gate = prompt.index("LIVE EVIDENCE GATE")
+        self.assertLess(prompt.index("Ground every finding"), gate)
+        self.assertLess(gate, prompt.index("Publish one review"))
+        self.assertIn("user-visible UI behavior", prompt)
+        self.assertIn("real running application", prompt)
+        self.assertIn("production-facing path", prompt)
+        self.assertIn("CSS-token", prompt)
+        self.assertIn("generated mockups", prompt)
+        self.assertIn("reconstructed", prompt)
+        self.assertIn("never substitute for the required live evidence", prompt)
+        self.assertIn("names exactly which live evidence is missing", prompt)
+        self.assertIn("`🔄 CHANGES REQUESTED`", prompt)
+
     def test_prompt_requires_refreshing_mutable_github_state(self):
         """A resumed conversation must not trust an earlier turn's observations."""
         prompt = main._build_review_prompt(

package/skills/gitlab/README.md

@@ -11,6 +11,8 @@ This skill is activated by the following keywords:
 
 ## Details
 
+Use authenticated GitLab 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 `GITLAB_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, `GITLAB_TOKEN`, which allows you to interact with
 the GitLab API.
 
@@ -34,4 +36,4 @@ 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
-```
+```

package/skills/gitlab/SKILL.md

@@ -5,6 +5,10 @@ triggers:
 - gitlab
 ---
 
+## Connection selection
+
+Use authenticated GitLab 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 GitLab MCP tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `GITLAB_TOKEN`, which allows you to interact with
 the GitLab API.