@openhands/extensions 0.22.1 → 0.24.0

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

@@ -0,0 +1,151 @@
+"""Choose one code-aware, currently available maintainer for a reviewed PR."""
+
+from urllib.error import HTTPError
+from urllib.parse import urlencode
+
+_DECISIVE_REVIEW_STATES = {"APPROVED", "CHANGES_REQUESTED"}
+_MAX_PATHS = 8
+_COMMITS_PER_PATH = 10
+
+
+class HandoffConfigurationError(ValueError):
+    """The configured roster cannot produce a GitHub review request."""
+
+
+def parse_maintainers(value):
+    """Normalize a comma-separated catalog value or a JSON-style list."""
+    if isinstance(value, str):
+        value = value.split(",")
+    result = []
+    seen = set()
+    for item in value or []:
+        login = str(item).strip()
+        key = login.lower()
+        if login and key not in seen:
+            seen.add(key)
+            result.append(login)
+    return result
+
+
+def _reviewer_states(reviews, head_sha=None):
+    standing = {}
+    for review in reviews:
+        if head_sha is not None and review.get("commit_id") != head_sha:
+            continue
+        state = (review.get("state") or "").upper()
+        login = (review.get("user") or {}).get("login", "").lower()
+        if not login:
+            continue
+        if state == "DISMISSED":
+            standing.pop(login, None)
+        elif state in _DECISIVE_REVIEW_STATES:
+            standing[login] = state
+    return standing
+
+
+def _path_scores(repository, pr_number, base_ref, candidates):
+    scores = dict.fromkeys(candidates, 0)
+    files = repository.gh_pages(f"/pulls/{pr_number}/files")[:_MAX_PATHS]
+    for changed_file in files:
+        path = changed_file.get("filename")
+        if not path:
+            continue
+        query = urlencode(
+            {"path": path, "sha": base_ref, "per_page": _COMMITS_PER_PATH}
+        )
+        commits = repository.gh("GET", f"/commits?{query}")
+        for rank, commit in enumerate(commits[:_COMMITS_PER_PATH]):
+            login = ((commit.get("author") or {}).get("login") or "").lower()
+            if login in scores:
+                scores[login] += _COMMITS_PER_PATH - rank
+    return scores
+
+
+def _open_review_load(repository, owner, owner_type, login):
+    owner_qualifier = "org" if owner_type.lower() == "organization" else "user"
+    response = repository.api(
+        "GET",
+        "/search/issues",
+        params={
+            "q": (
+                f"is:pr is:open {owner_qualifier}:{owner} "
+                f"review-requested:{login}"
+            ),
+            "per_page": 1,
+        },
+    )
+    return int(response.get("total_count", 0))
+
+
+def request_maintainer_review(repository, pr, maintainers):
+    """Ensure one configured maintainer is reviewing *pr*.
+
+    API failures propagate so the scanner can retry without clearing its trigger
+    label. The return value is the existing or newly requested login.
+    """
+    roster = parse_maintainers(maintainers)
+    if not roster:
+        return None
+
+    by_key = {login.lower(): login for login in roster}
+    requested = {
+        (item.get("login") or "").lower() for item in pr.get("requested_reviewers", [])
+    }
+    for login in roster:
+        if login.lower() in requested:
+            return login
+
+    number = pr["number"]
+    head_sha = pr["head"]["sha"]
+    reviews = repository.gh_pages(f"/pulls/{number}/reviews")
+    # A human approval remains useful after a later push unless GitHub dismisses
+    # it or the reviewer subsequently requests changes. Do not ask that person
+    # to review the same PR again merely because the automated review targets a
+    # newer commit.
+    review_states = _reviewer_states(reviews)
+    for login in roster:
+        if review_states.get(login.lower()) == "APPROVED":
+            return login
+
+    standing = _reviewer_states(reviews, head_sha)
+    for login in roster:
+        if login.lower() in standing:
+            return login
+
+    author = ((pr.get("user") or {}).get("login") or "").lower()
+    candidates = [key for key in by_key if key != author]
+    if not candidates:
+        raise HandoffConfigurationError(
+            "No eligible maintainer remains after excluding the PR author"
+        )
+
+    base_ref = (pr.get("base") or {}).get("ref") or "main"
+    scores = _path_scores(repository, number, base_ref, candidates)
+    owner = repository.repository.split("/", 1)[0]
+    owner_type = (
+        (((pr.get("base") or {}).get("repo") or {}).get("owner") or {}).get("type")
+        or "Organization"
+    )
+    loads = {
+        login: _open_review_load(repository, owner, owner_type, by_key[login])
+        for login in candidates
+    }
+    order = {login.lower(): index for index, login in enumerate(roster)}
+    selected_key = min(
+        candidates,
+        key=lambda login: (-scores[login], loads[login], order[login]),
+    )
+    selected = by_key[selected_key]
+    try:
+        repository.gh(
+            "POST",
+            f"/pulls/{number}/requested_reviewers",
+            {"reviewers": [selected]},
+        )
+    except HTTPError as exc:
+        if exc.code == 422:
+            raise HandoffConfigurationError(
+                f"GitHub cannot assign configured maintainer @{selected}"
+            ) from exc
+        raise
+    return selected

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

