@openhands/extensions 0.0.1-alpha → 0.2.0

package/skills/github-repo-monitor/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: github-repo-monitor
+description: >
+  This skill should be used when the user asks to "monitor a GitHub repository",
+  "watch GitHub for issues or PRs", "respond to @OpenHands mentions on GitHub",
+  "set up an OpenHands GitHub integration", "trigger OpenHands from a GitHub
+  comment", or "poll a GitHub repo for a trigger phrase". Guides the user
+  through creating a cron automation that polls a single repository and starts
+  an OpenHands conversation whenever a configurable trigger phrase is detected
+  in an issue or PR comment.
+triggers:
+  - /github-monitor:poll
+---
+
+# GitHub Repository Monitor
+
+Create a cron automation that polls a single GitHub repository on a
+configurable schedule (default: every minute).
+
+When a comment on an issue or PR contains the **trigger phrase**
+(default: `@OpenHands`) it:
+
+1. Posts a GitHub comment acknowledging the request with a conversation link.
+2. Creates an OpenHands conversation pre-loaded with the issue/PR title, body,
+   labels, and recent comment history for full context.
+3. Posts a summary GitHub comment when the conversation finishes.
+
+On every subsequent run:
+- New trigger comments on an already-tracked issue/PR are forwarded to the
+  running conversation (or re-open a previously closed one).
+- When a conversation goes idle/finished/error the agent's final response
+  is posted back as a GitHub comment.
+
+> **Local mode only.** This automation targets the local OpenHands setup
+> (`dev:automation` stack). A cloud/webhook variant is out of scope here.
+
+---
+
+## Prerequisites
+
+### Required secret
+
+Verify that the following secret is set in **OpenHands Settings → Secrets**
+before proceeding:
+
+| Secret name | Token type | Minimum permissions |
+|---|---|---|
+| `GITHUB_TOKEN` | Classic PAT | `repo` (private repos) or `public_repo` (public repos) |
+| `GITHUB_TOKEN` | Fine-grained PAT | Issues: Read and Write |
+
+Check with:
+```bash
+curl -s https://api.github.com/user \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))"
+```
+
+If the token is missing, inform the user and stop — the automation cannot
+function without GitHub credentials.
+
+### Optional secret
+
+| Secret name | Default | Purpose |
+|---|---|---|
+| `OPENHANDS_URL` | `http://localhost:8000` | Base URL used to build conversation links in GitHub comments |
+
+---
+
+## Setup Workflow
+
+Follow these steps in order.
+
+### Step 1  -  Verify GITHUB_TOKEN
+
+Fetch the secret and run the `curl` check above.
+
+- If the secret is absent: tell the user
+  *"GITHUB_TOKEN is not set. Please add it in OpenHands Settings → Secrets
+  (classic PAT with `repo` or `public_repo` scope, or a fine-grained PAT
+  with Issues: Read and Write)."* Then stop.
+
+- If the API returns a non-200 or `{"message": "Bad credentials"}`:
+  tell the user the token is invalid and ask them to update it.
+
+### Step 2  -  Collect repository
+
+Ask the user: *"Which GitHub repository should be monitored?
+(Format: `owner/repo`, e.g. `microsoft/vscode`)"*
+
+Validate access and write permissions:
+
+```bash
+curl -s "https://api.github.com/repos/{owner}/{repo}" \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+if 'message' in d:
+    print('ERROR:', d['message'])
+else:
+    perms = d.get('permissions', {})
+    print(f\"Accessible. Private: {d.get('private')}. Permissions: {perms}\")
+"
+```
+
+- If `message: Not Found` or `message: Bad credentials` →
+  inform the user and ask them to check the repo name and token.
+- If the repo is private and `permissions.push` is `false` →
+  inform the user the token does not have write access and comments will fail.
+- If the check passes, record `REPO = "{owner}/{repo}"`.
+
+### Step 3  -  Collect trigger phrase
+
+Ask the user: *"What trigger phrase should OpenHands respond to?
+(Press Enter to use the default: `@OpenHands`)"*
+
+Accepted values: any non-empty string unlikely to appear by accident.
+
+Record as `TRIGGER_PHRASE`. Default: `"@openhands"`.
+
+### Step 4  -  Collect allowed GitHub logins
+
+Ask the user: *"Which GitHub users may trigger this automation?
+Press Enter to allow only the authenticated `GITHUB_TOKEN` owner.
+You may also provide comma-separated GitHub logins, or `*` to allow any
+non-bot commenter on the monitored repository."*
+
+Map the answer to `ALLOWED_GITHUB_LOGINS`:
+
+| User answer | `ALLOWED_GITHUB_LOGINS` value |
+|---|---|
+| Empty/default | `["<TOKEN_OWNER>"]` |
+| `enyst,tofarr` | `["enyst", "tofarr"]` |
+| `*` | `["*"]` |
+
+Default to token-owner-only unless the user explicitly chooses a broader
+allowlist. Record as `ALLOWED_GITHUB_LOGINS`.
+
+### Step 5  -  Collect event types
+
+Ask the user: *"Which event types should be monitored?
+Choose one or more:*
+  *1. Issue and PR comments (default)*
+  *2. PR inline review comments*
+  *3. Both*
+*(Press Enter to accept the default: issue and PR comments.)"*
+
+Map the choice to the `EVENT_TYPES` list:
+
+| Choice | `EVENT_TYPES` value |
+|---|---|
+| 1 (default) | `["issue_comment"]` |
+| 2 | `["pr_review_comment"]` |
+| 3 | `["issue_comment", "pr_review_comment"]` |
+
+### Step 6  -  Collect cron schedule
+
+Ask the user: *"How often should the automation poll GitHub?
+(Press Enter for the default: every minute.
+Use a cron expression for a different interval, e.g.:
+`*/5 * * * *` = every 5 minutes,
+`0 * * * *` = every hour)"*
+
+Default: `* * * * *` (every minute).
+
+Record as `CRON_SCHEDULE`.
+
+### Step 7  -  Generate the automation script
+
+Read `scripts/main.py` from this skill's directory. Apply exactly five
+constant substitutions near the top of the file:
+
+| Placeholder | Replace with |
+|---|---|
+| `REPO = "owner/repo"` | `REPO = "{owner_repo}"` |
+| `TRIGGER_PHRASE = "@openhands"` | `TRIGGER_PHRASE = "{trigger_phrase_lower}"` |
+| `EVENT_TYPES = ["issue_comment"]` | `EVENT_TYPES = {event_types_list}` |
+| `ALLOWED_GITHUB_LOGINS = ["<TOKEN_OWNER>"]` | `ALLOWED_GITHUB_LOGINS = {allowed_logins_list}` |
+| `DEFAULT_OPENHANDS_URL = "http://localhost:8000"` | `DEFAULT_OPENHANDS_URL = "{url}"` (keep default if the user has no preference) |
+
+Write the customised script to a temporary build directory:
+```bash
+mkdir -p /tmp/github-monitor-build
+# (write the customised main.py to /tmp/github-monitor-build/main.py)
+```
+
+Validate syntax before packaging:
+```bash
+python3 -m py_compile /tmp/github-monitor-build/main.py && echo "Syntax OK"
+```
+
+Fix any syntax errors before proceeding.
+
+### Step 8  -  Package and upload
+
+Determine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`
+block in your system context:
+- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`
+- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`
+
+If no Automation backend is listed in `<RUNTIME_SERVICES>`, stop and tell
+the user to start the full automation stack.
+
+```bash
+tar -czf /tmp/github-monitor.tar.gz -C /tmp/github-monitor-build .
+
+# OPENHANDS_HOST: read from <RUNTIME_SERVICES> Automation backend url_from_agent
+OPENHANDS_HOST="<automation-url-from-runtime-services>"
+
+TARBALL_PATH=$(curl -s -X POST \
+  "${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-repo-monitor" \
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "Content-Type: application/gzip" \
+  --data-binary @/tmp/github-monitor.tar.gz \
+  | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")
+
+echo "Uploaded: $TARBALL_PATH"
+```
+
+### Step 9  -  Create the automation
+
+```bash
+curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1" \
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"name\": \"GitHub Monitor: {owner}/{repo}\",
+    \"trigger\": {\"type\": \"cron\", \"schedule\": \"{cron_schedule}\"},
+    \"tarball_path\": \"$TARBALL_PATH\",
+    \"entrypoint\": \"python3 main.py\",
+    \"timeout\": 55
+  }" | python3 -m json.tool
+```
+
+Record the returned `id`.
+
+### Step 10  -  Confirm
+
+Tell the user:
+
+> ✅ **GitHub Repository Monitor** is running!
+>
+> - Automation ID: `{id}`
+> - Repository: `{owner}/{repo}`
+> - Trigger phrase: `{phrase}`
+> - Event types: `{event_types}`
+> - Allowed GitHub logins: `{allowed_logins}`
+> - Polling schedule: `{cron_schedule}`
+> - State file: `~/.openhands/workspaces/automation-state/github_poller_{id}.json`
+>
+> From an allowed GitHub login, post a comment containing `{phrase}` on any
+> issue or PR in `{owner}/{repo}` to test it. OpenHands will acknowledge with
+> a comment and a link to the new conversation.
+
+---
+
+## Runtime Behaviour (per poll)
+
+Each cron run executes `main.py`, which:
+
+1. **Loads state** from the JSON file (see `references/state-schema.md`).
+2. **Resolves and validates GITHUB_TOKEN** — aborts immediately if absent or invalid.
+3. **Polls for new events** since the previous `last_poll` timestamp:
+   - `GET /repos/{owner}/{repo}/issues/comments?since=…` for `issue_comment`
+   - `GET /repos/{owner}/{repo}/pulls/comments?since=…` for `pr_review_comment`
+4. **Processes matching comments** in chronological order:
+   - Skips bot accounts (login ending in `[bot]`) to avoid feedback loops.
+   - Skips already-processed comment IDs.
+   - Skips comments from logins outside `ALLOWED_GITHUB_LOGINS`.
+   - Checks body for the trigger phrase (case-insensitive).
+   - Extracts the issue/PR number from the comment URL.
+5. **For each trigger comment**, per issue/PR:
+   - **Active conversation** → forwards the new comment directly.
+   - **Closed conversation** → tries to re-open it; falls back to creating
+     a new conversation if the old one is unreachable.
+   - **No conversation** → fetches full context (title, body, labels, last
+     10 comments) and creates a new conversation with a detailed prompt.
+   - Posts a GitHub comment: *"🤖 OpenHands is on it! View progress: {url}"*
+6. **Checks active conversations** for completion:
+   - If `status ∈ {idle, finished, error, stuck}` and enough time has passed
+     since creation (debounce), fetches the agent's final response and posts
+     it as a GitHub comment. Marks the conversation `closed`.
+7. **Saves state** and fires the completion callback.
+
+---
+
+## Additional Resources
+
+### Reference Files
+
+- **`references/state-schema.md`**  -  State JSON schema, field definitions,
+  and conversation lifecycle diagram.
+- **`references/github-api.md`**  -  GitHub API endpoint reference, token
+  scopes, rate limits, and common error codes.
+
+### Script Template
+
+- **`scripts/main.py`**  -  The complete automation script. Customise the four
+  constants at the top (`REPO`, `TRIGGER_PHRASE`, `EVENT_TYPES`,
+  `DEFAULT_OPENHANDS_URL`) before packaging.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Bot doesn't respond to comments | `GITHUB_TOKEN` missing or wrong scopes | Verify token with `curl /user`; check scopes in Step 1 |
+| "Bad credentials" in run logs | Token expired | Rotate token and update the secret in Settings |
+| 404 on repo access | Repo name wrong or token has no access | Re-check `owner/repo` spelling; add token as collaborator |
+| Comments posted but no conversation created | Agent server URL wrong | Check `OPENHANDS_URL` secret and `AGENT_SERVER_URL` env var |
+| Same comment processed twice | `processed_comment_ids` cleared | State file was deleted; harmless but duplicate comment may appear |
+| Summary never posted | Conversation stuck in `running` | Open the conversation in the OpenHands UI; agent may need input |
+| No events detected after first run | `last_poll` in the future | Delete the state file to reset; it will be recreated on next run |

package/skills/github-repo-monitor/commands/github-monitor:poll.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: This skill should be used when the user asks to "monitor a GitHub repository", "watch GitHub for issues or PRs", "respond to @OpenHands mentions on GitHub", "set up an OpenHands GitHub integration", "trigger OpenHands from a GitHub comment", or "poll a GitHub repo for a trigger phrase". Guides the user through creating a cron automation that polls a single repository and starts an OpenHands conversation whenever a configurable trigger phrase is detected in an issue or PR comment.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/skills/github-repo-monitor/references/github-api.md

@@ -0,0 +1,241 @@
+# GitHub API Reference
+
+Quick reference for the endpoints, authentication, and rate limits used by
+the GitHub Repository Monitor automation.
+
+---
+
+## Authentication
+
+All requests use Bearer authentication:
+
+```
+Authorization: Bearer {GITHUB_TOKEN}
+Accept: application/vnd.github+json
+X-GitHub-Api-Version: 2022-11-28
+```
+
+---
+
+## Token Types and Required Scopes
+
+### Classic Personal Access Token
+
+| Scope | Grants |
+|-------|--------|
+| `repo` | Full access to private and public repos (read + write issues/PRs) |
+| `public_repo` | Write access to public repos only (sufficient for public repos) |
+
+### Fine-Grained Personal Access Token
+
+| Permission | Level |
+|------------|-------|
+| Issues | Read and Write |
+| Pull requests | Read (optional, for fetching PR metadata) |
+
+### Checking Token Scopes
+
+```bash
+curl -I https://api.github.com/user \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  | grep -i x-oauth-scopes
+# X-OAuth-Scopes: repo, public_repo
+```
+
+Fine-grained PATs do not return `X-OAuth-Scopes`; the script relies on the
+`permissions` field in the repo response instead.
+
+---
+
+## Endpoints Used
+
+### Verify token identity
+
+```
+GET /user
+```
+
+Returns the authenticated user. Use to verify the token is valid.
+
+---
+
+### Verify repo access and permissions
+
+```
+GET /repos/{owner}/{repo}
+```
+
+Key fields in the response:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `private` | bool | Whether the repo is private |
+| `permissions.push` | bool | Token has write access (required for private repos) |
+| `permissions.pull` | bool | Token has read access |
+| `full_name` | string | `owner/repo` |
+
+Error codes:
+- `404` — Repo not found or token has no read access.
+- `403` — Token exists but is blocked from this resource.
+
+---
+
+### Poll issue and PR comments
+
+```
+GET /repos/{owner}/{repo}/issues/comments
+  ?since={ISO 8601 UTC}
+  &sort=created
+  &direction=asc
+  &per_page=100
+  &page={n}
+```
+
+Returns all comments on issues **and** PRs (PRs are a superset of issues in
+GitHub's API). The `since` parameter filters to comments created **at or
+after** the given timestamp.
+
+Key fields per comment:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Integer comment ID (used for deduplication) |
+| `body` | Comment text |
+| `user.login` | Author username |
+| `user.type` | `"User"` or `"Bot"` |
+| `created_at` | ISO 8601 UTC creation timestamp |
+| `html_url` | Direct link to the comment |
+| `issue_url` | API URL of the parent issue/PR (extract number from last path segment) |
+
+---
+
+### Poll PR inline review comments
+
+```
+GET /repos/{owner}/{repo}/pulls/comments
+  ?since={ISO 8601 UTC}
+  &sort=created
+  &direction=asc
+  &per_page=100
+  &page={n}
+```
+
+Returns inline review comments on PR diffs.
+
+Key fields per comment:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Integer comment ID |
+| `body` | Comment text |
+| `user.login` | Author username |
+| `pull_request_url` | API URL of the parent PR (extract number from last path segment) |
+| `path` | File path the comment was left on |
+| `line` | Line number in the file (nullable) |
+| `created_at` | ISO 8601 UTC creation timestamp |
+
+---
+
+### Fetch issue/PR metadata
+
+```
+GET /repos/{owner}/{repo}/issues/{issue_number}
+```
+
+Works for both issues and pull requests. To distinguish:
+- Response contains `pull_request` key → it's a PR.
+- No `pull_request` key → it's a regular issue.
+
+Key fields:
+
+| Field | Description |
+|-------|-------------|
+| `number` | Issue/PR number |
+| `title` | Title string |
+| `body` | Description text (can be null) |
+| `state` | `"open"` or `"closed"` |
+| `html_url` | Browser URL |
+| `labels[].name` | Label names |
+| `pull_request.url` | Present only if this is a PR |
+
+---
+
+### Fetch recent comments for context
+
+```
+GET /repos/{owner}/{repo}/issues/{issue_number}/comments
+  ?per_page=100
+```
+
+Returns all issue/PR comments in chronological order. The script fetches
+all pages and takes the last `CONTEXT_COMMENT_LIMIT` (default 10) entries.
+
+---
+
+### Post a comment
+
+```
+POST /repos/{owner}/{repo}/issues/{issue_number}/comments
+
+Body: { "body": "comment text (Markdown supported)" }
+```
+
+Works for both issues and PRs. Returns the created comment object including
+its `id` and `html_url`.
+
+Error codes:
+- `403` — Token lacks write permission.
+- `404` — Repo or issue not found.
+- `410` — Issue is locked; comments are disabled.
+
+---
+
+## Rate Limits
+
+| Tier | Limit | Notes |
+|------|-------|-------|
+| Authenticated requests | 5,000 / hour | Per token |
+| Search API | 30 / minute | Not used by this script |
+| Secondary rate limit | Varies | Triggered by rapid POST bursts; unlikely at 1-min polling |
+
+At one poll per minute on a moderately active repo:
+- ~2 GET calls per run baseline (user + repo)
+- ~1–3 additional GETs per trigger event (issue context + comment history)
+- ~1–2 POSTs per trigger event (acknowledgement comment + optional summary)
+
+Typical usage: **< 20 requests/hour** for a quiet repo,
+**< 300 requests/hour** for a very active repo (still well within the 5,000 limit).
+
+Check remaining quota with:
+```bash
+curl -s https://api.github.com/rate_limit \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+core = d['resources']['core']
+print(f\"Remaining: {core['remaining']}/{core['limit']}  Reset: {core['reset']}\")
+"
+```
+
+---
+
+## Common Error Codes
+
+| Code | Meaning | Typical fix |
+|------|---------|-------------|
+| 401 | Bad credentials / token expired | Rotate token; update the secret |
+| 403 | Forbidden (scope missing or repo blocked) | Add required scope; check org SSO |
+| 404 | Resource not found or no read access | Check repo name; ensure token has access |
+| 410 | Gone (issue locked or deleted) | Harmless — skip this issue |
+| 422 | Unprocessable entity (e.g., body too long) | Truncate comment body |
+| 429 | Rate limit hit (secondary) | Slow down; add sleep between requests |
+
+---
+
+## Bot Detection
+
+GitHub sets `user.type = "Bot"` for GitHub Apps and some bots. Classic bot
+accounts (created as regular users) may instead have logins ending in
+`[bot]` (e.g. `dependabot[bot]`). The script skips both patterns to avoid
+feedback loops with other automation.