@openhands/extensions 0.24.0 → 0.26.0

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

@@ -2,22 +2,37 @@
 
 import json
 import os
+import time
 from urllib.error import HTTPError
 from urllib.request import Request, urlopen
-from uuid import NAMESPACE_URL, UUID, uuid5
-
-import httpx
-from openhands.sdk import RemoteConversation
-from openhands.sdk.conversation.request import (
-    SendMessageRequest,
-    StartConversationRequest,
-)
-from openhands.sdk.conversation.state import ConversationExecutionStatus
-from openhands.sdk.llm.message import TextContent
-from openhands.sdk.workspace import LocalWorkspace, RemoteWorkspace
+from uuid import NAMESPACE_URL, UUID, uuid4, uuid5
+
+try:
+    import httpx
+    from openhands.sdk import RemoteConversation
+    from openhands.sdk.conversation.request import (
+        SendMessageRequest,
+        StartConversationRequest,
+    )
+    from openhands.sdk.conversation.state import ConversationExecutionStatus
+    from openhands.sdk.llm.message import TextContent
+    from openhands.sdk.workspace import LocalWorkspace, RemoteWorkspace
+except ImportError:
+    # A run on OpenHands Cloud or Enterprise has no SDK on its Python path and
+    # does not need one: CloudConversations speaks the OpenHands API instead.
+    httpx = RemoteConversation = SendMessageRequest = None
+    StartConversationRequest = ConversationExecutionStatus = None
+    TextContent = LocalWorkspace = RemoteWorkspace = None
 
 _CONVERSATION_KEY_PREFIX = "agent-conversation-"
 
+# How long a conversation the OpenHands API was asked to start may take to
+# appear before the start is taken to have failed and is made again.
+_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
+
 
 def _register_tools() -> None:
     """Register tool models needed to deserialize an attached agent."""
@@ -50,19 +65,106 @@ def _kv_request(key: str, method: str, value: dict | None = None) -> dict | None
     return body.get("value") if method == "GET" else body
 
 
+class CloudConversations:
+    """The conversations of a run on OpenHands Cloud or Enterprise.
+
+    Such a run has no Agent Server to attach to. The OpenHands API starts each
+    conversation in a sandbox of its own, which outlives the run's, with the
+    agent profile's model, tools and secrets resolved on the server.
+    """
+
+    def __init__(self) -> None:
+        self.api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+        self.headers = {
+            "Authorization": f"Bearer {os.environ['OPENHANDS_API_KEY']}",
+            "Content-Type": "application/json",
+        }
+
+    def _request(self, method: str, url: str, body=None, headers=None):
+        request = Request(
+            url if url.startswith("http") else f"{self.api}{url}",
+            data=json.dumps(body).encode() if body is not None else None,
+            headers=headers or self.headers,
+            method=method,
+        )
+        with urlopen(request, timeout=90) as response:
+            raw = response.read()
+        return json.loads(raw) if raw.strip() else {}
+
+    def get(self, conversation_id) -> dict | None:
+        """The conversation, or None while the API has no record of it."""
+        found = self._request("GET", f"/api/v1/app-conversations?ids={conversation_id}")
+        return found[0] if found else None
+
+    def start(self, conversation_id, profile_id, title: str, prompt: str) -> None:
+        self._request(
+            "POST",
+            "/api/v1/app-conversations",
+            {
+                "conversation_id": str(conversation_id),
+                "agent_profile_id": str(profile_id),
+                "title": title,
+                "initial_message": _user_message(prompt),
+            },
+        )
+
+    def run(self, conversation: dict) -> None:
+        """Start the next turn of an idle conversation on its own Agent Server."""
+        try:
+            self._request(
+                "POST",
+                f"{conversation['conversation_url']}/run",
+                headers={"X-Session-API-Key": conversation["session_api_key"]},
+            )
+        except HTTPError as exc:
+            if exc.code != 409:  # 409: a turn is already running
+                raise
+
+    def send(self, conversation: dict, prompt: str) -> None:
+        """Send the next turn, waking the conversation's sandbox if it is paused."""
+        conversation_id = conversation["id"]
+        if conversation.get("sandbox_status") != "RUNNING":
+            self._request(
+                "POST", f"/api/v1/sandboxes/{conversation['sandbox_id']}/resume"
+            )
+            deadline = time.monotonic() + _CLOUD_RESUME_TIMEOUT_SECONDS
+            # The execution status is only reported once the sandbox's Agent
+            # Server answers, which is when it can take the message.
+            while not (self.get(conversation_id) or {}).get("execution_status"):
+                if time.monotonic() > deadline:
+                    raise RuntimeError(
+                        f"Conversation {conversation_id} did not resume in time"
+                    )
+                time.sleep(_CLOUD_POLL_SECONDS)
+        self._request(
+            "POST",
+            f"/api/v1/app-conversations/{conversation_id}/send-message",
+            {**_user_message(prompt), "run": True},
+        )
+
+
+def _user_message(text: str) -> dict:
+    return {"role": "user", "content": [{"type": "text", "text": text}]}
+
+
 class AgentConversationDispatcher:
     """Deliver one revision at a time to a stable conversation for each subject."""
 
     def __init__(self) -> None:
