@openhands/extensions 0.24.0 → 0.26.0

package/skills/jira-issue-to-pr/README.md

@@ -28,10 +28,13 @@ This skill is activated by keywords:
    Subsequent runs filter by both `first_run_at` and a KV-backed set of
    already-processed issue keys. A `max_new_per_run` cap (default 5) limits
    conversations started per cron firing.
-3. **Dispatch** - for each new issue, the script calls
-   `POST /api/conversations` on the agent server to start an independent agent
-   conversation with a PR-creation prompt. The prompt instructs the agent to
-   extract the target GitHub repository (`owner/repo`) from the ticket body.
+3. **Dispatch** - for each new issue, the script starts an independent agent
+   conversation with a PR-creation prompt: `POST /api/conversations` on the
+   agent server when running locally, `POST /api/v1/app-conversations` on
+   OpenHands Cloud and Enterprise. The prompt instructs the agent to extract the
+   target GitHub repository (`owner/repo`) from the ticket body. On Cloud the
+   next poll confirms the conversation came up and starts it again when it did
+   not.
 4. **Comment** - immediately after the conversation is created, the script
    posts a Jira comment on the issue: `I'm on it: <conversation URL>`.
 5. **Persist** - the processed issue key is recorded so re-runs never
@@ -40,6 +43,11 @@ This skill is activated by keywords:
 The polling run is lightweight (Python stdlib only, no SDK install); LLM costs
 are incurred only when new issues are actually found.
 
+Where Jira can reach the deployment (OpenHands Cloud and Enterprise), the skill
+can set up an event-based automation instead of this poller: Jira pushes label
+events through a webhook, which `scripts/setup_webhook.py` registers in both
+OpenHands and Jira. See "Event-Based Alternative" in `SKILL.md`.
+
 ## Prerequisites
 
 | Requirement | Details |

package/skills/jira-issue-to-pr/SKILL.md

@@ -30,10 +30,10 @@ starts, it also posts a comment on the Jira ticket: "I'm on it: <conversation
    be picked up. Subsequent runs filter by both `first_run_at` and a KV-backed set of
    already-processed issue keys. A `max_new_per_run` cap (default 5) limits conversations
    started per cron firing as additional defense-in-depth.
-3. **Dispatch** - for each new issue, call `POST /api/conversations` on the agent server
-   to start an independent agent conversation with a PR-creation prompt. The prompt
-   instructs the agent to extract the target GitHub repository (`owner/repo`) from the
-   ticket body.
+3. **Dispatch** - for each new issue, start an independent agent conversation with a
+   PR-creation prompt: `POST /api/conversations` on the agent server when running locally,
+   or `POST /api/v1/app-conversations` on OpenHands Cloud. The prompt instructs the agent
+   to extract the target GitHub repository (`owner/repo`) from the ticket body.
 4. **Comment** - immediately after the conversation is created, post a Jira comment on the
    issue: `I'm on it: <conversation URL>`.
 5. **Persist** - record the processed issue key so re-runs never duplicate work.