@@ -1,19 +1,82 @@
-"""Select labeled PR heads and delegate each review to a sandboxed agent."""
+"""Select requested PR heads and delegate each review to a sandboxed agent."""
 
 import json
+import os
+import sys
+from functools import cached_property
+from urllib.parse import quote
 
 import main as workflow
 from agent_conversation import AgentConversationDispatcher
 from github_client import GitHubRepository, run_repositories
+from maintainer_handoff import (
+    HandoffConfigurationError,
+    parse_maintainers,
+    request_maintainer_review,
+)
 
 
 class PullRequestReviewer(GitHubRepository):
     name = "github-pr-reviewer"
 
-    def _prompt(self, pr, label_event):
+    @cached_property
+    def github_login(self):
+        return self.api("GET", "/user")["login"]
+
+    @cached_property
+    def trigger_reviewer(self):
+        return self.config.get("trigger_reviewer", "all-hands-bot").lower()
+
+    @staticmethod
+    def _event_payload():
+        """Return the GitHub webhook payload, or None for a scheduled run."""
+        raw = os.environ.get("AUTOMATION_EVENT_PAYLOAD")
+        if not raw:
+            return None
+        outer = json.loads(raw)
+        payload = (outer.get("event") or {}).get("payload")
+        return payload if isinstance(payload, dict) else None
+
+    def _latest_reviewer_request(self, number):
+        matching = [
+            event
+            for event in self.gh_pages(f"/issues/{number}/events")
+            if event.get("event") == "review_requested"
+            and ((event.get("requested_reviewer") or {}).get("login") or "").lower()
+            == self.trigger_reviewer
+            and event.get("id") is not None
+        ]
+        if not matching:
+            return None
+        return max(
+            matching,
+            key=lambda event: (
+                event.get("created_at") or "",
+                int(event.get("id") or 0),
+            ),
+        )
+
+    def _event_candidate(self, payload):
+        repository = ((payload.get("repository") or {}).get("full_name") or "")
+        if repository.lower() != self.repository.lower():
+            return None
+        pr = payload.get("pull_request")
+        if not isinstance(pr, dict) or pr.get("number") is None:
+            return None
+        action = payload.get("action")
+        if action == "review_requested":
+            requested = (
+                (payload.get("requested_reviewer") or {}).get("login") or ""
+            ).lower()
+            return pr if requested == self.trigger_reviewer else None
+        if action == "submitted":
+            author = ((payload.get("review") or {}).get("user") or {}).get("login")
+            return pr if (author or "").lower() == self.trigger_reviewer else None
+        return None
+
+    def _prompt(self, pr, trigger, label=None):
         number = pr["number"]
         sha = pr["head"]["sha"]
-        label = self.config.get("trigger_label", workflow.TRIGGER_LABEL)
         token = self.token_name
         workspace = (
             "The workspace contains an empty Git repository. Before fetching, run "
@@ -28,9 +91,31 @@ class PullRequestReviewer(GitHubRepository):
             self.repository,
             pr,
             sha,
-            label_event,
+            trigger,
             workspace_instructions=workspace,
             github_token_secret=token,
+            trigger_description=(
+                None
+                if label
+                else (
+                    f"latest review request for "
+                    f"`{self.trigger_reviewer}` "
+                    f"event {trigger.get('id', '?')} at "
+                    f"{trigger.get('created_at', '?')}"
+                )
+            ),
+        )
+        moved_head_instruction = (
+            f"leave `{label}` in place so the new head is reviewed"
+            if label
+            else "publish no review; the new head requires another reviewer request"
+        )
+        trigger_completion = (
+            f"Leave the `{label}` label in place after GitHub accepts the review. "
+            "The deterministic scanner removes it"
+            if label
+            else "Do not change review requests after GitHub accepts the review. "
+            "The deterministic event handler completes the request"
         )
         return (
             prompt + "\n\nAcceptance reporting:\n"
@@ -38,36 +123,140 @@ class PullRequestReviewer(GitHubRepository):
             "the repository's appropriate focused tests in the workspace. Do not "
             "modify tracked files.\n"
             f"- Re-read {self.repository} PR #{number} immediately before reporting. "
-            f"If its head is no longer `{sha}`, publish no status and leave `{label}` "
-            "in place so the new head is reviewed.\n"
-            "- After the readable native review is accepted by GitHub, set commit "
-            "status `software-factory/review` to success only for an `✅ APPROVED` "
-            "verdict, otherwise failure. Set `software-factory/tests` to success only "
-            "when the relevant checks and tests pass, otherwise failure. Use the exact "
-            f"head `{sha}` for both statuses.\n"
-            f"- After both statuses are visible on that head, remove the `{label}` "
-            "label. Never paste JSON artifacts or full command logs into comments."
+            "Confirm its current body, labels, review threads, and the head's check "
+            "results, and re-read every linked issue's current body and labels: an "
+            "issue's readiness or priority may have changed since an earlier turn. "
+            f"If the head is no longer `{sha}`, {moved_head_instruction}.\n"
+            f"- {trigger_completion} after completing any configured "
+            "human-review handoff. Never paste JSON artifacts or full command logs "
+            "into comments.\n"
+            "- Once GitHub accepts the native review, stop immediately. Do not "
+            "continue inspecting the repository, run more commands, or publish a "
+            "second result."
         )
 
