@openhands/extensions 0.24.0 → 0.26.0

package/skills/github-issue-triage/scripts/github_client.py

@@ -12,24 +12,62 @@ from urllib.parse import parse_qsl, urlencode, urlsplit
 from urllib.request import Request, urlopen
 
 
+# The secret name of the GitHub token an OpenHands Cloud or Enterprise user's
+# connected GitHub integration provides: how this run's sandbox serves it, and
+# how a conversation sees it in its environment.
+CLOUD_GITHUB_TOKEN_SECRET = "github_token"
+CLOUD_GITHUB_TOKEN_ENV = "GITHUB_TOKEN"
+
+
+def is_cloud_run() -> bool:
+    """Whether this run is on OpenHands Cloud or Enterprise.
+
+    The automation service hands a run the Agent Server URL only on a local
+    Agent Canvas; elsewhere the run talks to the OpenHands API instead.
+    """
+    return bool(os.environ.get("OPENHANDS_CLOUD_API_URL")) and not os.environ.get(
+        "AGENT_SERVER_URL"
+    )
+
+
+def _load_cloud_secret(name: str) -> str | None:
+    """Read one named secret of this run's sandbox from the OpenHands API."""
+    api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+    request = Request(
+        f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}",
+        headers={"X-Session-API-Key": os.environ["SESSION_API_KEY"]},
+    )
+    try:
+        with urlopen(request, timeout=90) as response:
+            return response.read().decode().strip()
+    except HTTPError as exc:
+        if exc.code == 404:
+            return None
+        raise
+
+
 def _load_secret(name: str) -> str:
-    """Read one named secret from the environment or configured Agent Server."""
+    """Read one named secret from the environment, or from the configured Agent
+    Server on a local run and the OpenHands API on a cloud one."""
     value = os.environ.get(name)
     if value:
         return value
 
-    from openhands.sdk.workspace import RemoteWorkspace
+    if is_cloud_run():
+        value = _load_cloud_secret(name)
+    else:
+        from openhands.sdk.workspace import RemoteWorkspace
 
-    workspace = RemoteWorkspace(
-        host=os.environ["AGENT_SERVER_URL"],
-        api_key=os.environ["SESSION_API_KEY"],
-        working_dir=os.environ.get("WORKSPACE_BASE", "/workspace"),
-    )
-    try:
-        secret = workspace.get_secrets([name]).get(name)
-        value = secret.get_value() if secret else None
-    finally:
-        workspace.reset_client()
+        workspace = RemoteWorkspace(
+            host=os.environ["AGENT_SERVER_URL"],
+            api_key=os.environ["SESSION_API_KEY"],
+            working_dir=os.environ.get("WORKSPACE_BASE", "/workspace"),
+        )
+        try:
+            secret = workspace.get_secrets([name]).get(name)
+            value = secret.get_value() if secret else None
+        finally:
+            workspace.reset_client()
     if not value:
         raise ValueError(f"The GitHub credential {name} is unavailable")
     return value
@@ -95,11 +133,22 @@ class GitHubRepository:
                 "Expected the environment variable containing the GitHub token"
             )
         self.token_name = github_token_secret
-        self.token = _load_secret(github_token_secret)
+        try:
+            self.token = _load_secret(github_token_secret)
+        except ValueError:
+            if not is_cloud_run():
+                raise
+            # No secret is saved under that name, so use the user's connected
+            # GitHub integration, under the name a conversation sees it by.
+            self.token = _load_cloud_secret(CLOUD_GITHUB_TOKEN_SECRET)
+            if not self.token:
+                raise
+            self.token_name = CLOUD_GITHUB_TOKEN_ENV
         self.conversation = conversation
         self.conversation_id = str(conversation.id) if conversation else None
         self.dispatcher = dispatcher
-        self.workspace = Path(os.environ["WORKSPACE_BASE"])
+        # A cloud run is not given a workspace base; its sandbox has /workspace.
+        self.workspace = Path(os.environ.get("WORKSPACE_BASE", "/workspace"))
         self.project = self.workspace
         self.evidence = self.workspace / "evidence"
         self.evidence.mkdir(exist_ok=True)