@@ -48,12 +48,28 @@ Before deploying, ensure the following are in place:
 | Requirement | Details |
 |---|---|
 | **Jira API token** | Stored as an OpenHands secret (see [Jira API token setup](#jira-api-token)) |
-| **GitHub token** | Must be stored as an OpenHands secret with `repo` + `workflow` scope so the spawned conversation can push branches and open PRs |
+| **GitHub access** | Local: a GitHub token stored as an OpenHands secret with `repo` + `workflow` scope so the spawned conversation can push branches and open PRs. OpenHands Cloud: the spawned conversation uses the user's connected GitHub integration (native integration recommended, or the GitHub MCP server) |
+| **KV store** (OpenHands Cloud only) | The automation service must have its KV store enabled (`kvStore` in `GET /api/automation/v1/capabilities`); each cloud run starts in a fresh sandbox, so processed issues are remembered there |
 | **Jira label** | The label to watch for (default: `create-pr`) must exist in the Jira project |
 | **GitHub repo** | The target repository must exist and the GitHub token must have write access |
 
 ## Deploying the Automation
 
+### Determine the API host and auth
+
+Set `OPENHANDS_HOST` and `AUTH_HEADER` for the curl commands below:
+
+- **OpenHands Cloud** - a `<HOST>` value is present in the system prompt:
+  ```bash
+  OPENHANDS_HOST="<HOST value>"
+  AUTH_HEADER="Authorization: Bearer $OPENHANDS_API_KEY"
+  ```
+- **Local Agent Canvas** - no `<HOST>` value:
+  ```bash
+  OPENHANDS_HOST="http://localhost:8000"
+  AUTH_HEADER="X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY"
+  ```
+
 ### Step 1 - Collect parameters
 
 Gather the following from the user before proceeding:
@@ -101,8 +117,8 @@ python3 -m py_compile "$WORK/main.py"   # validate syntax before uploading
 
 ```bash
 TARBALL_PATH=$(curl -s -X POST \
-  "http://localhost:8000/api/automation/v1/uploads?name=jira-issue-to-pr" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  "${OPENHANDS_HOST}/api/automation/v1/uploads?name=jira-issue-to-pr" \
+  -H "$AUTH_HEADER" \
   -H "Content-Type: application/gzip" \
   --data-binary @/tmp/jira-issue-to-pr.tar.gz \
   | python3 -c "import sys,json; print(json.load(sys.stdin)['tarball_path'])")
@@ -111,8 +127,8 @@ TARBALL_PATH=$(curl -s -X POST \
 ### Step 5 - Create the automation
 
 ```bash
-curl -s -X POST "http://localhost:8000/api/automation/v1" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1" \
+  -H "$AUTH_HEADER" \
   -H "Content-Type: application/json" \
   -d "{
     \"name\": \"Jira issue-to-PR Poller\",
@@ -133,15 +149,107 @@ Save the returned `id` - use it for updates and monitoring.
 
 ```bash
 curl -s -X POST \
-  "http://localhost:8000/api/automation/v1/<AUTOMATION_ID>/dispatch" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" | python3 -m json.tool
+  "${OPENHANDS_HOST}/api/automation/v1/<AUTOMATION_ID>/dispatch" \
+  -H "$AUTH_HEADER" | python3 -m json.tool
 
 # After ~30 seconds, check the run status:
-curl -s "http://localhost:8000/api/automation/v1/<AUTOMATION_ID>/runs?limit=1" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+curl -s "${OPENHANDS_HOST}/api/automation/v1/<AUTOMATION_ID>/runs?limit=1" \
+  -H "$AUTH_HEADER" \
   | python3 -c "import sys,json; r=json.load(sys.stdin)['runs'][0]; print(r['status'], r.get('error_detail'))"
 ```
 
+## Event-Based Alternative
+
+Where Jira can reach the deployment over the internet (OpenHands Cloud and Enterprise),
+Jira can push label events instead of being polled. That is a different automation from
+the poller above: a prompt automation triggered by a Jira webhook, created with the
+`openhands-automation` skill (see its "Custom Webhook Example: Jira Cloud").
+`scripts/main.py` is not used, so its KV-backed deduplication and its "I'm on it"
+comment do not apply; the prompt has to ask for whatever of that is wanted.
+
+### Set up the webhook
+
+The webhook is a pair: a custom webhook source in OpenHands and an admin webhook in
+Jira, sharing a signing secret. `scripts/setup_webhook.py` creates both, so the user
+does not have to open Jira or copy a URL and secret by hand. It needs the API token of
+an account with the **Administer Jira** permission, stored as an OpenHands secret.
+
+1. **Collect** the Jira site URL, the account email, the name of the secret holding that
+   account's API token, and the label. A token used only for this step (for example
+   `JIRA_ADMIN_TOKEN`) can be deleted from the user's secrets afterwards.
+2. **Dry run, then ask.** Registering a webhook changes the user's Jira site, so show
+   what will be created and wait for the user to confirm:
+
+   ```bash
+   OPENHANDS_API_KEY="$OPENHANDS_API_KEY" python3 <skill-dir>/scripts/setup_webhook.py apply --dry-run \
+     --jira-base-url "https://acme.atlassian.net" --jira-email "alice@acme.com" \
+     --jira-token-env JIRA_ADMIN_TOKEN --openhands-host "$OPENHANDS_HOST" --label create-pr
+   ```
+
+   The command has to name the secret (`--jira-token-env JIRA_ADMIN_TOKEN`): naming it is
+   what makes its value available to the command.
+3. **Apply** - the same command without `--dry-run`. It registers the OpenHands webhook
+   (`source` `jira`, `webhookEvent`, `X-Hub-Signature`), creates the Jira webhook for
+   *Issue created* and *Issue updated* limited to `labels = "create-pr"`, and sends one
+   signed test request. `"signed_delivery_check": "ok"` in its output means the pair works.
+   Running it again updates the Jira webhook in place and keeps the secret, so a
+   failure half way cannot break a working pair. Add `--rotate-secret` when the two
+   sides have drifted apart, for instance after the deployment was reinstalled.
+
+   The secret is generated inside the script and is never printed. Do not ask the user
+   for it, and do not try to read or echo it.
+4. **If it exits with code 3**, the account is not a Jira administrator. Fall back to
+   [Manual webhook setup](#manual-webhook-setup).
+
+To stop Jira sending events, for example when the automation is deleted, run the same
+command with `delete` in place of `apply`.
+
+### Create the event-triggered automation
+
+Create the automation with this trigger:
+
+```json
+{
+  "type": "event",
+  "source": "jira",
+  "on": ["jira:issue_created", "jira:issue_updated"],
+  "filter": "contains(issue.fields.labels, 'create-pr') && (webhookEvent == 'jira:issue_created' || length(changelog.items[?field == 'labels'] || `[]`) > `0`)"
+}
+```
+
+Jira sends labels as plain strings, so the filter reads `issue.fields.labels`, not
+`issue.fields.labels[].name`. The `changelog` check limits updates to those that
+change the labels; without it every later edit of a labelled issue starts another run.
+It still fires when another label is added to or removed from an issue that
+carries the label, so have the prompt skip an issue that already has a pull request.
+
+To verify, add the label to an issue and check the automation's runs.
+
+### Manual webhook setup
+
+Use this when the Jira account is not an administrator: the user, or their Jira
+administrator, does both steps by hand.
+
+1. **Register the webhook** with `"source": "jira"`, `"event_key_expr": "webhookEvent"`
+   and `"signature_header": "X-Hub-Signature"` (see the `openhands-automation` skill for
+   the request). The defaults (`type`, `X-Signature-256`) do not fit Jira: deliveries are
+   refused with 401, or accepted and never matched.
+2. **Configure Jira** - a Jira admin creates the webhook under Jira settings → System →
+   WebHooks with the returned `webhook_url` and secret, the *Issue created* and
+   *Issue updated* events, and a JQL filter such as `labels = create-pr`. A Jira
+   Automation rule cannot be used instead: its "Send web request" action is not signed.
+
+To test a manually configured webhook without Jira, sign a request the way Jira does:
+
+```bash
+BODY='{"webhookEvent":"jira:issue_created","issue":{"key":"TEST-1","fields":{"labels":["create-pr"]}}}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $NF}')
+curl -s -X POST "<webhook_url>" -H "Content-Type: application/json" \
+  -H "X-Hub-Signature: sha256=$SIG" -d "$BODY"
+```
+
+`"matched": 1` in the response means the trigger fired and a run was started.
+
 ## Updating an Existing Deployment
 
 To change configuration or update the script:
@@ -152,8 +260,8 @@ To change configuration or update the script:
 
 ```bash
 curl -s -X PATCH \
-  "http://localhost:8000/api/automation/v1/<AUTOMATION_ID>" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  "${OPENHANDS_HOST}/api/automation/v1/<AUTOMATION_ID>" \
+  -H "$AUTH_HEADER" \
   -H "Content-Type: application/json" \
   -d "{\"tarball_path\": \"<NEW_TARBALL_PATH>\"}"
 ```
@@ -164,7 +272,7 @@ To reprocess issues that were already handled (e.g., after testing), clear the K
 
 ```bash
 curl -s -X DELETE \
-  "http://localhost:8000/api/automation/v1/<KV_BASE>/v1/kv/state" \
+  "${OPENHANDS_HOST}/api/automation/v1/<KV_BASE>/v1/kv/state" \
   -H "Authorization: Bearer $AUTOMATION_KV_TOKEN"
 ```
 
@@ -178,11 +286,14 @@ The automation script lives at `scripts/main.py`. Key behaviors:
 - **Config file** - reads all parameters from `config.json` co-located with the script.
 - **First-run baseline** - on the very first execution the script writes `first_run_at` (UTC timestamp) into the KV store and exits without dispatching; issues whose `updated` timestamp predates that baseline are skipped on all subsequent runs. Using `updated` (not `created`) means an old issue that has its label applied after deployment is correctly treated as new.
 - **Per-run cap** - `max_new_per_run` (default 5) limits how many conversations are started per cron firing; any remaining new issues are dispatched on the next run.
-- **KV store** - persists `{"processed_keys": [...], "first_run_at": "..."}` between runs; falls back to a local file in dev environments where `AUTOMATION_KV_TOKEN` is absent.
+- **KV store** - persists `{"processed_keys": [...], "first_run_at": "..."}` between runs; falls back to a local file in local dev environments where `AUTOMATION_KV_TOKEN` is absent (on OpenHands Cloud the run fails instead, since its sandbox does not persist).
 - **Jira API** - uses `POST /rest/api/3/search/jql` (the current non-deprecated endpoint).
-- **Conversation dispatch** - calls `POST /api/conversations` on the agent server with the current user's LLM/agent settings forwarded to the new conversation.
+- **Conversation dispatch** - locally, calls `POST /api/conversations` on the agent server with the current user's LLM/agent settings forwarded to the new conversation; on OpenHands Cloud, calls `POST /api/v1/app-conversations`, which runs each conversation in its own sandbox with the user's settings, secrets and connected git provider.
+- **Start confirmation** (OpenHands Cloud only) - the API answers a start request before the conversation exists, so the next run checks each one. A start that failed is made again, up to three times, and after that the failure is posted on the Jira issue.
 - **Error transparency** - captures Jira HTTP response bodies in error messages for fast diagnosis.
 
+`scripts/setup_webhook.py` belongs to the [event-based alternative](#event-based-alternative) and is not part of the poller's tarball. It is stdlib-only, reads `OPENHANDS_API_KEY` and the Jira API token from the environment, and prints a JSON summary that never contains the signing secret.
+
 ## Known Limitations
 
 ### Pre-existing issues updated after deployment

package/skills/jira-issue-to-pr/references/setup.md

@@ -9,6 +9,14 @@
 3. Give it a label (e.g., `openhands-create-pr`) and click **Create**.
 4. Copy the token value - it is shown only once.
 
+### Token for the event-based webhook setup
+
+`scripts/setup_webhook.py` registers a webhook in Jira, which Jira allows only for an
+account with the **Administer Jira** global permission. Create the token as above while
+logged in as such an account - a classic API token, not one restricted to scopes - and
+store it under its own name, for example `JIRA_ADMIN_TOKEN`. It is needed only while the
+webhook is set up, changed or deleted, and can be removed from the secrets afterwards.
+
 ### Store the token as an OpenHands secret
 
 Navigate to **Settings → Secrets** in the OpenHands UI and add a new secret:

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

@@ -10,8 +10,11 @@ config.json fields:
 
 The target GitHub repository is NOT configured here. Each Jira ticket body must include
 the repo in "owner/repo" format; the spawned agent extracts it from the ticket text.
+
+Runs against a local agent server (AGENT_SERVER_URL is injected) or on OpenHands Cloud
+(OPENHANDS_CLOUD_API_URL / OPENHANDS_API_KEY / SANDBOX_ID are injected instead).
 """
-import base64, json, os, re, sys, tempfile, urllib.error, urllib.request
+import base64, json, os, re, sys, tempfile, urllib.error, urllib.request, uuid
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -25,6 +28,11 @@ JIRA_EMAIL         = _cfg["jira_email"]
 JIRA_TOKEN_SECRET  = _cfg.get("jira_token_secret", "JIRA_CLOUD_KEY")
 JIRA_LABEL         = _cfg.get("jira_label", "create-pr")
 MAX_NEW_PER_RUN    = int(_cfg.get("max_new_per_run", 5))
+# How often a conversation that OpenHands Cloud failed to start is started again.
+MAX_START_ATTEMPTS = 3
+
+# Only a local run is handed the agent server's URL.
+IS_LOCAL = bool(os.environ.get("AGENT_SERVER_URL"))
 
 # ── KV store helpers ──────────────────────────────────────────────────────────
 _KV_TOKEN  = os.environ.get("AUTOMATION_KV_TOKEN", "")
@@ -105,10 +113,16 @@ def save_state(state):
 
 # ── Required stdlib helpers ───────────────────────────────────────────────────
 def get_secret(name):
-    url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
+    if IS_LOCAL:
+        url = f"{os.environ['AGENT_SERVER_URL'].rstrip('/')}/api/settings/secrets/{name}"
+    else:
+        # Cloud: the OpenHands Cloud API serves the secrets of this run's sandbox.
+        cloud_url = os.environ.get("OPENHANDS_CLOUD_API_URL", "").rstrip("/")
+        sandbox_id = os.environ.get("SANDBOX_ID", "")
+        url = f"{cloud_url}/api/v1/sandboxes/{sandbox_id}/settings/secrets/{name}"
     with urllib.request.urlopen(urllib.request.Request(
-        f"{url}/api/settings/secrets/{name}", headers={"X-Session-API-Key": key}
+        url, headers={"X-Session-API-Key": key}
     )) as r:
         return r.read().decode().strip()
 
@@ -120,12 +134,15 @@ def fire_callback(status="COMPLETED", error=None):
     body = {"status": status, "run_id": os.environ.get("AUTOMATION_RUN_ID", "")}
     if error:
         body["error"] = error
+    # Cloud runs are not given a callback key; they authenticate with their API key.
+    api_key = (os.environ.get("AUTOMATION_CALLBACK_API_KEY")
+               or os.environ.get("OPENHANDS_API_KEY", ""))
     try:
         urllib.request.urlopen(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}",
             }
         ))
     except Exception as e:
@@ -199,6 +216,96 @@ def post_jira_comment(issue_key, auth_header, text):
         print(f"Warning: failed to post Jira comment on {issue_key} ({exc.code}): {body_text[:200]}")
 
 
+def _cloud_request(method, path, body=None):
+    """Call the OpenHands Cloud API with the API key this run was given."""
+    cloud_url = os.environ.get("OPENHANDS_CLOUD_API_URL", "").rstrip("/")
+    req = urllib.request.Request(
+        f"{cloud_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()
+    except urllib.error.HTTPError as exc:
+        body_text = exc.read().decode(errors="replace")
+        raise RuntimeError(f"OpenHands API {method} {path} failed {exc.code}: {body_text[:500]}") from exc
+    return json.loads(raw) if raw.strip() else {}
+
+
+def start_cloud_conversation(title, prompt):
+    """Ask the OpenHands Cloud API to start a conversation.
+
+    OpenHands Cloud runs it in its own sandbox with the user's LLM, MCP servers,
+    secrets and connected git provider (e.g. the native GitHub integration).
+
+    The API answers with the task that starts the conversation, not with a
+    started conversation, so this returns the conversation's URL and that task's
+    id for a later run to confirm (settle_cloud_starts).
+    """
+    cloud_url       = os.environ.get("OPENHANDS_CLOUD_API_URL", "").rstrip("/")
+    conversation_id = uuid.uuid4().hex
+    task = _cloud_request("POST", "/api/v1/app-conversations", {
+        "conversation_id": conversation_id,
+        "title":           title,
+        "initial_message": {"content": [{"type": "text", "text": prompt}]},
+    })
+    if task.get("status") == "ERROR":
+        raise RuntimeError(f"Starting a conversation failed: {task.get('detail') or 'no detail'}")
+    return f"{cloud_url}/canvas/conversations/{conversation_id}", task.get("id")
+
+
+def settle_cloud_starts(state, processed_keys, auth_header):
+    """Confirm the conversations earlier runs asked OpenHands Cloud to start.
+
+    A start can still fail after the API accepted it, for instance when its
+    sandbox does not come up. Such an issue is released so the next poll starts
+    it again, MAX_START_ATTEMPTS times in all; after that the failure is posted
+    on the issue instead, so it is neither lost silently nor retried forever.
+    """
+    pending = state.get("pending_starts") or {}
+    if not pending:
+        return
+    query = "&".join(f"ids={entry['task_id']}" for entry in pending.values())
+    try:
+        tasks = _cloud_request("GET", f"/api/v1/app-conversations/start-tasks?{query}")
+    except RuntimeError as exc:
+        # Confirming earlier starts must not keep this run from polling Jira.
+        print(f"Warning: could not confirm earlier conversation starts: {exc}")
+        return
+    if not isinstance(tasks, list):
+        return  # not the answer expected; leave them for the next run
+    by_id = {task["id"]: task for task in tasks if task}
+
+    for key, entry in list(pending.items()):
+        task = by_id.get(entry["task_id"])
+        # A task OpenHands no longer has says nothing about a failure, so it is
+        # settled like a started one rather than risk a second conversation.
+        status = task["status"] if task else "READY"
+        if status not in ("READY", "ERROR"):
+            continue  # still starting
+        del pending[key]
+        if status == "READY":
+            continue
+        detail = task.get("detail") or "no detail given"
+        if entry.get("attempts", 1) < MAX_START_ATTEMPTS:
+            print(f"Conversation for {key} did not start ({detail}); it will be started again")
+            processed_keys.discard(key)
+            state.setdefault("start_attempts", {})[key] = entry.get("attempts", 1)
+        else:
+            print(f"Conversation for {key} did not start ({detail}); giving up")
+            post_jira_comment(
+                key, auth_header,
+                f"OpenHands could not start a conversation for this issue: {detail}",
+            )
+    state["pending_starts"]  = pending
+    state["processed_keys"] = list(processed_keys)
+
+
 # ── Timestamp helpers ─────────────────────────────────────────────────────────
 def _parse_ts(ts):
     """Parse an ISO-8601 timestamp, normalising +HHMM → +HH:MM for Python < 3.11."""
@@ -208,6 +315,12 @@ def _parse_ts(ts):
 
 # ── Main ──────────────────────────────────────────────────────────────────────
 try:
+    # A cloud run starts in a fresh sandbox, so without the KV store the processed
+    # issues (and the first-run baseline) would be forgotten after every run.
+    if not IS_LOCAL and not kv_available():
+        raise RuntimeError("The automation KV store is required on OpenHands Cloud, "
+                           "but AUTOMATION_KV_TOKEN is not set for this run.")
+
     jira_token  = get_secret(JIRA_TOKEN_SECRET)
     auth_header = "Basic " + base64.b64encode(
         f"{JIRA_EMAIL}:{jira_token}".encode()
@@ -227,6 +340,9 @@ try:
 
     first_run_at = _parse_ts(state["first_run_at"])
 
+    if not IS_LOCAL:
+        settle_cloud_starts(state, processed_keys, auth_header)
+
     print(f"Polling {JIRA_BASE_URL} for issues labeled '{JIRA_LABEL}'…")
     issues = fetch_labeled_issues(auth_header)
     print(f"Total matching issues : {len(issues)}")
@@ -248,26 +364,28 @@ try:
         fire_callback("COMPLETED")
         sys.exit(0)
 
-    # Start one agent conversation per new issue via the agent server HTTP API.
-    agent_url   = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
-    session_key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
-
-    # Fetch settings with encrypted secrets so llm.api_key is a Fernet token
-    # (starts with gAAAAA) rather than the masked "**********" placeholder.
-    # The conversation payload must include secrets_encrypted: True so the
-    # agent-server decrypts it server-side; we never handle the plaintext key.
-    with urllib.request.urlopen(urllib.request.Request(
-        f"{agent_url}/api/settings",
-        headers={"X-Session-API-Key": session_key, "X-Expose-Secrets": "encrypted"},
-    )) as r:
-        settings = json.loads(r.read())
-
-    agent_settings = settings.get("agent_settings", {})
-    agent_settings.pop("schema_version", None)
-    mcp_config = agent_settings.pop("mcp_config", None)
-    ctx = agent_settings.setdefault("agent_context", {})
-    ctx.update({"load_public_skills": True, "load_user_skills": True, "load_project_skills": True})
-    max_iterations = (settings.get("conversation_settings") or {}).get("max_iterations") or 1000
+    # Start one agent conversation per new issue: via the agent server HTTP API on a
+    # local run, via the OpenHands Cloud API (start_cloud_conversation) on a cloud run.
+    if IS_LOCAL:
+        agent_url   = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
+        session_key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
+
+        # Fetch settings with encrypted secrets so llm.api_key is a Fernet token
+        # (starts with gAAAAA) rather than the masked "**********" placeholder.
+        # The conversation payload must include secrets_encrypted: True so the
+        # agent-server decrypts it server-side; we never handle the plaintext key.
+        with urllib.request.urlopen(urllib.request.Request(
+            f"{agent_url}/api/settings",
+            headers={"X-Session-API-Key": session_key, "X-Expose-Secrets": "encrypted"},
+        )) as r:
+            settings = json.loads(r.read())
+
+        agent_settings = settings.get("agent_settings", {})
+        agent_settings.pop("schema_version", None)
+        mcp_config = agent_settings.pop("mcp_config", None)
+        ctx = agent_settings.setdefault("agent_context", {})
+        ctx.update({"load_public_skills": True, "load_user_skills": True, "load_project_skills": True})
+        max_iterations = (settings.get("conversation_settings") or {}).get("max_iterations") or 1000
 
     for issue in new_issues:
         key         = issue["key"]
@@ -297,36 +415,45 @@ Steps:
    - Body  : Reference the Jira issue key and describe the changes made.
 6. Print the PR URL when done.
 """
-        workdir = tempfile.mkdtemp(prefix=f"jira-{key.lower()}-")
-        payload = {
-            "secrets_encrypted":   True,
-            "agent_settings":      agent_settings,
-            "workspace":           {"kind": "LocalWorkspace", "working_dir": workdir},
-            "confirmation_policy": {"kind": "NeverConfirm"},
-            "max_iterations":      max_iterations,
-            "stuck_detection":     True,
-            "autotitle":           True,
-            "worktree":            False,
-            "initial_message": {
-                "role":    "user",
-                "content": [{"type": "text", "text": prompt}],
-                "run":     True,
-            },
-        }
-        if mcp_config:
-            payload["mcp_config"] = mcp_config
-
-        conv_req = urllib.request.Request(
-            f"{agent_url}/api/conversations",
-            data=json.dumps(payload).encode(),
-            headers={"Content-Type": "application/json", "X-Session-API-Key": session_key},
-        )
-        with urllib.request.urlopen(conv_req) as r:
-            conv = json.loads(r.read())
-
-        conv_id  = conv.get("id")
-        conv_url = f"{agent_url}/conversations/{conv_id}"
-        print(f"✓ Conversation started for {key}: id={conv_id}")
+        if IS_LOCAL:
+            workdir = tempfile.mkdtemp(prefix=f"jira-{key.lower()}-")
+            payload = {
+                "secrets_encrypted":   True,
+                "agent_settings":      agent_settings,
+                "workspace":           {"kind": "LocalWorkspace", "working_dir": workdir},
+                "confirmation_policy": {"kind": "NeverConfirm"},
+                "max_iterations":      max_iterations,
+                "stuck_detection":     True,
+                "autotitle":           True,
+                "worktree":            False,
+                "initial_message": {
+                    "role":    "user",
+                    "content": [{"type": "text", "text": prompt}],
+                    "run":     True,
+                },
+            }
+            if mcp_config:
+                payload["mcp_config"] = mcp_config
+
+            conv_req = urllib.request.Request(
+                f"{agent_url}/api/conversations",
+                data=json.dumps(payload).encode(),
+                headers={"Content-Type": "application/json", "X-Session-API-Key": session_key},
+            )
+            with urllib.request.urlopen(conv_req) as r:
+                conv = json.loads(r.read())
+
+            conv_id  = conv.get("id")
+            conv_url = f"{agent_url}/conversations/{conv_id}"
+            print(f"✓ Conversation started for {key}: id={conv_id}")
+        else:
+            conv_url, start_task_id = start_cloud_conversation(f"[{key}] {summary}", prompt)
+            if start_task_id:
+                attempts = state.setdefault("start_attempts", {}).pop(key, 0) + 1
+                state.setdefault("pending_starts", {})[key] = {
+                    "task_id": start_task_id, "attempts": attempts,
+                }
+            print(f"✓ Conversation requested for {key}: {conv_url}")
 
         post_jira_comment(key, auth_header, f"I'm on it: {conv_url}")