@openhands/extensions 0.8.0 → 0.9.0

package/skills/iterate/SKILL.md

@@ -21,6 +21,7 @@ No scripts — you are the orchestration loop. Uses only standard `gh` CLI
 commands that work on any GitHub repo.
 
 Requires: `gh` CLI authenticated with repo access, a PR branch.
+Windows PowerShell equivalents for Bash-only assignment, redirection, and quoting patterns in this skill are in `references/windows.md`.
 
 ## Discover what the repo has
 

package/skills/iterate/references/windows.md

@@ -0,0 +1,41 @@
+# Windows Notes for Iterate Commands
+
+The `gh` CLI works on Windows, but a few snippets in the skill use Bash syntax.
+
+## Assign Command Output
+
+```powershell
+$sha = gh pr view --json headRefOid --jq .headRefOid
+gh run list --commit $sha --status failure --json databaseId,name,conclusion `
+  --jq '.[] | "\(.databaseId)\t\(.name)\t\(.conclusion)"'
+```
+
+## Redirect Stderr
+
+Replace `2>/dev/null` with `2>$null`:
+
+```powershell
+gh pr create --fill --draft 2>$null
+```
+
+## Multi-line GraphQL Queries
+
+Use a here-string for GraphQL.
+
+```powershell
+$query = @'
+query($owner: String!, $repo: String!, $pr: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      reviewThreads(last: 100) { nodes { id isResolved path line } }
+    }
+  }
+}
+'@
+
+gh api graphql -f query="$query" -f owner="{owner}" -f repo="{repo}" -F pr="{number}"
+```
+
+## Chained Commands
+
+If `&&` is not supported by the installed shell, run each command separately and check `$LASTEXITCODE`.

package/skills/jira-issue-to-pr/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "jira-issue-to-pr",
+  "version": "1.0.0",
+  "description": "Deploy a cron-based OpenHands automation that watches a Jira Cloud project for issues labeled with a configurable label (default: create-pr) and spawns an agent conversation to create a GitHub pull request for each new issue found. The target GitHub repo is read from the ticket body - no repo parameter required at deploy time.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "jira",
+    "atlassian",
+    "github",
+    "pull-request",
+    "automation"
+  ]
+}

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

@@ -0,0 +1,56 @@
+# Jira Issue to GitHub PR
+
+Deploy a cron-based OpenHands automation that polls a Jira Cloud project for
+open issues carrying a configurable label (default: `create-pr`) and, for each
+new issue, starts an OpenHands agent conversation that clones the GitHub
+repository named in the ticket body, creates a branch, implements the requested
+change, and opens a pull request. Once the conversation starts, it posts a
+comment on the Jira ticket: "I'm on it: `<conversation URL>`".
+
+## Triggers
+
+This skill is activated by keywords:
+
+- `set up a Jira automation to create pull requests`
+- `poll Jira for create-pr issues`
+- `automatically create GitHub PRs from Jira tickets`
+- `deploy a Jira issue-to-PR automation`
+- `create a Jira to GitHub PR workflow`
+- `automate GitHub PR creation from a Jira label`
+
+## How It Works
+
+1. **Poll** - every N minutes, the script calls `POST /rest/api/3/search/jql`
+   on the Jira Cloud instance to find open issues with the configured label.
+2. **Deduplicate** - on the first run the script records a `first_run_at`
+   baseline timestamp in the KV store; issues whose `updated` timestamp
+   predates that baseline are skipped (no backfill blast on first deploy).
+   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.
+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
+   duplicate work.
+
+The polling run is lightweight (Python stdlib only, no SDK install); LLM costs
+are incurred only when new issues are actually found.
+
+## Prerequisites
+
+| Requirement | Details |
+|---|---|
+| **Jira API token** | Stored as an OpenHands secret (see `references/setup.md`) |
+| **GitHub token** | Stored as an OpenHands secret with `repo` + `workflow` scope so the spawned conversation can push branches and open PRs |
+| **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 |
+
+## Quick Start
+
+See `SKILL.md` for the full step-by-step deployment guide, and
+`references/setup.md` for Jira API token creation, GitHub token scopes, cron
+schedule reference, and troubleshooting.

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

@@ -0,0 +1,216 @@
+---
+name: jira-issue-to-pr
+description: >
+  This skill should be used when the user asks to "set up a Jira automation to create pull requests",
+  "poll Jira for create-pr issues", "automatically create GitHub PRs from Jira tickets",
+  "deploy a Jira issue-to-PR automation", "create a Jira to GitHub PR workflow",
+  or mentions automating GitHub PR creation from a Jira label.
+  Deploys a cron-based OpenHands automation that watches a Jira Cloud project for issues
+  labeled with a configurable label (default: "create-pr") and spawns an agent conversation
+  to create a GitHub pull request for each new issue found. The target GitHub repository
+  is read from the body of the Jira ticket - no repo parameter is required at deploy time.
+---
+
+# Jira → GitHub PR Automation
+
+Deploys a cron automation that polls a Jira Cloud instance for open issues carrying a
+configurable label and, for each new issue, starts an OpenHands agent conversation that
+clones the GitHub repository specified in the ticket body, creates a branch, implements
+or placeholders the requested change, and opens a pull request. Once the conversation
+starts, it also posts a comment on the Jira ticket: "I'm on it: <conversation URL>".
+
+## How It Works
+
+1. **Poll** - every N minutes, `POST /rest/api/3/search/jql` on the Jira Cloud instance
+   to find open issues with the configured label.
+2. **Deduplicate** - on the very first run the script records a `first_run_at` baseline
+   timestamp in the KV store; any issue whose `updated` timestamp predates that baseline
+   is skipped (no backfill blast on first deploy). Using `updated` rather than `created`
+   means an old issue that has its label added after the automation is deployed will still
+   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.
+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.
+
+The polling run is lightweight (stdlib only, no SDK install); LLM costs are incurred only
+when new issues are actually found.
+
+## Prerequisites
+
+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 |
+| **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
+
+### Step 1 - Collect parameters
+
+Gather the following from the user before proceeding:
+
+| Parameter | Example | Notes |
+|---|---|---|
+| `jira_base_url` | `https://acme.atlassian.net` | No trailing slash |
+| `jira_email` | `alice@acme.com` | Atlassian account email for Basic auth |
+| `jira_token_secret` | `JIRA_CLOUD_KEY` | Name of the OpenHands secret holding the API token |
+| `jira_label` | `create-pr` | Label to watch for (optional, defaults to `create-pr`) |
+| `max_new_per_run` | `5` | Max conversations dispatched per cron firing (optional, defaults to `5`) |
+| `cron_schedule` | `*/5 * * * *` | Polling frequency in cron syntax |
+
+> **Note**: The GitHub repository is not configured here. Each Jira ticket body must include
+> a reference to the target GitHub repo in `owner/repo` format (e.g. `acme-org/backend`).
+> The spawned agent extracts it from the ticket text.
+
+### Step 2 - Create config.json
+
+Create `config.json` next to `scripts/main.py` when packaging:
+
+```json
+{
+  "jira_base_url":     "https://acme.atlassian.net",
+  "jira_email":        "alice@acme.com",
+  "jira_token_secret": "JIRA_CLOUD_KEY",
+  "jira_label":        "create-pr",
+  "max_new_per_run":   5
+}
+```
+
+### Step 3 - Package the tarball
+
+Copy `scripts/main.py` from this skill and package it with the `config.json`:
+
+```bash
+WORK=$(mktemp -d)
+cp <skill-dir>/scripts/main.py "$WORK/main.py"
+# write config.json into $WORK/config.json (see Step 2)
+tar -czf /tmp/jira-issue-to-pr.tar.gz -C "$WORK" .
+python3 -m py_compile "$WORK/main.py"   # validate syntax before uploading
+```
+
+### Step 4 - Upload the tarball
+
+```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" \
+  -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'])")
+```
+
+### 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" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"name\": \"Jira issue-to-PR Poller\",
+    \"trigger\": {
+      \"type\":     \"cron\",
+      \"schedule\": \"*/5 * * * *\",
+      \"timezone\": \"UTC\"
+    },
+    \"tarball_path\": \"$TARBALL_PATH\",
+    \"entrypoint\":   \"python3 main.py\",
+    \"timeout\":      540
+  }" | python3 -m json.tool
+```
+
+Save the returned `id` - use it for updates and monitoring.
+
+### Step 6 - Verify with a test dispatch
+
+```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
+
+# 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" \
+  | python3 -c "import sys,json; r=json.load(sys.stdin)['runs'][0]; print(r['status'], r.get('error_detail'))"
+```
+
+## Updating an Existing Deployment
+
+To change configuration or update the script:
+
+1. Edit `config.json` with new values.
+2. Repackage and upload a new tarball (Steps 3-4 above).
+3. PATCH the existing automation with the new `tarball_path`:
+
+```bash
+curl -s -X PATCH \
+  "http://localhost:8000/api/automation/v1/<AUTOMATION_ID>" \
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"tarball_path\": \"<NEW_TARBALL_PATH>\"}"
+```
+
+## Resetting Processed State
+
+To reprocess issues that were already handled (e.g., after testing), clear the KV store:
+
+```bash
+curl -s -X DELETE \
+  "http://localhost:8000/api/automation/v1/<KV_BASE>/v1/kv/state" \
+  -H "Authorization: Bearer $AUTOMATION_KV_TOKEN"
+```
+
+Or delete and recreate the automation to start with a clean state.
+
+## Script Reference
+
+The automation script lives at `scripts/main.py`. Key behaviors:
+
+- **No SDK dependencies** - pure Python stdlib; no `setup.sh` or `uv` install needed.
+- **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.
+- **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.
+- **Error transparency** - captures Jira HTTP response bodies in error messages for fast diagnosis.
+
+## Known Limitations
+
+### Pre-existing issues updated after deployment
+
+The deduplication filter compares each issue's `fields.updated` timestamp against
+`first_run_at`. `updated` is Jira's last-modified timestamp for the issue as a whole —
+it advances whenever **any** field changes (comments, priority, description, status, etc.),
+not only when the `create-pr` label is applied.
+
+This means a pre-existing issue that already carried the label at deployment time can
+slip through the filter if it is later updated for an unrelated reason (e.g. someone adds
+a comment), because its `updated` timestamp will have advanced past `first_run_at` while
+its key is not yet in `processed_keys`.
+
+**Workaround:** The only fully reliable way to detect exactly when a label was applied
+is the Jira changelog API (`GET /rest/api/3/issue/{key}/changelog`), which requires an
+extra HTTP call per issue. To avoid that overhead, keep the automation's scope narrow:
+use a label that is exclusively added as a PR-creation signal and is not already present
+on issues at the time of deployment.
+
+Once an issue is successfully dispatched its key is written to `processed_keys` in the
+KV store and is **permanently skipped on every future run** — regardless of subsequent
+label changes, comments, or any other updates to the issue. The only way to re-trigger a
+previously processed issue is to manually clear the KV store or delete and recreate the
+automation. This means the risk window described above is finite: as soon as the
+automation processes a pre-existing issue (even accidentally), it will never dispatch
+that issue again.
+
+## Additional Resources
+
+- **`references/setup.md`** - Jira API token creation, GitHub token scopes, cron schedule reference, and troubleshooting guide.

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

@@ -0,0 +1,170 @@
+# Setup & Troubleshooting Reference
+
+## Jira API Token
+
+### Create a token
+
+1. Log in to [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens).
+2. Click **Create API token**.
+3. Give it a label (e.g., `openhands-create-pr`) and click **Create**.
+4. Copy the token value - it is shown only once.
+
+### Store the token as an OpenHands secret
+
+Navigate to **Settings → Secrets** in the OpenHands UI and add a new secret:
+
+| Field | Value |
+|---|---|
+| Name | `JIRA_CLOUD_KEY` (or any name; set `jira_token_secret` in `config.json` to match) |
+| Value | The API token copied above |
+
+### How the script authenticates
+
+The script constructs an HTTP Basic auth header:
+
+```
+Authorization: Basic base64(<jira_email>:<jira_token>)
+```
+
+The Jira Cloud REST API v3 requires this for all authenticated requests.
+
+---
+
+## GitHub Token
+
+The spawned agent conversation clones the target repository, pushes a new branch, and
+opens a pull request. The GitHub token must be stored as an OpenHands secret and must
+have the following scopes:
+
+| Scope | Required for |
+|---|---|
+| `repo` | Clone private repos, push branches, read/write PR content |
+| `workflow` | Push changes that touch `.github/workflows/` files |
+
+The token does **not** need to be referenced in `config.json` - the spawned conversation
+inherits the user's configured secrets automatically through the agent server.
+
+### Store the token
+
+Navigate to **Settings → Secrets** and store the token under the name `GITHUB_TOKEN`
+(or whatever name is expected by the agent's GitHub skill).
+
+---
+
+## config.json Field Reference
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `jira_base_url` | ✅ | - | Full URL of your Atlassian instance, e.g. `https://acme.atlassian.net` |
+| `jira_email` | ✅ | - | Email address of the Atlassian account that owns the API token |
+| `jira_token_secret` | ❌ | `"JIRA_CLOUD_KEY"` | Name of the OpenHands secret holding the Jira API token |
+| `jira_label` | ❌ | `"create-pr"` | Jira issue label to watch for |
+
+> **GitHub repo**: not a config field. The target repository is read from the body of each
+> Jira ticket. Ticket authors must include the repo in `owner/repo` format or as a full
+> GitHub URL (e.g. `https://github.com/acme-org/backend`).
+
+---
+
+## Cron Schedule Reference
+
+| Schedule | Meaning |
+|---|---|
+| `*/5 * * * *` | Every 5 minutes |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 * * * *` | Every hour |
+| `0 9 * * 1-5` | Weekdays at 9 AM UTC |
+| `0 9,17 * * *` | Daily at 9 AM and 5 PM UTC |
+
+For high-frequency schedules (tighter than 15 minutes), consider that each run with new
+issues spawns one conversation per issue. Set `timeout` on the automation to something
+less than the interval to avoid overlapping runs - the KV store prevents double-processing
+even if runs do overlap.
+
+---
+
+## Jira Search API Notes
+
+The script uses `POST /rest/api/3/search/jql` - the current non-deprecated Jira Cloud
+search endpoint. All older endpoints return 410 Gone:
+
+| Removed endpoint | Returns |
+|---|---|
+| `GET /rest/api/2/search` | 410 Gone |
+| `GET /rest/api/3/search` | 410 Gone |
+| `POST /rest/api/3/search` | 410 Gone |
+
+Reference: [Atlassian changelog CHANGE-2046](https://developer.atlassian.com/changelog/#CHANGE-2046)
+
+The `POST /rest/api/3/search/jql` request body:
+
+```json
+{
+  "jql":        "labels = \"create-pr\" AND statusCategory != Done",
+  "fields":     ["key", "summary", "description", "status"],
+  "maxResults": 50
+}
+```
+
+The response is `SearchAndReconcileResults`; the script reads the `issues` array from it.
+
+---
+
+## Troubleshooting
+
+### `Jira search failed 401`
+
+- Wrong email in `jira_email` - must match the Atlassian account that owns the token.
+- Token expired or revoked - create a new one at id.atlassian.com and update the secret.
+- Token copied with extra whitespace - secrets are stored/retrieved with `.strip()`.
+
+### `Jira search failed 403`
+
+- The Atlassian account does not have **Browse Projects** permission on the target project.
+- Grant the account project-level read access in Jira's project settings.
+
+### `Jira search failed 400` with `"The value 'xxx' does not exist for the field 'labels'"`
+
+- The label does not exist in Jira yet. Create at least one issue with that label first,
+  or create the label explicitly in **Jira Settings → Issues → Labels**.
+
+### Run completes but no conversation is started
+
+- All matching issues are already in `processed_keys`. Clear state or add a new issue.
+- The Jira project has issues with the label but all are in a Done status category.
+  The JQL filter is `statusCategory != Done` - reopen or create a fresh issue.
+
+### Conversation started but no PR appears
+
+- The spawned conversation inherits the user's agent/LLM settings. Check the conversation
+  in the OpenHands UI (it appears in the conversations list under the automation run).
+- The GitHub token may lack `repo` scope to push or open PRs.
+- The target repo's default branch may be protected; the token must have bypass permission,
+  or the PR should be created against a different base branch.
+
+### `fire_callback error` in output
+
+- Non-fatal. The automation service callback URL is unavailable (common in local dev).
+  This does not affect conversation dispatch.
+
+### KV store not available (state falls back to local file)
+
+- `AUTOMATION_KV_TOKEN` is not injected, meaning the deployment is not configured with a
+  KV secret. State is written to a local file under `$WORKSPACE_BASE/../automation-state/`.
+  This is lost between runs in cloud pod deployments - configure the KV store secret on
+  the automation service to get persistent state.
+
+---
+
+## Multiple Deployments
+
+To watch multiple Jira projects or multiple GitHub repos, deploy separate automations —
+one per `config.json`. Each automation has its own KV-store namespace (keyed by
+automation ID), so processed-key sets do not cross-contaminate.
+
+Example: two automations, one per project:
+
+| Automation name | `jira_base_url` | `jira_label` | GitHub repo (in ticket body) |
+|---|---|---|---|
+| `Jira issue-to-PR - frontend` | `https://acme.atlassian.net` | `create-pr` | `acme/frontend` (written by ticket author) |
+| `Jira issue-to-PR - backend` | `https://acme.atlassian.net` | `create-pr-backend` | `acme/backend` (written by ticket author) |