+    def _finish_completed_review(self, pr, trigger, label=None):
+        """Complete an exact-head review, including an optional human handoff."""
+        head_sha = pr["head"]["sha"]
+        triggered_at = trigger.get("created_at") or ""
+        reviews = self.gh_pages(f"/pulls/{pr['number']}/reviews")
+        completed = [
+            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
+        ]
+        if not completed:
+            return False
+        approved = None
+        maintainer_decision = False
+        for review in sorted(
+            completed, key=lambda item: item["submitted_at"], reverse=True
+        ):
+            body = (review.get("body") or "").rstrip()
+            if body.endswith("✅ APPROVED"):
+                approved = True
+                break
+            if body.endswith("🔄 CHANGES REQUESTED"):
+                approved = False
+                break
+            if body.endswith(workflow.MAINTAINER_DECISION_VERDICT):
+                maintainer_decision = True
+                break
+        if approved is None and not maintainer_decision:
+            return False
+        # A scope stop is not an approval: it requests the maintainer decision
+        # the change is missing, through the same handoff as an approval.
+        if approved or maintainer_decision:
+            maintainers = parse_maintainers(self.config.get("maintainers"))
+            if maintainers:
+                try:
+                    selected = request_maintainer_review(self, pr, maintainers)
+                except HandoffConfigurationError as exc:
+                    self.gh(
+                        "POST",
+                        f"/issues/{pr['number']}/comments",
+                        {
+                            "body": (
+                                "⚠️ **Automated maintainer handoff could not be "
+                                f"completed:** {exc}. Update the automation's "
+                                "maintainer roster, then request another review."
+                                "\n\n_This is an automated configuration check; "
+                                "no AI was used to generate this comment._"
+                            )
+                        },
+                    )
+                    selected = None
+                print(
+                    json.dumps(
+                        {
+                            "repository": self.repository,
+                            "pr": pr["number"],
+                            "human_reviewer": selected,
+                        }
+                    ),
+                    flush=True,
+                )
+        current = self.gh("GET", f"/pulls/{pr['number']}")
+        if current["head"]["sha"] != pr["head"]["sha"]:
+            # Treat this scan as handled so it cannot redeliver the stale head.
+            # Scheduled mode leaves its label in place; event mode requires a
+            # fresh review request for the new head.
+            return True
+        if label:
+            self.gh(
+                "DELETE", f"/issues/{pr['number']}/labels/{quote(label, safe='')}"
+            )
+        return True
+
     def run(self):
         repository_id = self.gh("GET", "")["id"]
         label = self.config.get("trigger_label", workflow.TRIGGER_LABEL)
-        prs = self.gh_pages("/pulls?state=open&sort=updated&direction=asc")
+        payload = self._event_payload()
+        if payload is None:
+            prs = self.gh_pages("/pulls?state=open&sort=updated&direction=asc")
+        else:
+            candidate = self._event_candidate(payload)
+            if candidate and self.github_login.lower() != self.trigger_reviewer:
+                raise RuntimeError(
+                    "The configured GitHub credential must authenticate as "
+                    f"{self.trigger_reviewer} for reviewer-request mode"
+                )
+            prs = [candidate] if candidate else []
+        failures = []
         for candidate in prs:
-            if label not in {item["name"] for item in candidate.get("labels", [])}:
+            event_mode = payload is not None
+            if not event_mode and label not in {
+                item["name"] for item in candidate.get("labels", [])
+            }:
                 continue
             try:
                 pr = self.gh("GET", f"/pulls/{candidate['number']}")
