@openhands/extensions 0.25.0 → 0.27.0

package/skills/github-issue-triage/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-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."
         )
 

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

@@ -24,6 +24,8 @@ This skill is activated by:
   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
@@ -31,10 +33,9 @@ This skill is activated by:
   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 a bounded, rotating window of that unrequested backlog per scan
-  (10 PRs per repository), remembering its position in the Automation KV store so
-  the next scan resumes past it; explicit requests and trigger labels are always
-  examined, never skipped behind the window
+- 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

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

@@ -58,7 +58,7 @@ symbolic base branch carries no branch rules of its own:
   `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, non-draft PR
+- 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
@@ -71,21 +71,12 @@ symbolic base branch carries no branch rules of its own:
   `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.
-- The unrequested part of a scan is a **bounded, rotating window**, not the whole
-  backlog. Classifying one unrequested head costs a review read plus the
-  exact-head check and workflow reads, so examining every open PR in one scan
-  spent the run's API budget in the largest repository and announced every red or
-  pending head. A scan examines at most `SCAN_WINDOW` (10) unrequested PRs per
-  repository and stores where the window ended in the automation service's own
-  KV store, under a per-repository `review-scan:{owner}__{repo}` key, so the next
-  scan resumes past that point and the backlog is covered fairly over several
-  scans. The window wraps at the end of the backlog. When the KV store is not
-  available (a local run) the position is kept in memory, so the scan still
-  rotates within the run.
-- An explicit `all-hands-bot` review request or a trigger label is **never**
-  subject to the window: every explicit candidate is examined on every scan,
-  whatever the stored position is, so a request is not delayed behind the
-  rotation.
+- 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
@@ -499,7 +490,7 @@ The completion callback fires once for the whole run.
 | 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 requests and the bounded rotating window of unrequested PRs, or raise `max_new_per_run` if the deployment can hold more agents |
+| 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 |

package/skills/github-pr-reviewer/references/state-schema.md

@@ -18,21 +18,6 @@ store under the key `state:{owner}__{repo}` — for example
 `AUTOMATION_KV_TOKEN` is injected into the run environment. Each automation has
 its own isolated namespace.
 
-The scheduled worker (`worker.py`) uses the same store for one more document, the
-**unrequested-scan cursor**, under the key `review-scan:{owner}__{repo}`:
-
-```json
-{ "cursor": 20 }
-```
-
-`cursor` is the position in the repository's unrequested-PR backlog at which the
-next scheduled scan's bounded window starts. Each scan examines at most
-`SCAN_WINDOW` (10) unrequested PRs from that position, then writes the position
-after the window, so successive scans rotate through the whole backlog instead of
-reading one pull request per open PR. A cursor past the end wraps to the start.
-This document is separate from `main.py`'s per-repository review state; a missing
-or unreadable cursor simply starts the window at the beginning.
-
 **Fallback (local/dev):** When the KV store is not available, the state is
 written to a local JSON file at: