@openhands/extensions 0.25.0 → 0.27.0

package/skills/github/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/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-agents-md-maintainer/README.md

@@ -24,6 +24,13 @@ This skill is activated by:
 - Opens draft pull requests by default, titled `docs: update AGENTS.md` or
   `docs: add AGENTS.md`
 
+On OpenHands Cloud and Enterprise the conversation is started through the
+OpenHands API in a sandbox of its own, with the user's own settings. The agent
+clones the repository itself, and a conversation that ends without a pull
+request is recorded as unfinished: the script has no clone to open one from. A
+user with no `GITHUB_PERSONAL_ACCESS_TOKEN` secret is served the token of their
+connected GitHub integration instead.
+
 ## What the agent is asked to do
 
 Read the repository - layout, the build, test, lint and format commands as they

package/skills/github-agents-md-maintainer/SKILL.md

@@ -167,17 +167,24 @@ python3 -m py_compile /tmp/agents-md-build/main.py && echo "Syntax OK"
 
 ### Step 8 - Package and upload
 
-Determine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`
-block in your system context:
-- **OPENHANDS_HOST**: the Automation backend `url_from_agent`
-- **Auth**: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`
+Set `OPENHANDS_HOST` and `AUTH_HEADER` for the commands below:
+- **OpenHands Cloud or Enterprise** - a `<HOST>` value is in your system prompt:
+  use it as `OPENHANDS_HOST`, with `AUTH_HEADER="Authorization: Bearer $OPENHANDS_API_KEY"`
+- **Local Agent Canvas** - an **Automation backend** is listed in the
+  `<RUNTIME_SERVICES>` block of your system context: use its `url_from_agent` as
+  `OPENHANDS_HOST`, with `AUTH_HEADER="X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY"`
+
+On OpenHands Cloud or Enterprise each run starts in a fresh sandbox, so the
+automation keeps its state in the KV store: check that `kvStore` is listed under
+`features` in `GET ${OPENHANDS_HOST}/api/automation/v1/capabilities` before
+deploying.
 
 ```bash
 tar -czf /tmp/agents-md.tar.gz -C /tmp/agents-md-build .
 
 TARBALL_PATH=$(curl -s -X POST \
   "${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-agents-md-maintainer" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "$AUTH_HEADER" \
   -H "Content-Type: application/gzip" \
   --data-binary @/tmp/agents-md.tar.gz \
   | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")
@@ -189,7 +196,7 @@ echo "Uploaded: $TARBALL_PATH"
 
 ```bash
 curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "$AUTH_HEADER" \
   -H "Content-Type: application/json" \
   -d "{
     \"name\": \"AGENTS.md Maintainer: {repo_summary}\",

package/skills/github-agents-md-maintainer/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."
         )