@@ -111,10 +160,13 @@ class GitHubRepository:
 
     @property
     def github_instructions(self):
+        # A cloud conversation runs in a sandbox of its own, so this run's
+        # workspace path means nothing to it.
+        where = "your working directory" if is_cloud_run() else self.project
         return (
             f"Use `GH_TOKEN=${self.token_name} gh api` for GitHub requests. "
             "Never print the credential value. "
-            f"Only {self.repository} is in scope. Work in {self.project}. "
+            f"Only {self.repository} is in scope. Work in {where}. "
             "Do not modify the automation bundle or its configuration."
         )
 
@@ -165,6 +217,122 @@ class GitHubRepository:
             result.setdefault(item["context"], item["state"])
         return result
 
+    def check_runs(self, sha):
+        """Return every check run GitHub reported for one commit SHA.
+
+        Reading check runs needs no branch-protection or ruleset access, so this
+        is the head-eligibility signal the automation's own token can always
+        see. The endpoint answers with an object rather than a list, so it
+        paginates through ``gh`` instead of ``gh_pages``.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/commits/{sha}/check-runs?per_page=100&page={page}"
+            )
+            batch = data.get("check_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub check-run pagination exceeded limit")
+
+    def required_check_contexts(self, number):
+        """Return the status contexts GitHub marks required on one pull request.
+
+        `isRequired` is the merge-policy source of truth and is PR-scoped, so it
+        is correct for a stacked PR whose symbolic base branch carries no branch
+        rules of its own. It is a field on each context in the head's status
+        check rollup and takes the pull request number, so a single GraphQL query
+        answers with the required check runs and any required commit statuses,
+        each already attributed to the exact head. Only contexts GitHub itself
+        reports as required are returned, so an optional workflow that fails
+        before creating any check run is not present.
+        """
+        owner, name = self.repository.split("/", 1)
+        query = (
+            "query($owner:String!,$name:String!,$number:Int!){"
+            "repository(owner:$owner,name:$name){"
+            "pullRequest(number:$number){"
+            "commits(last:1){"
+            "nodes{"
+            "commit{"
+            "statusCheckRollup{"
+            "contexts(first:100){"
+            "pageInfo{hasNextPage}"
+            "nodes{"
+            "__typename"
+            " ... on CheckRun{name isRequired(pullRequestNumber:$number)}"
+            " ... on StatusContext{context isRequired(pullRequestNumber:$number)}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+        )
+        data = self.api(
+            "POST",
+            "/graphql",
+            body={
+                "query": query,
+                "variables": {"owner": owner, "name": name, "number": number},
+            },
+        )
+        if data.get("errors"):
+            raise RuntimeError(
+                f"GitHub required-check query failed: {data['errors'][0].get('message')}"
+            )
+        nodes = (
+            (((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {})
+            .get("commits", {})
+            .get("nodes")
+        ) or []
+        contexts = (
+            ((nodes[0].get("commit") or {}).get("statusCheckRollup") or {}).get(
+                "contexts", {}
+            )
+            if nodes
+            else {}
+        )
+        if (contexts.get("pageInfo") or {}).get("hasNextPage"):
+            raise RuntimeError(
+                "GitHub required-check rollup exceeds one page; the required "
+                "set may be incomplete"
+            )
+        return [
+            {
+                "name": node.get("name") or node.get("context"),
+                "kind": node.get("__typename"),
+            }
+            for node in (contexts.get("nodes") or [])
+            if node.get("isRequired") and (node.get("name") or node.get("context"))
+        ]
+
+    def workflow_runs(self, sha):
+        """Return every Actions workflow run GitHub reported for one commit SHA.
+
+        A workflow that fails before any job starts - a workflow-level error, or
+        a `pull_request` run whose jobs never materialize - still records a
+        failed check suite, but it contributes no check runs, so the commit's
+        check-run rollup and `gh pr checks` both report success. Reading the
+        workflow runs directly is the only way the gate can see that failure.
+        Like the check-run endpoint this answers with an object, so it paginates
+        manually.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/actions/runs?head_sha={sha}&per_page=100&page={page}"
+            )
+            batch = data.get("workflow_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub workflow-run pagination exceeded limit")
+
     def completed_dependency(self, number):
         if number in self._completed_dependencies:
             return self._completed_dependencies[number]

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

