@openhands/extensions 0.25.0 → 0.27.0

package/skills/jira-issue-to-pr/scripts/setup_webhook.py

@@ -0,0 +1,290 @@
+"""
+Set up the Jira Cloud webhook of an event-based Jira automation.
+
+Registers a custom webhook source in OpenHands and the matching admin webhook in
+Jira Cloud. The two share a signing secret that is generated or rotated here and is
+never printed, so it does not enter the conversation. A webhook that already exists
+on both sides is updated in place and keeps its secret.
+
+Usage:
+  python3 setup_webhook.py apply  --jira-base-url URL --jira-email EMAIL --openhands-host HOST
+  python3 setup_webhook.py delete --jira-base-url URL --jira-email EMAIL --openhands-host HOST
+
+  --jira-token-env NAME  environment variable holding the Jira API token (default JIRA_CLOUD_KEY)
+  --source NAME          OpenHands webhook source (default "jira")
+  --label LABEL          Jira label the webhook is limited to (default "create-pr")
+  --jql JQL              JQL filter to use instead of the label
+  --name NAME            name of the webhook in Jira
+  --dry-run              apply only: report what would change, change nothing
+  --rotate-secret        apply only: give an existing pair a new signing secret; without
+                         it a webhook that exists on both sides keeps the one it has
+
+Environment:
+  OPENHANDS_API_KEY      API key for the OpenHands deployment
+  <--jira-token-env>     API token of an account with the Administer Jira permission
+
+Exit codes: 0 done, 1 failed, 2 bad arguments or environment, 3 the Jira account is
+not an administrator (set the webhook up by hand instead).
+"""
+import argparse, base64, hashlib, hmac, json, os, secrets, sys, urllib.error, urllib.parse, urllib.request
+
+JIRA_EVENTS = ["jira:issue_created", "jira:issue_updated"]
+# What Jira Cloud sends: the event name in `webhookEvent`, the signature in
+# `X-Hub-Signature` as "sha256=<hex HMAC-SHA256 of the body>".
+OPENHANDS_WEBHOOK = {
+    "event_key_expr": "webhookEvent",
+    "signature_header": "X-Hub-Signature",
+    "signature_scheme": "hmac_sha256_hex",
+}
+# No automation listens for this event name, so the signed check starts no run.
+CHECK_EVENT = "openhands:setup_check"
+
+_secret = ""
+
+
+class Failure(Exception):
+    def __init__(self, message, code=1):
+        super().__init__(message)
+        self.code = code
+
+
+def _redact(text):
+    return text.replace(_secret, "***") if _secret else text
+
+
+def _call(method, url, headers, body=None):
+    """Return (status, parsed JSON or text). An HTTP error status is returned, not raised."""
+    data = json.dumps(body).encode() if body is not None else None
+    if data is not None:
+        headers = {**headers, "Content-Type": "application/json"}
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            status, raw = resp.status, resp.read()
+    except urllib.error.HTTPError as exc:
+        status, raw = exc.code, exc.read()
+    except urllib.error.URLError as exc:
+        raise Failure(f"{method} {url} failed: {exc.reason}") from exc
+    text = raw.decode("utf-8", errors="replace")
+    try:
+        return status, json.loads(text) if text.strip() else {}
+    except ValueError:
+        return status, text
+
+
+def _expect(what, status, body, ok=(200, 201, 204)):
+    if status not in ok:
+        raise Failure(f"{what} failed: HTTP {status} {_redact(str(body))[:300]}")
+    return body
+
+
+class OpenHands:
+    def __init__(self, host, api_key, source):
+        self.base = host.rstrip("/") + "/api/automation/v1/webhooks"
+        self.headers = {"Authorization": f"Bearer {api_key}"}
+        self.source = source
+
+    def find(self):
+        status, body = _call("GET", f"{self.base}?limit=100", self.headers)
+        webhooks = _expect("Listing OpenHands webhooks", status, body).get("webhooks", [])
+        return next((w for w in webhooks if w.get("source") == self.source), None)
+
+    def create(self, secret):
+        payload = {"name": "Jira Cloud", "source": self.source, "webhook_secret": secret,
+                   **OPENHANDS_WEBHOOK}
+        status, body = _call("POST", self.base, self.headers, payload)
+        return _expect("Registering the OpenHands webhook", status, body)
+
+    def align(self, webhook):
+        """Give an existing webhook the settings Jira needs; return it."""
+        wanted = {**OPENHANDS_WEBHOOK, "enabled": True}
+        if all(webhook.get(k) == v for k, v in wanted.items()):
+            return webhook
+        status, body = _call("PATCH", f"{self.base}/{webhook['id']}", self.headers, wanted)
+        return _expect("Updating the OpenHands webhook", status, body)
+
+    def rotate(self, webhook):
+        status, body = _call("POST", f"{self.base}/{webhook['id']}/rotate-secret", self.headers)
+        if status != 200 or not isinstance(body, dict) or not body.get("webhook_secret"):
+            raise Failure(f"Rotating the OpenHands webhook secret failed: HTTP {status}")
+        return body["webhook_secret"]
+
+
+class Jira:
+    def __init__(self, base_url, email, token):
+        self.site = base_url.rstrip("/")
+        self.base = self.site + "/rest/webhooks/1.0/webhook"
+        basic = base64.b64encode(f"{email}:{token}".encode()).decode()
+        self.headers = {"Authorization": f"Basic {basic}", "Accept": "application/json"}
+
+    def require_admin(self):
+        status, body = _call(
+            "GET", f"{self.site}/rest/api/3/mypermissions?permissions=ADMINISTER", self.headers
+        )
+        if status in (401, 403):
+            raise Failure(f"Jira rejected the credentials (HTTP {status}). Check the site URL, "
+                          "the account email and the API token.")
+        body = _expect("Reading Jira permissions", status, body)
+        try:
+            permission = body["permissions"]["ADMINISTER"]
+        except (KeyError, TypeError) as exc:
+            raise Failure("Reading Jira permissions returned an unexpected response.") from exc
+        if not permission.get("havePermission"):
+            raise Failure("This Jira account does not have the Administer Jira permission, "
+                          "which registering a webhook requires. Ask a Jira administrator to "
+                          "create the webhook by hand.", code=3)
+
+    def find(self, url):
+        """The webhooks delivering to `url`; none when no URL is known yet."""
+        status, body = _call("GET", self.base, self.headers)
+        hooks = _expect("Listing Jira webhooks", status, body)
+        if not isinstance(hooks, list):
+            raise Failure("Listing Jira webhooks returned an unexpected response.")
+        return [h for h in hooks if url and h.get("url") == url]
+
+    @staticmethod
+    def _id(hook):
+        return str(hook["self"]).rstrip("/").rsplit("/", 1)[-1]
+
+    def save(self, existing, payload):
+        if existing:
+            hook_id = self._id(existing[0])
+            status, body = _call("PUT", f"{self.base}/{hook_id}", self.headers, payload)
+            _expect("Updating the Jira webhook", status, body)
+            return hook_id, "updated"
+        status, body = _call("POST", self.base, self.headers, payload)
+        return self._id(_expect("Creating the Jira webhook", status, body)), "created"
+
+    def delete(self, hook):
+        status, body = _call("DELETE", f"{self.base}/{self._id(hook)}", self.headers)
+        _expect("Deleting the Jira webhook", status, body)
+        return self._id(hook)
+
+
+def _signed_check(url, secret):
+    """Deliver one request signed the way Jira signs, to prove the pair works."""
+    body = json.dumps({"webhookEvent": CHECK_EVENT}).encode()
+    signature = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+    req = urllib.request.Request(url, data=body, method="POST", headers={
+        "Content-Type": "application/json", "X-Hub-Signature": f"sha256={signature}"})
+    try:
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            return "ok" if resp.status == 200 else f"HTTP {resp.status}"
+    except urllib.error.HTTPError as exc:
+        return f"HTTP {exc.code} {_redact(exc.read().decode('utf-8', errors='replace'))[:200]}"
+    except urllib.error.URLError as exc:
+        return f"unreachable: {exc.reason}"
+
+
+def apply(args, openhands, jira):
+    global _secret
+    jira.require_admin()
+    jql = args.jql or 'labels = "{}"'.format(args.label.replace("\\", "\\\\").replace('"', '\\"'))
+    name = args.name or f"OpenHands: issues labelled {args.label}"
+    webhook = openhands.find()
+    # Asked before anything is written: it proves Jira serves this account the
+    # webhook API, and says whether Jira already holds this webhook's secret.
+    in_jira = jira.find(webhook["webhook_url"] if webhook else None)
+    # A pair that exists on both sides keeps its secret, so a failure half way
+    # through cannot leave Jira signing with one OpenHands no longer accepts.
+    new_secret = args.rotate_secret or not (webhook and in_jira)
+
+    if args.dry_run:
+        if not webhook:
+            openhands_plan = f"register source '{args.source}'"
+        elif new_secret:
+            openhands_plan = "rotate the secret of the existing one"
+        else:
+            openhands_plan = "keep the existing one and its secret"
+        return {
+            "dry_run": True,
+            "openhands_webhook": openhands_plan,
+            "jira_webhook": "update the existing one" if in_jira else "create",
+            "jira": {"site": jira.site, "name": name, "events": JIRA_EVENTS, "jql": jql,
+                     "url": webhook["webhook_url"] if webhook else "(assigned on registration)"},
+        }
+
+    payload = {"name": name, "events": JIRA_EVENTS, "excludeBody": False,
+               "filters": {"issue-related-events-section": jql}}
+    if webhook:
+        webhook = openhands.align(webhook)
+        if new_secret:
+            _secret = openhands.rotate(webhook)
+    else:
+        _secret = secrets.token_urlsafe(32)
+        webhook = openhands.create(_secret)
+    url = webhook["webhook_url"]
+    if not url.startswith("https://"):
+        raise Failure(f"Jira only delivers to HTTPS URLs, and this deployment's is {url}")
+    if new_secret:
+        # Left out otherwise: Jira keeps the secret of a webhook updated without one.
+        payload["secret"] = _secret
+
+    try:
+        hook_id, action = jira.save(in_jira, {**payload, "url": url})
+    except Failure as exc:
+        if not new_secret:
+            raise
+        raise Failure(f"{exc} OpenHands now holds a signing secret that Jira does not, so "
+                      "Jira's deliveries are refused until apply succeeds; run it again once "
+                      "the cause is fixed.", exc.code) from exc
+
+    return {
+        "openhands_webhook": {"id": webhook["id"], "source": webhook["source"], "url": url},
+        "jira_webhook": {"id": hook_id, "action": action, "name": name,
+                         "events": JIRA_EVENTS, "jql": jql},
+        "signing_secret": "new" if new_secret else "unchanged",
+        "signed_delivery_check": _signed_check(url, _secret) if new_secret
+                                 else "skipped: the secret was not changed",
+    }
+
+
+def delete(args, openhands, jira):
+    jira.require_admin()
+    webhook = openhands.find()
+    if not webhook:
+        return {"deleted_jira_webhooks": [],
+                "note": f"No OpenHands webhook with source '{args.source}', so no Jira webhook to match."}
+    return {"deleted_jira_webhooks": [jira.delete(h) for h in jira.find(webhook["webhook_url"])],
+            "note": "The OpenHands webhook is left in place; it receives nothing now."}
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Set up the Jira Cloud webhook of an event-based automation.")
+    parser.add_argument("action", choices=["apply", "delete"])
+    parser.add_argument("--jira-base-url", required=True)
+    parser.add_argument("--jira-email", required=True)
+    parser.add_argument("--openhands-host", required=True)
+    parser.add_argument("--jira-token-env", default="JIRA_CLOUD_KEY")
+    parser.add_argument("--source", default="jira")
+    parser.add_argument("--label", default="create-pr")
+    parser.add_argument("--jql")
+    parser.add_argument("--name")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--rotate-secret", action="store_true")
+    args = parser.parse_args()
+
+    api_key = os.environ.get("OPENHANDS_API_KEY", "")
+    token = os.environ.get(args.jira_token_env, "")
+    try:
+        if not api_key:
+            raise Failure("OPENHANDS_API_KEY is not set.", code=2)
+        if not token:
+            raise Failure(f"{args.jira_token_env} is not set. Store the Jira API token as an "
+                          "OpenHands secret and name it in the command.", code=2)
+        if urllib.parse.urlparse(args.jira_base_url).scheme != "https":
+            raise Failure("--jira-base-url must be an https:// URL.", code=2)
+        if urllib.parse.urlparse(args.openhands_host).scheme != "https":
+            raise Failure("--openhands-host must be an https:// URL: Jira only delivers "
+                          "webhooks over HTTPS.", code=2)
+        openhands = OpenHands(args.openhands_host, api_key, args.source)
+        jira = Jira(args.jira_base_url, args.jira_email, token)
+        result = (apply if args.action == "apply" else delete)(args, openhands, jira)
+    except Failure as exc:
+        print(_redact(str(exc)), file=sys.stderr)
+        sys.exit(exc.code)
+    print(_redact(json.dumps(result, indent=2)))
+
+
+if __name__ == "__main__":
+    main()