-                event = workflow._latest_trigger_label_event(
-                    self.token, self.repository, pr["number"]
+                trigger = (
+                    self._latest_reviewer_request(pr["number"])
+                    if event_mode
+                    else workflow._latest_trigger_label_event(
+                        self.token, self.repository, pr["number"]
+                    )
                 )
-                if event is None:
+                if trigger is None:
+                    continue
+                trigger_label = None if event_mode else label
+                if self._finish_completed_review(pr, trigger, trigger_label):
+                    continue
+                if event_mode and payload.get("action") == "submitted":
+                    # A submitted review is a completion signal, never a fresh
+                    # trigger. A non-decisive review, or one superseded by a new
+                    # head, must wait for another reviewer request instead of
+                    # dispatching a review the caller never asked for.
                     continue
                 sha = pr["head"]["sha"]
                 result = self.dispatcher.deliver(
                     subject=f"{repository_id}:pr:{pr['number']}",
-                    delivery=f"{event['id']}:{sha}",
-                    prompt=self._prompt(pr, event),
+                    delivery=f"{trigger['id']}:{sha}",
+                    prompt=self._prompt(pr, trigger, trigger_label),
                 )
                 print(
                     json.dumps(
@@ -82,11 +271,19 @@ class PullRequestReviewer(GitHubRepository):
                     flush=True,
                 )
             except Exception as exc:  # noqa: BLE001 - one PR must not block the scan
+                failures.append(candidate.get("number", "?"))
                 print(
                     f"Failed to submit {self.repository} PR "
-                    f"#{candidate.get('number', '?')}: {exc}",
+                    f"#{candidate.get('number', '?')}: "
+                    f"{type(exc).__name__}: {exc}",
+                    file=sys.stderr,
                     flush=True,
                 )
+        if failures:
+            raise RuntimeError(
+                "Reviewer scan failed for PRs: "
+                + ", ".join(f"#{number}" for number in failures)
+            )
 
 
 if __name__ == "__main__":

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

@@ -522,6 +522,91 @@ class TestRepoReviewGuide(unittest.TestCase):
         self.assertIn("CONTRIBUTING.md", prompt)
         self.assertIn("nested `AGENTS.md`", prompt)
 
+    def test_prompt_uses_native_approval_for_a_clean_review(self):
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        self.assertIn("`event: APPROVE`", prompt)
+        self.assertIn("otherwise use `event: COMMENT`", prompt)
+        self.assertIn("Never use `REQUEST_CHANGES`", prompt)
+        self.assertIn("native GitHub review is the only result channel", prompt)
+        self.assertIn("Do not create commit statuses or Checks", prompt)
+        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_refreshing_mutable_github_state(self):
+        """A resumed conversation must not trust an earlier turn's observations."""
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        assert "CURRENT STATE" in prompt
+        for surface in (
+            "still matches the Head SHA",
+            "current PR title and body",
+            "current review comments and threads",
+            "current review requests",
+            "GitHub Actions check results",
+            "body and labels of every linked issue",
+        ):
+            self.assertIn(surface, prompt)
+        # The readiness case from the report: a linked issue gaining a label.
+        self.assertIn("ready-for-dev", prompt)
+
+    def test_prompt_forbids_repeating_an_earlier_observation(self):
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        self.assertIn("fresh review", prompt)
+        self.assertIn("re-established now", prompt)
+        self.assertIn(
+            "never repeat an earlier finding, verdict, or "
+            "label/priority claim",
+            prompt,
+        )
+
+    def test_prompt_refreshes_state_before_the_scope_gate_and_keeps_analysis(self):
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        # The refresh precedes the verdict-shaping steps, while the repository
+        # analysis the conversation already did stays part of the workflow.
+        self.assertLess(prompt.index("CURRENT STATE"), prompt.index("SCOPE GATE"))
+        self.assertLess(prompt.index("CURRENT STATE"), prompt.index("MUST read"))
+        self.assertIn("useful background", prompt)
+        self.assertIn("AGENTS.md", prompt)
+
+    def test_prompt_scope_gate_stops_before_the_technical_review(self):
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        gate = prompt.index("SCOPE GATE")
+        self.assertLess(gate, prompt.index("Inspect the PR discussion"))
+        self.assertLess(gate, prompt.index("Ground every finding"))
+        self.assertIn("before inspecting changed files, reading the diff, or running", prompt)
+        self.assertIn("scope categories and ownership boundaries", prompt)
+        self.assertIn("continue the technical review unchanged", prompt)
+        self.assertIn("move repositories, close, or receive a maintainer decision", prompt)
+
 
 class TestNormalizeRepo(unittest.TestCase):
     """A repository is written down in more than one way, and every API path in

package/skills/github-repo-monitor/scripts/github_client.py

@@ -123,6 +123,10 @@ class GitHubRepository:
             self.token, method, f"/repos/{self.repository}" + path, body=body
         )[0]
 
+    def api(self, method, path, params=None, body=None):
+        """Call a GitHub endpoint that is not scoped to one repository."""
+        return github_request(self.token, method, path, params=params, body=body)[0]
+
     def shell(self, args, cwd=None, timeout=300):
         result = subprocess.run(
             args,