@@ -57,12 +57,22 @@ gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/reviews --input /tmp/revie
 | Parameter | Description |
 |-----------|-------------|
 | `commit_id` | Commit SHA to comment on (use `git rev-parse HEAD`) |
-| `event` | `COMMENT`, `APPROVE`, or `REQUEST_CHANGES` |
+| `event` | `APPROVE`, `COMMENT`, or `REQUEST_CHANGES` (see below) |
 | `path` | File path as shown in the diff |
 | `line` | Line number in the NEW version (right side of diff) |
 | `side` | `RIGHT` for new/added lines, `LEFT` for deleted lines |
 | `body` | Comment text with priority label |
 
+### Choosing the `event` Value
+
+| Event | When to use |
+|-------|-------------|
+| `APPROVE` | No issues found, or only 🟡 suggestions that are non-blocking |
+| `COMMENT` | You have 🟠 Important feedback but it's not a hard blocker |
+| `REQUEST_CHANGES` | There are 🔴 Critical issues that **must** be fixed before merge |
+
+**Default to `APPROVE`** when the code is correct and merge-ready. Use `COMMENT` or `REQUEST_CHANGES` only when there are actionable issues that warrant it.
+
 ### Multi-Line Comments
 
 For comments spanning multiple lines, add `start_line` to specify the range:
@@ -184,4 +194,4 @@ curl -X POST \
 5. Do NOT post comments for code that is acceptable — only comment when action is needed
 6. Use suggestion syntax for concrete code changes, but only after verifying the resulting code matches your description (see "How Suggestions Actually Work")
 7. Keep the review body brief (details go in inline comments)
-8. If no issues: post a short approval message with no inline comments
+8. If no issues: use `"event": "APPROVE"` with a short approval message and no inline comments

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

@@ -12,7 +12,43 @@ This skill is activated by:
 ## Features
 
 - Reviews PRs on demand from a GitHub reviewer request or label event
+- Gates each scheduled review on the current head's GitHub-required checks
+  before starting an agent, read through the `isRequired` signal, so an optional
+  workflow that fails cannot block a mergeable head: a completed `failure`,
+  `cancelled`, or `timed_out` required check blocks the review, and a `queued`,
+  `in_progress`, or not-yet-reported required check exits with a clear
+  waiting-on-checks outcome instead of holding a slot. If the required-check
+  signal is unavailable the gate falls back to every current-head check run and
+  workflow run, including a workflow that fails before creating any check run
+- Dispatches an explicit `all-hands-bot` review request even when required CI is
+  red or pending; the CI gate applies to scheduled discovery
+- Ignores checks and workflow runs recorded for an obsolete head, so a stale
+  failure cannot block the push that fixed it
+- Explicit reviewer requests include draft PRs in both event mode and scheduled
+  scans; drafts without a request or trigger label remain excluded
+- Resumes an outstanding reviewer request on the next scheduled scan once the
+  requested head's checks are green, so a request that arrives during CI is not
+  lost; the explicit-request event path is kept for event-only deployments
+- Reviews open, non-draft PRs that nobody requested on a scheduled scan once
+  their current head is green and carries no review yet, keyed by
+  repository/PR/head so a repeat scan never duplicates a conversation or review
+  and a changed head becomes eligible again
+- Examines the whole unrequested backlog on each scheduled scan, while the
+  global `max_new_per_run` quota limits only newly created review conversations;
+  blocked or pending heads consume no launch slot
+- Posts no managed gate comment for an unrequested PR that is merely red or
+  pending - the comment answers an explicit request, so a scan over a large
+  backlog cannot storm the PRs with comments
+- Names the retry the deployment actually has in the waiting comment: a
+  scheduled scan where a cron trigger exists, and removing and re-requesting the
+  bot where only the event trigger does
+- Rewrites its own managed gate comment in place when the retry wording changes,
+  so switching a deployment from the event trigger to a cron scan updates the
+  outstanding-request explanation instead of leaving the old instruction
 - Watches several repositories from a single automation, each with its own state