package/skills/linear-triage/SKILL.md

@@ -64,14 +64,14 @@ Construct a prompt that includes:
 
 ### Step 4 — Create the automation
 
-Read the Automation backend URL and auth from `<RUNTIME_SERVICES>`:
-- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`
-- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`
+Set `OPENHANDS_HOST` and `AUTH_HEADER` for the request 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 `<RUNTIME_SERVICES>`: use its `url_from_agent` as `OPENHANDS_HOST`, with `AUTH_HEADER="X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY"`
 
 Use the **prompt preset** endpoint:
 ```bash
 curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "$AUTH_HEADER" \
   -H "Content-Type: application/json" \
   -d '{
     "name": "Linear Issue Triage",
@@ -80,7 +80,7 @@ curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   }'
 ```
 
-PowerShell note: use `curl.exe` for this exact flag syntax, and replace `${OPENHANDS_HOST}` / `$OPENHANDS_AUTOMATION_API_KEY` with `$env:OPENHANDS_HOST` / `$env:OPENHANDS_AUTOMATION_API_KEY` if running it natively.
+PowerShell note: use `curl.exe` for this exact flag syntax, and replace `${OPENHANDS_HOST}` / `$AUTH_HEADER` with `$env:OPENHANDS_HOST` / `$env:AUTH_HEADER` if running it natively.
 
 ### Step 5 — Confirm
 