-        self.agent_url = os.environ["AGENT_SERVER_URL"]
+        # The automation service hands a run the Agent Server URL only on a
+        # local Agent Canvas; elsewhere conversations go through the OpenHands API.
+        self.agent_url = os.environ.get("AGENT_SERVER_URL")
         self.api_key = os.environ["SESSION_API_KEY"]
         self.profile_id = UUID(os.environ["AUTOMATION_AGENT_PROFILE_ID"])
         payload = json.loads(os.environ["AUTOMATION_EVENT_PAYLOAD"])
         self.automation_id = str(payload["automation_id"])
+        self._cloud = None if self.agent_url else CloudConversations()
         self._workspace: RemoteWorkspace | None = None
         self._secrets = {}
 
     def __enter__(self):
+        if self._cloud:
+            return self
         _register_tools()
         self._workspace = RemoteWorkspace(
             host=self.agent_url,
@@ -76,17 +178,107 @@ class AgentConversationDispatcher:
         return self
 
     def __exit__(self, *args):
+        if self._cloud:
+            return None
         assert self._workspace is not None
         return self._workspace.__exit__(*args)
 
-    def deliver(self, subject: str, delivery: str, prompt: str) -> dict[str, str]:
+    def deliver(
+        self, subject: str, delivery: str, prompt: str, head: str = ""
+    ) -> dict[str, str]:
+        """Deliver one revision of `subject`, deduping a repeated head.
+
+        `delivery` keys the revision: a second trigger for the same revision
+        reuses the conversation without a new turn, and a changed head becomes a
+        new delivery. `head` is the revision's commit, and it is the guard that
+        matters when two triggers name the same commit - a re-request after the
+        bot's own handoff, say - because a delivery key that only counts triggers
+        would send a second turn and publish a second review of identical code.
+        A conversation already running for this head is reported `in_progress`
+        and left alone, whatever the new delivery says. Callers with no revision
+        identity leave `head` empty and keep the delivery-key-only behavior.
+        """
         conversation_id = uuid5(NAMESPACE_URL, f"{self.automation_id}:{subject}")
         state_key = f"{_CONVERSATION_KEY_PREFIX}{conversation_id}"
         record = _kv_request(state_key, "GET") or {}
-        if self._workspace is None:
-            raise RuntimeError("AgentConversationDispatcher must be used as a context")
 
         same_delivery = record.get("delivery") == delivery
+        same_head = bool(head) and record.get("head") == head
+
+        if self._cloud:
+            disposition, conversation_id = self._deliver_cloud(
+                record, conversation_id, subject, prompt, same_delivery, same_head
+            )
+        else:
+            disposition = self._deliver_local(
+                conversation_id, prompt, same_delivery, same_head
+            )
+
+        if disposition in ("deduplicated", "in_progress"):
+            return {
+                "disposition": disposition,
+                "conversation_id": str(conversation_id),
+            }
+
+        new_record = {
+            "subject": subject,
+            "conversation_id": str(conversation_id),
+            "delivery": delivery,
+            "head": head or record.get("head") or "",
+        }
+        if disposition == "created" and self._cloud:
+            new_record["started_at"] = time.time()
+        _kv_request(state_key, "PUT", new_record)
+        return {
+            "disposition": disposition,
+            "conversation_id": str(conversation_id),
+        }
+
+    def _deliver_cloud(
+        self, record, conversation_id, subject, prompt, same_delivery, same_head
+    ):
+        """Deliver through the OpenHands API; return the disposition and the id.
+
+        The id is the subject's stable one until its conversation can no longer
+        take a turn - its start never completed, or its sandbox is gone - and a
+        fresh id from then on, because the API does not start an id twice. The
+        KV record carries whichever is current.
+        """
+        current_id = record.get("conversation_id") or conversation_id
+        conversation = self._cloud.get(current_id)
+
+        if conversation is None:
+            started = time.time() - float(record.get("started_at") or 0)
+            if started < _CLOUD_START_GRACE_SECONDS:
+                # The API is still bringing the subject's conversation up and
+                # does not list it yet. Starting another would run two for one
+                # subject, so even a new revision waits: the record is left as
+                # it is and the next trigger delivers it.
+                return "in_progress", current_id
+        elif conversation.get("sandbox_status") in ("ERROR", "MISSING"):
+            if same_delivery:
+                return "deduplicated", current_id
+            conversation = None
+
+        if conversation is None:
+            new_id = uuid4() if record else conversation_id
+            self._cloud.start(new_id, self.profile_id, subject, prompt)
+            return "created", new_id
+
+        status = conversation.get("execution_status")
+        if status == "running" and (same_delivery or same_head):
+            return "in_progress", current_id
+        if same_delivery:
+            if status in ("idle", "paused"):
+                self._cloud.run(conversation)
+                return "resumed", 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:
+        if self._workspace is None:
+            raise RuntimeError("AgentConversationDispatcher must be used as a context")
 
         try:
             conversation = RemoteConversation.attach(
@@ -112,14 +304,18 @@ class AgentConversationDispatcher:
             disposition = "created"
         try:
             if disposition == "resumed":
-                if same_delivery:
-                    if (
-                        conversation.state.execution_status
-                        == ConversationExecutionStatus.RUNNING
-                    ):
-                        conversation.update_secrets(self._secrets)
-                        disposition = "in_progress"
-                    elif conversation.state.execution_status in (
+                running = (
+                    conversation.state.execution_status
+                    == ConversationExecutionStatus.RUNNING
+                )
+                if running and (same_delivery or same_head):
+                    # A turn is already running for this very revision, so a new
+                    # trigger is not new work: report the live conversation
+                    # rather than starting a second pass beside it.
+                    conversation.update_secrets(self._secrets)
+                    disposition = "in_progress"
+                elif same_delivery:
+                    if conversation.state.execution_status in (
                         ConversationExecutionStatus.IDLE,
                         ConversationExecutionStatus.PAUSED,
                     ):
@@ -128,28 +324,12 @@ class AgentConversationDispatcher:
                     else:
                         disposition = "deduplicated"
                 else:
+                    # A changed head, or a head a human clarified since, is new
+                    # work on the same subject: reuse the conversation and send
+                    # the revision as its next turn.
                     conversation.update_secrets(self._secrets)
                     conversation.send_message(prompt)
                     conversation.run(blocking=False)
         finally:
             conversation.close()
-
-        if disposition in ("deduplicated", "in_progress"):
-            return {
-                "disposition": disposition,
-                "conversation_id": str(conversation_id),
-            }
-
-        _kv_request(
-            state_key,
-            "PUT",
-            {
-                "subject": subject,
-                "conversation_id": str(conversation_id),
-                "delivery": delivery,
-            },
-        )
-        return {
-            "disposition": disposition,
-            "conversation_id": str(conversation_id),
-        }
+        return disposition

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

@@ -51,6 +51,12 @@ REVIEW_STYLE_INSTRUCTIONS = ""
 # than relying on the spawned agent's skill activation. Set to "" to disable.
 REPO_REVIEW_GUIDE_PATH = ".agents/skills/custom-codereview-guide.md"
 DEFAULT_OPENHANDS_URL = "http://localhost:8000"
+# The most new review conversations one scheduled scan may start, counted across
+# every configured repository rather than per repository. The scheduled scan
+# drains outstanding reviewer requests in oldest-request order, so a small bound
+# keeps a first scan over a large backlog from starting an agent for every
+# eligible pull request at once.
+MAX_NEW_PER_RUN = 2
 
 # A review that ends with this marker is a scope stop: the reviewer found the
 # change out of scope, or needing a product/architecture decision, before the
@@ -69,6 +75,7 @@ _CONFIG_TYPES: dict[str, type] = {
     "review_tone": str,
     "review_style_instructions": str,
     "repo_review_guide_path": str,
+    "max_new_per_run": int,
     "openhands_url": str,
 }
 
@@ -95,7 +102,11 @@ def load_config(directory: Path | None = None) -> dict:
         if key not in raw:
             continue
         value = raw[key]
-        if not isinstance(value, expected):
+        # bool is an int in Python, so an unguarded int check would accept
+        # `"max_new_per_run": true` and then start `True` conversations.
+        if not isinstance(value, expected) or (
+            expected is int and isinstance(value, bool)
+        ):
             raise SystemExit(
                 f"{CONFIG_FILENAME}: {key} must be {expected.__name__}, "
                 f"got {type(value).__name__}"
@@ -106,6 +117,10 @@ def load_config(directory: Path | None = None) -> dict:
             raise SystemExit(
                 f'{CONFIG_FILENAME}: repos must be a non-empty list of "owner/repo" strings'
             )
+        if key == "max_new_per_run" and value < 1:
+            raise SystemExit(
+                f"{CONFIG_FILENAME}: max_new_per_run must be at least 1"
+            )
         config[key] = value
     return config
 
@@ -150,6 +165,7 @@ TRIGGER_LABEL = _CONFIG.get("trigger_label", TRIGGER_LABEL)
 REVIEW_TONE = _CONFIG.get("review_tone", REVIEW_TONE)
 REVIEW_STYLE_INSTRUCTIONS = _CONFIG.get("review_style_instructions", REVIEW_STYLE_INSTRUCTIONS)
 REPO_REVIEW_GUIDE_PATH = _CONFIG.get("repo_review_guide_path", REPO_REVIEW_GUIDE_PATH)
+MAX_NEW_PER_RUN = _CONFIG.get("max_new_per_run", MAX_NEW_PER_RUN)
 DEFAULT_OPENHANDS_URL = _CONFIG.get("openhands_url", DEFAULT_OPENHANDS_URL)
 
 DONE_DEBOUNCE = 15