+- Bounds a scheduled scan to a small, configurable number of new review
+  conversations across all repositories (default 2), draining the oldest
+  outstanding reviewer requests first and reaching the rest on later scans
 - Processes each review request or label application idempotently
 - Supports re-review by requesting the bot again or re-applying the label. Each
   explicit request refreshes mutable GitHub state (head, PR body, reviews,

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

@@ -25,9 +25,101 @@ once per label event, and publishes the AI review to GitHub.
 Windows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in `references/windows.md`.
 
 The automation script is deterministic: PR discovery, label-event tracking,
-state persistence, stale-result suppression, the repository checkout, and its
-removal are all handled in Python. The LLM is invoked only for the review
-itself.
+head eligibility, state persistence, stale-result suppression, the repository
+checkout, and its removal are all handled in Python. The LLM is invoked only for
+the review itself.
+
+Before any review conversation is created, a scheduled scan evaluates the
+current head's GitHub-required checks, read through the GraphQL `isRequired`
+signal for the pull request. That signal is the merge policy's own source of
+truth and is pull-request-scoped, so it stays correct for a stacked PR whose
+symbolic base branch carries no branch rules of its own:
+
+- Only checks GitHub reports as required decide the scheduled gate. An optional
+  workflow that fails - including one that fails before creating any check run -
+  does not block a head whose required checks pass.
+- A completed required run on the exact head whose conclusion is `failure`,
+  `cancelled`, or `timed_out` blocks the review. Any other unrecognized
+  conclusion fails closed as a block rather than silently approving.
+- A completed required run whose conclusion is `success`, `neutral`, or
+  `skipped` does not block. A required `commit status` context is classified
+  alongside required check runs.
+- A `queued` or `in_progress` required run on the exact head, and a required
+  context that has not reported a current-head check run at all, make the run
+  exit with a **waiting on checks** outcome. Unfulfilled is never approval. The
+  worker does not hold a slot polling; the next scheduled scan or explicit
+  review request retries.
+- When the required-check signal cannot be read or is empty, the gate falls back
+  to every current-head check run and workflow run, so a red head still blocks.
+  In that fallback, workflow runs are read as well as check runs, because a
+  workflow can fail before creating any check run - a workflow-level error, or a
+  `pull_request` run whose jobs never start. Such a run leaves a failed check
+  suite with no check runs under it, so the commit's check-run rollup and
+  `gh pr checks` both report success and only the workflow run reveals the red
+  CI. A workflow run whose check suite already reported check runs is left to
+  those runs, so a workflow is never counted twice.
+- A scheduled scan considers the trigger label **and** every open PR, including drafts,
+  that still holds an outstanding `all-hands-bot` review request. That is what
+  resumes a request made while CI was running: the request is keyed by its own
+  `review_requested` event, so repeated scans reuse one conversation and one
+  review instead of creating duplicates, and a PR whose request was answered or
+  withdrawn simply drops out of `requested_reviewers`.
+- The scheduled scan also reviews open, non-draft PRs that **nobody requested**
+  and that carry no trigger label, once their current head has no completed
+  review by this account. That is what keeps reviewing PRs after the outstanding
+  requests are exhausted. The delivery key is the stable
+  `scan:{repository}:{number}:{head}`, so repeated scans reuse one conversation
+  and one native review, and a changed head becomes eligible again under its new
+  SHA.
+- Each scheduled scan classifies the **whole open backlog**, including
+  unrequested PRs. Blocked, pending, draft, or already-reviewed heads therefore
+  cannot hide an eligible head behind an inspection window. The separate
+  `max_new_per_run` quota limits only newly created review conversations, not the
+  number of PRs inspected; explicit requests and trigger labels retain priority
+  when eligible candidates are drained.
+- A gate stop on an **unrequested** head posts no managed comment. A PR nobody
+  asked about that is merely red or pending is simply skipped without starting an
+  agent, which is what keeps a scan over a large backlog from posting a gate
+  comment on every PR. The managed comment is the answer to an explicit request,
+  so a requested or labeled head that is red or pending still gets its
+  explanation.
+- Workflow runs are read as well as check runs, because a workflow can fail
+  before creating any check run - a workflow-level error, or a `pull_request`
+  run whose jobs never start. Such a run leaves a failed check suite with no
+  check runs under it, so the commit's check-run rollup and `gh pr checks` both
+  report success and only the workflow run reveals the red CI. A workflow run
+  whose check suite already reported check runs is left to those runs, so a
+  workflow is never counted twice.
+- Runs attributed to any other (obsolete) head SHA are ignored, so a stale
+  failure cannot block the push that fixed it. This applies to workflow runs
+  too.
+- Only the latest run of each logical check or workflow counts. A logical check
+  is its name plus the reporting app identity, and a logical workflow is its
+  name plus workflow ID. The latest is chosen by the run ID (the reliable
+  creation sequence) with the start time as a tie-break, so a re-run that fixed
+  a check supersedes its earlier failure on the same SHA while a newer queued or
+  in-progress re-run supersedes an earlier success and makes the head wait.
+  Ordering by the run ID keeps a run whose start time is still absent in its
+  true creation position in both directions.
+
+An explicit `all-hands-bot` review request is the intake-policy exception: the
+caller asked for that head by name, so the request dispatches even when required
+CI is red or pending, and the gate leaves no explanatory comment. Draft, scope,
+exact-head, and delivery-deduplication safeguards still apply. A blocked or
+waiting scheduled stop consumes no trigger: once the head's required checks are
+non-blocking, the scheduled scan, or a new `all-hands-bot` review request,
+starts the normal review.
+
+The gate needs no configured list of check names. When it stops a review it
+leaves one concise explanation on the PR, identified by a hidden marker carrying
+the head SHA and gate category, so a later run for a different head updates that
+comment instead of posting another. Only a marker this reviewer account authored
+counts as its own comment; every other PR comment is untrusted and can neither
+suppress the explanation nor be edited. If the repository's own workflow already
+posted a deterministic remediation comment that names the same current-head
+checks, the gate adds nothing; a disclosure about some other check does not
+suppress it. The gate applies to scheduled label scans; an explicit
+`all-hands-bot` review request bypasses it by design.
 
 Each explicit review request - a re-applied trigger label, or a new reviewer
 request in event mode - is a fresh review. The conversation for a PR is reused,
@@ -39,6 +131,52 @@ verdict, or label/priority claim that state no longer supports. Repository
 analysis the conversation already did, such as reading `AGENTS.md`, stays
 useful and is not repeated.
 
+The waiting and blocked explanations name the retry the deployment actually has.
+A scheduled run proves a scan is configured, so it says the next scan will
+retry. An event-only run does not, so it tells the reader to remove the
+outstanding `all-hands-bot` request and request `all-hands-bot` again instead of
+promising a scan that does not exist: GitHub will not accept a second request
+while the first is still outstanding.
+
+The gate leaves only one explanation per head. When the same head keeps the same
+hidden marker but the retry wording changes -- an event-only comment on a head
+whose automation is later switched to a cron scan -- the scheduled run rewrites
+that managed comment in place, so the comment always names the retry that is
+actually deployed, and an unchanged body is left untouched.
+
+## Bounded intake per scheduled scan
+
+A scheduled scan drains outstanding reviewer requests fairly, but starting an
+agent for every eligible pull request at once would overload the deployment, so
+the scan starts at most `MAX_NEW_PER_RUN` new review conversations, counted
+**across every configured repository** rather than per repository. The default
+is `2`, and the rendered `config.json` overrides it through the
+`max_new_per_run` key that `github-issue-to-pr` and `gitlab-issue-to-mr` already
+use.
+
+- Eligible candidates are ordered deterministically: an explicit `all-hands-bot`
+  request (or a trigger label) is ordered before an unrequested PR, then by the
+  oldest `all-hands-bot` `review_requested` event for a requested PR or the PR's
+  own creation time (oldest first) for an unrequested one, then by repository,
+  then by pull-request number, so the oldest work drains first and a later scan
+  reaches the remainder.
+- The bound counts the conversations a scan **starts**. A delivery that only
+  deduplicates or reports an already-running conversation reuses a runtime and
+  consumes no slot, so repeated scans make progress on the backlog instead of
+  re-spending the bound on work already in flight.
+- Reaching the bound never cuts the scan short. The scan still evaluates the
+  exact-head checks of the remaining candidates, reconciles completed reviews,
+  and runs the maintainer handoff. A candidate whose checks are pending or
+  failing starts no conversation and consumes no slot, so it cannot block a later
+  green candidate. Only an explicit request or a trigger label gets a waiting or
+  blocked gate comment; an unrequested head that is merely red or pending is
+  skipped silently.
+- A dispatch that raises is reported and does not consume a slot or abort the
+  scan, so the candidates behind it are still considered.
+- The explicit `review_requested` event path and the trigger-label scan are
+  unchanged: an explicit request still starts its conversation immediately, and
+  only the scheduled scan's new conversations are bounded.
+
 The review prompt starts with a scope gate: using the repository's own guidance
 (its scope categories and ownership boundaries, not a list of individual PR
 numbers), the reviewer decides whether the change belongs in this repository
@@ -176,7 +314,7 @@ Record as `CRON_SCHEDULE`.
 
 ### Step 6 - Generate the automation script
 
-Read `scripts/main.py` from this skill's directory. Apply exactly six constant
+Read `scripts/main.py` from this skill's directory. Apply exactly seven constant
 substitutions near the top of the file:
 
 > The script also reads a `config.json` shipped beside it, if there is one, over
@@ -192,6 +330,7 @@ substitutions near the top of the file:
 | `REVIEW_TONE = "thorough"` | `REVIEW_TONE = "{review_tone}"` |
 | `REVIEW_STYLE_INSTRUCTIONS = ""` | `REVIEW_STYLE_INSTRUCTIONS = "{style_instructions}"` |
 | `REPO_REVIEW_GUIDE_PATH = ".agents/skills/custom-codereview-guide.md"` | leave unchanged to auto-load a repo review guide at this path, or set to `""` to disable |
+| `MAX_NEW_PER_RUN = 2` | leave unchanged to bound a scheduled scan to two new review conversations across all repositories, or raise it if the deployment can hold more agents at once |
 | `DEFAULT_OPENHANDS_URL = "http://localhost:8000"` | leave unchanged unless the user has a preference |
 
 Use a safe string writer such as `json.dumps(value)` when inserting user-provided
@@ -348,6 +487,10 @@ The completion callback fires once for the whole run.
 | 404 on repo access | Repo name wrong or no access | Re-check the entry in `REPOS` and the token's permissions |
 | One repository is skipped, others work | That repository failed its access check | Read the `=== owner/repo ===` block in the run log |
 | Same PR not reviewed after new commits | Label event was already processed | Remove and re-apply the trigger label |
+| Review paused with a failing-check comment | A current-head required check reported `failure`, `cancelled`, or `timed_out` | Fix the named checks and push; the review starts on the new head, or request `all-hands-bot` to review immediately |
+| Review reported waiting on checks | A current-head required check is `queued` or `in_progress`, or has not reported yet | No action; a later scan or a new review request retries |
+| Optional workflow failed but no review was paused | The failed workflow is not required, so the required-only scheduled gate ignored it | No action; only GitHub-required checks gate scheduled discovery |
+| Only a few reviews start on a large backlog | The per-scan `max_new_per_run` bound (default 2) reached | No action; later scans drain the remaining oldest eligible PRs, or raise `max_new_per_run` if the deployment can hold more agents |
 | 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 |
 | Review arrives as a plain comment, not a review | Publishing failed, so the script posted the text as a fallback | Check that the token has Pull requests: Read and Write |