package/skills/news-digest/README.md

@@ -8,6 +8,12 @@ your topics and write a short digest.
 makes it the automation to run first, before deciding what access you are
 willing to hand over.
 
+On a local Agent Canvas the conversation that writes the digest is also started
+with no secrets and no MCP servers. On OpenHands Cloud and Enterprise it is
+started through the OpenHands API with your own settings, so it holds your
+secrets and MCP servers like any conversation you start there, while reading
+feed text nobody vetted.
+
 ## Trigger
 
 This skill is activated by:

package/skills/news-digest/SKILL.md

@@ -4,8 +4,8 @@ description: >
   Create an automation that reads a list of public RSS and Atom feeds on a
   schedule - daily by default - keeps what is new and matches the configured
   topics, and has an agent write a short digest of it. It needs no credentials:
-  the feeds are public URLs and the conversation is started with no secrets and
-  no MCP servers.
+  the feeds are public URLs and, on a local Agent Canvas, the conversation is
+  started with no secrets and no MCP servers.
 triggers:
   - /news-digest:setup
 ---
@@ -154,17 +154,24 @@ python3 -m py_compile /tmp/news-digest-build/main.py && echo "Syntax OK"
 
 ### Step 6 - 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/news-digest.tar.gz -C /tmp/news-digest-build .
 
 TARBALL_PATH=$(curl -s -X POST \
   "${OPENHANDS_HOST}/api/automation/v1/uploads?name=news-digest" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "$AUTH_HEADER" \
   -H "Content-Type: application/gzip" \
   --data-binary @/tmp/news-digest.tar.gz \
   | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")
@@ -176,7 +183,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\": \"Daily news digest\",
@@ -210,7 +217,7 @@ Then offer to dispatch it once so they can read today's digest immediately:
 
 ```bash
 curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/{id}/dispatch" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY"
+  -H "$AUTH_HEADER"
 ```
 
 ---
@@ -241,6 +248,9 @@ shipped one and then:
    with the stories **and the topics** in its prompt, an empty secrets payload
    and no MCP servers, working in `{WORKSPACE_BASE}/news-digest/{date}`. The
    agent decides which stories are relevant before it writes anything.
+   On OpenHands Cloud and Enterprise the conversation is started through
+   the OpenHands API instead, in a sandbox of its own and with the user's own
+   settings, so there it does hold the user's secrets and MCP servers.
 7. When the conversation reaches `idle`, `finished`, `error` or `stuck`:
    - reads `digest.md` from the working directory, falling back to the agent's
      final message;

package/skills/news-digest/commands/news-digest-setup.md

@@ -1,6 +1,6 @@
 ---
 # auto-generated by sync_extensions.py
-description: Create an automation that reads a list of public RSS and Atom feeds on a schedule - daily by default - keeps what is new and matches the configured topics, and has an agent write a short digest of it. It needs no credentials: the feeds are public URLs and the conversation is started with no secrets and no MCP servers.
+description: Create an automation that reads a list of public RSS and Atom feeds on a schedule - daily by default - keeps what is new and matches the configured topics, and has an agent write a short digest of it. It needs no credentials: the feeds are public URLs and, on a local Agent Canvas, the conversation is started with no secrets and no MCP servers.
 ---
 
 Read and follow the complete instructions in the SKILL.md file located in this skill's directory.

package/skills/news-digest/scripts/main.py

@@ -8,7 +8,10 @@ This automation needs no credentials. It authenticates to nothing: the feeds are
 public URLs fetched over plain HTTPS, and the conversation is started with an
 empty secret allow-list and no MCP servers, so there is nothing for it to leak.
 That is deliberate - it is the automation to reach for when you want to see one
-working before you decide which tokens you are willing to hand over.
+working before you decide which tokens you are willing to hand over. The empty
+allow-list holds on a local Agent Canvas. On OpenHands Cloud and Enterprise the
+OpenHands API starts the conversation in a sandbox of its own, with the user's
+own model, secrets and MCP servers; the script itself still uses none of them.
 
 The split of duties is the same as the other bundled automations, drawn at what
 has a right answer. Python owns the schedule, the once-a-day claim, fetching,
@@ -37,6 +40,7 @@ import time
 import urllib.error
 import urllib.parse
 import urllib.request
+import uuid
 from collections.abc import Callable
 from datetime import datetime, timezone
 from email.utils import parsedate_to_datetime
@@ -224,17 +228,24 @@ USER_AGENT = "OpenHands-News-Digest/1.0 (+https://github.com/OpenHands/extension
 DIGEST_FILENAME = "digest.md"
 
 
+# A local Agent Canvas run is handed the Agent Server URL. A run on OpenHands
+# Cloud or Enterprise is handed the OpenHands API instead.
+_CLOUD_API_URL = os.environ.get("OPENHANDS_CLOUD_API_URL", "").rstrip("/")
+IS_CLOUD = bool(_CLOUD_API_URL) and not os.environ.get("AGENT_SERVER_URL")
+
+
 def _get_env_key() -> str:
     return os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0") or ""
 
 
 def get_secret(name: str) -> str:
-    url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     key = _get_env_key()
-    req = urllib.request.Request(
-        f"{url}/api/settings/secrets/{name}",
-        headers={"X-Session-API-Key": key},
-    )
+    if IS_CLOUD:
+        # The OpenHands API serves the secrets of this run's sandbox.
+        url = f"{_CLOUD_API_URL}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
+    else:
+        url = f"{os.environ.get('AGENT_SERVER_URL', '').rstrip('/')}/api/settings/secrets/{name}"
+    req = urllib.request.Request(url, headers={"X-Session-API-Key": key})
     with urllib.request.urlopen(req) as r:
         return r.read().decode().strip()
 
@@ -252,12 +263,14 @@ def fire_callback(
         body["error"] = error
     if conversation_id:
         body["conversation_id"] = conversation_id
+    # A cloud run is not given a callback key; it authenticates with its API key.
+    api_key = os.environ.get("AUTOMATION_CALLBACK_API_KEY") or os.environ.get("OPENHANDS_API_KEY", "")
     req = urllib.request.Request(
         url,
         data=json.dumps(body).encode(),
         headers={
             "Content-Type": "application/json",
-            "Authorization": f"Bearer {os.environ.get('AUTOMATION_CALLBACK_API_KEY', '')}",
+            "Authorization": f"Bearer {api_key}",
         },
     )
     try:
@@ -749,12 +762,96 @@ def _build_secrets_payload(agent_url: str, api_key: str) -> dict:
     return secrets
 
 
+def _cloud_request(method: str, path: str, body: dict | None = None):
+    """Call the OpenHands API with the API key this cloud run was given."""
+    req = urllib.request.Request(
+        f"{_CLOUD_API_URL}{path}",
+        data=json.dumps(body).encode() if body is not None else None,
+        headers={
+            "Authorization": f"Bearer {os.environ.get('OPENHANDS_API_KEY', '')}",
+            "Content-Type": "application/json",
+        },
+        method=method,
+    )
+    try:
+        with urllib.request.urlopen(req) as r:
+            raw = r.read()
+            return json.loads(raw) if raw.strip() else {}
+    except urllib.error.HTTPError as exc:
+        body_text = exc.read().decode()
+        raise RuntimeError(f"OpenHands API {method} {path} → {exc.code}: {body_text}") from exc
+
+
+def _create_cloud_conversation(initial_message: str, title: str) -> str:
+    """Start a conversation through the OpenHands API and return its id.
+
+    OpenHands runs it in a sandbox of its own, which outlives this run's, with
+    the user's own model, MCP servers and secrets: unlike a local run, the
+    conversation is not held to the empty secrets payload below.
+    """
+    conversation_id = uuid.uuid4().hex
+    _cloud_request(
+        "POST",
+        "/api/v1/app-conversations",
+        {
+            "conversation_id": conversation_id,
+            "title": title,
+            "initial_message": {
+                "role": "user",
+                "content": [{"type": "text", "text": initial_message}],
+            },
+        },
+    )
+    return conversation_id
+
+
+def _cloud_conversation_status(conv_id: str) -> str:
+    found = _cloud_request("GET", f"/api/v1/app-conversations?ids={conv_id}")
+    conversation = found[0] if found else None
+    if conversation is None:
+        # OpenHands is still bringing the conversation up.
+        return "starting"
+    if conversation.get("execution_status"):
+        return conversation["execution_status"]
+    # The status is only reported while the conversation's sandbox is running.
+    # Once it is paused, the last status the agent reported is in its events.
+    events = _cloud_request(
+        "GET",
+        f"/api/v1/conversation/{conv_id}/events/search"
+        "?kind__eq=ConversationStateUpdateEvent&sort_order=TIMESTAMP_DESC&limit=100",
+    )
+    for event in events.get("items", []):
+        if event.get("key") == "execution_status":
+            return event.get("value") or "unknown"
+    return "unknown"
+
+
+def _cloud_conversation_final_response(conv_id: str) -> str:
+    """The agent's closing message, read from the conversation's stored events."""
+    events = _cloud_request(
+        "GET",
+        f"/api/v1/conversation/{conv_id}/events/search?sort_order=TIMESTAMP_DESC&limit=100",
+    )
+    for event in events.get("items", []):
+        if event.get("source") != "agent":
+            continue
+        if event.get("kind") == "ActionEvent" and event.get("tool_name") == "finish":
+            return (event.get("action") or {}).get("message") or ""
+        if event.get("kind") == "MessageEvent":
+            content = (event.get("llm_message") or {}).get("content") or []
+            return "".join(part.get("text", "") for part in content)
+    return ""
+
+
 def create_conversation(
     agent_url: str,
     api_key: str,
     initial_message: str,
-    workspace_dir: Path,
+    workspace_dir: Path | None,
+    title: str = "",
 ) -> str:
+    if IS_CLOUD:
+        return _create_cloud_conversation(initial_message, title)
     payload: dict = {
         "workspace": {"working_dir": str(workspace_dir)},
         "agent": _get_agent_dict(agent_url, api_key),
@@ -770,11 +867,15 @@ def create_conversation(
 
 
 def conversation_status(agent_url: str, api_key: str, conv_id: str) -> str:
+    if IS_CLOUD:
+        return _cloud_conversation_status(conv_id)
     result = _oh_request(agent_url, api_key, "GET", f"/api/conversations/{conv_id}")
     return result.get("execution_status", "unknown")
 
 
 def conversation_final_response(agent_url: str, api_key: str, conv_id: str) -> str:
+    if IS_CLOUD:
+        return _cloud_conversation_final_response(conv_id)
     result = _oh_request(agent_url, api_key, "GET", f"/api/conversations/{conv_id}/agent_final_response")
     return result.get("response", "")
 
@@ -1048,9 +1149,14 @@ def _start_task(
 
     workspace_dir = None
     try:
-        workspace_dir = _prepare_workspace(period)
+        # A cloud conversation runs in a sandbox of its own, so there is no
+        # directory here for it to work in; its digest is its final message.
+        if not IS_CLOUD:
+            workspace_dir = _prepare_workspace(period)
         prompt = _build_digest_prompt(period, TOPICS, items, feed_errors)
-        conv_id = create_conversation(agent_url, api_key, prompt, workspace_dir)
+        conv_id = create_conversation(
+            agent_url, api_key, prompt, workspace_dir, title=f"News digest {period}"
+        )
     except Exception as exc:
         # The claim is dropped so the next run retries today. The workspace goes
         # with it rather than being left behind.
@@ -1065,7 +1171,7 @@ def _start_task(
         {
             "status": "active",
             "conversation_id": conv_id,
-            "workspace_dir": str(workspace_dir),
+            "workspace_dir": str(workspace_dir) if workspace_dir else None,
             "last_activity": time.time(),
         }
     )
@@ -1160,10 +1266,22 @@ def main() -> str | None:
     if not FEEDS:
         raise SystemExit("No feeds are configured; nothing to digest")
 
-    try:
-        openhands_url = get_secret("OPENHANDS_URL").rstrip("/") or DEFAULT_OPENHANDS_URL
-    except Exception:
-        openhands_url = DEFAULT_OPENHANDS_URL
+    if IS_CLOUD and not _kv_available():
+        # A cloud run starts in a fresh sandbox, so a state file would not
+        # survive it and every run would write today's digest again.
+        raise RuntimeError(
+            "The automation KV store is required on OpenHands Cloud and Enterprise, "
+            "but AUTOMATION_KV_TOKEN is not set for this run."
+        )
+
+    if IS_CLOUD:
+        # Conversations are opened in the Canvas of the deployment itself.
+        openhands_url = f"{_CLOUD_API_URL}/canvas"
+    else:
+        try:
+            openhands_url = get_secret("OPENHANDS_URL").rstrip("/") or DEFAULT_OPENHANDS_URL
+        except Exception:
+            openhands_url = DEFAULT_OPENHANDS_URL
 
     state = load_state()
     tasks: dict = state.setdefault("tasks", {})

package/skills/openhands-api/README.md

@@ -22,7 +22,7 @@ The Python client prefers `OPENHANDS_CLOUD_API_KEY` and falls back to `OPENHANDS
 
 ## Delegating work with new Cloud conversations
 
-Use `POST /api/v1/app-conversations` to create a separate OpenHands Cloud conversation for a self-contained task, then poll `GET /api/v1/app-conversations/start-tasks?ids=...` until you have an `app_conversation_id`.
+Use `POST /api/v1/app-conversations` to create a separate OpenHands Cloud conversation for a self-contained task, then poll `GET /api/v1/app-conversations/start-tasks?ids=...` until you have an `app_conversation_id`. Share the Agent Canvas link from `OpenHandsAPI.app_conversation_ui_url(app_conversation_id)` (the conversation's `conversation_ui_url`, falling back to `<base_url>/canvas/conversations/<id>`).
 
 Keep delegated prompts self-contained: include the repository, branch, relevant files, constraints, and expected output. Prefer five or fewer concurrently running delegated conversations.