@openhands/agent-canvas 1.0.0-rc.7 → 1.0.0-rc.9

package/dist/node_modules/@openhands/extensions/skills/index.cjs

@@ -1290,82 +1290,225 @@ curl -X POST \\
 7. Keep the review body brief (details go in inline comments)
 8. If no issues: post a short approval message with no inline comments`},{name:`github-pr-reviewer`,description:`Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed files, tests, and existing discussion via GitHub MCP, then posts a concise review highlighting risks, security issues, missing tests, and next steps.`,triggers:[`/pr-reviewer:setup`],content:`# GitHub PR Reviewer Automation
 
-Set up a cron or event-triggered automation that reviews GitHub pull requests.
+Create a cron automation that polls a GitHub repository, reviews each open
+pull request exactly once, and posts the AI review as a GitHub comment.
+
+The automation script is fully deterministic: PR discovery, state tracking,
+and deduplication are handled in Python. The LLM is only invoked to write
+the review text for PRs not yet seen, never for orchestration.
 
 ---
 
 ## Prerequisites
 
-### Required integration
+### Required secret
 
-- **GitHub MCP** must be installed in Settings → MCP.
+Verify that the following secret is set in **OpenHands Settings → Secrets**:
 
-### Information to collect
+| Secret name | Token type | Minimum permissions |
+|---|---|---|
+| \`GITHUB_PERSONAL_ACCESS_TOKEN\` | Classic PAT | \`repo\` (private) or \`public_repo\` (public) |
+| \`GITHUB_PERSONAL_ACCESS_TOKEN\` | Fine-grained PAT | Pull requests: Read and Write |
 
-Ask the user for:
+Check with:
+\`\`\`bash
+curl -s https://api.github.com/user \\
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \\
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))"
+\`\`\`
 
-1. **Repositories** — which repos should be watched (e.g. \`myorg/backend\`, \`myorg/frontend\`)
-2. **Trigger type** — event-based (reacts to \`pull_request.opened\` / \`pull_request.synchronize\`) or cron-based polling
-3. **Review tone** — thorough, concise, or friendly
-4. **Auto-post or draft** — should reviews be posted as GitHub comments automatically, or saved as draft artifacts for human approval first?
-5. **Filters** — any label, branch, or author filters (e.g. skip drafts, only review PRs with \`needs-review\` label)
+If the token is missing or invalid, inform the user and stop.
 
 ---
 
 ## Setup Workflow
 
-### Step 1 — Verify GitHub MCP access
+Follow these steps in order.
+
+### Step 1 — Verify GITHUB_PERSONAL_ACCESS_TOKEN
+
+Run the \`curl\` check above.
+
+- If absent: *"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in
+  OpenHands Settings → Secrets."* Stop.
+- If the API returns \`{"message": "Bad credentials"}\`: tell the user the
+  token is invalid and ask them to update it. Stop.
+
+### Step 2 — Collect repository
 
-Confirm the GitHub MCP integration is working:
+Ask: *"Which GitHub repository should be monitored?
+(Format: \`owner/repo\`, e.g. \`myorg/backend\`)"*
+
+Validate access:
+\`\`\`bash
+curl -s "https://api.github.com/repos/{owner}/{repo}" \\
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \\
+  | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+if 'message' in d:
+    print('ERROR:', d['message'])
+else:
+    print(f\\"Accessible. Private: {d.get('private')}. Permissions: {d.get('permissions')}\\")
+"
 \`\`\`
-Use the GitHub MCP to list recent pull requests in one of the target repositories.
+
+Record \`REPO = "{owner}/{repo}"\`.
+
+### Step 3 — Collect review tone
+
+Ask: *"What review tone should the reviewer use?
+  1. Thorough (default) — comprehensive coverage of correctness, security, tests, style
+  2. Concise — high-signal only, skips minor style feedback
+  3. Friendly — constructive and encouraging
+(Press Enter for Thorough, or type your choice or any custom style description)"*
+
+Map the choice to \`REVIEW_TONE\`:
+
+| Answer | \`REVIEW_TONE\` | \`REVIEW_STYLE_INSTRUCTIONS\` |
+|--------|--------------|------------------------------|
+| 1 / Enter | \`"thorough"\` | \`""\` |
+| 2 | \`"concise"\` | \`""\` |
+| 3 | \`"friendly"\` | \`""\` |
+| Custom text (e.g. "hostile pirate") | \`"thorough"\` | the custom text verbatim |
+
+### Step 4 — Collect cron schedule
+
+Ask: *"How often should the automation poll for new PRs?
+(Press Enter for the default: every 5 minutes.
+Use a cron expression for a different interval, e.g. \`0 * * * *\` = hourly)"*
+
+Default: \`*/5 * * * *\`.
+
+Record as \`CRON_SCHEDULE\`.
+
+### Step 5 — Generate the automation script
+
+Read \`scripts/main.py\` from this skill's directory. Apply exactly four
+constant substitutions near the top of the file:
+
+| Placeholder | Replace with |
+|---|---|
+| \`REPO = "owner/repo"\` | \`REPO = "{owner_repo}"\` |
+| \`REVIEW_TONE = "thorough"\` | \`REVIEW_TONE = "{review_tone}"\` |
+| \`REVIEW_STYLE_INSTRUCTIONS = ""\` | \`REVIEW_STYLE_INSTRUCTIONS = "{style_instructions}"\` |
+| \`DEFAULT_OPENHANDS_URL = "http://localhost:8000"\` | leave unchanged unless the user has a preference |
+
+Write the customised script to a temporary build directory:
+\`\`\`bash
+mkdir -p /tmp/pr-reviewer-build
+# write the customised main.py to /tmp/pr-reviewer-build/main.py
 \`\`\`
 
-If it fails, tell the user to install the GitHub MCP integration first.
+Validate syntax before packaging:
+\`\`\`bash
+python3 -m py_compile /tmp/pr-reviewer-build/main.py && echo "Syntax OK"
+\`\`\`
 
-### Step 2 — Determine trigger type
+Fix any syntax errors before proceeding.
 
-**Event-based (recommended if publicly reachable):**
-Check \`<RUNTIME_SERVICES>\` for deployment reachability. If the deployment has a public URL, recommend an event trigger on \`pull_request.opened\` and \`pull_request.synchronize\`.
+### Step 6 — Package and upload
 
-**Cron-based (local/private deployments):**
-If the deployment is local, set up a cron schedule (e.g. every 5 minutes) that polls for recently updated PRs.
+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\`
 
-### Step 3 — Build the review prompt
+\`\`\`bash
+tar -czf /tmp/pr-reviewer.tar.gz -C /tmp/pr-reviewer-build .
 
-Construct a prompt for the automation that includes:
-- The user's chosen repositories
-- Review focus areas (correctness, security, tests, maintainability)
-- Review tone preference
-- Whether to auto-post or draft
+TARBALL_PATH=$(curl -s -X POST \\
+  "\${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-pr-reviewer" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/gzip" \\
+  --data-binary @/tmp/pr-reviewer.tar.gz \\
+  | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")
 
-### Step 4 — Create the automation
+echo "Uploaded: $TARBALL_PATH"
+\`\`\`
 
-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\`
+### Step 7 — Register the automation
 
-Use the **prompt preset** endpoint:
 \`\`\`bash
-curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \\
+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 PR Reviewer",
-    "prompt": "<constructed review prompt>",
-    "trigger": <trigger config from step 2>
-  }'
+  -d "{
+    \\"name\\": \\"GitHub PR Reviewer: {owner}/{repo}\\",
+    \\"trigger\\": {\\"type\\": \\"cron\\", \\"schedule\\": \\"{cron_schedule}\\"},
+    \\"tarball_path\\": \\"$TARBALL_PATH\\",
+    \\"entrypoint\\": \\"python3 main.py\\",
+    \\"timeout\\": 300
+  }" | python3 -m json.tool
 \`\`\`
 
-### Step 5 — Confirm
+Record the returned \`id\`.
+
+### Step 8 — Confirm
 
 Tell the user:
+
 > ✅ **GitHub PR Reviewer** is running!
 >
 > - Automation ID: \`{id}\`
-> - Repositories: \`{repo list}\`
-> - Trigger: \`{trigger description}\`
-> - Review style: \`{tone}\`, \`{auto-post or draft}\``},{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`],content:`# GitHub Repository Monitor
+> - Repository: \`{owner}/{repo}\`
+> - Review tone: \`{tone}\`
+> - Polling schedule: \`{cron_schedule}\`
+> - State file: \`~/.openhands/workspaces/automation-state/github_pr_reviewer_{id}.json\`
+>
+> The next cron run will discover all currently open PRs and queue reviews.
+> Each PR is reviewed exactly once; state is stored in the JSON file above.
+> To force a re-review of all PRs, delete the state file.
+
+---
+
+## 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_PERSONAL_ACCESS_TOKEN\`** — aborts
+   immediately if absent or invalid.
+3. **Lists all open PRs** in the configured repository.
+4. **For each PR not yet in state**:
+   - Fetches the unified diff via the GitHub API.
+   - Skips PRs whose diff exceeds \`MAX_DIFF_LINES_SKIP\` (default 5000 lines)
+     and posts an explanatory comment.
+   - Truncates diffs larger than \`MAX_DIFF_LINES\` (default 500 lines) and
+     notes this in the prompt.
+   - Creates an OpenHands conversation with the PR metadata, diff, and
+     configured tone instructions as the initial message.
+   - Posts an acknowledgement comment on the PR with a link to the conversation.
+   - Records the PR in state with \`status: "active"\`.
+5. **For each active conversation**:
+   - Skips PRs that have been closed or merged (marks them closed silently).
+   - Checks the conversation's \`execution_status\`.
+   - When it reaches \`idle\`, \`finished\`, \`error\`, or \`stuck\`:
+     posts the agent's final response as a GitHub comment and marks the
+     conversation \`closed\`.
+6. **Saves updated state** and fires the completion callback.
+
+---
+
+## Additional Resources
+
+- **\`references/state-schema.md\`** — State JSON schema, field definitions,
+  and conversation lifecycle diagram.
+- **\`scripts/main.py\`** — The complete automation script. Customise the
+  four constants at the top before packaging.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Bot never posts reviews | \`GITHUB_PERSONAL_ACCESS_TOKEN\` missing or wrong scopes | Verify token; check Step 1 |
+| "Bad credentials" in run logs | Token expired | Rotate and update the secret |
+| 404 on repo access | Repo name wrong or no access | Re-check \`owner/repo\` and token permissions |
+| Same PR reviewed twice | State file deleted or corrupted | Check that the state file path is stable across runs |
+| Review never posted | Conversation stuck in \`running\` | Open the conversation in the OpenHands UI |
+| PR skipped silently | Diff too large | Raise \`MAX_DIFF_LINES_SKIP\` in the script or split the PR |`},{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`],content:`# GitHub Repository Monitor
 
 Create a cron automation that polls a single GitHub repository on a
 configurable schedule (default: every minute).
@@ -4217,6 +4360,7 @@ Source: [\`examples/\`](https://github.com/OpenHands/software-agent-sdk/tree/mai
 - [\`50_async_cancellation.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/50_async_cancellation.py)
 - [\`51_agent_hooks\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/51_agent_hooks)
 - [\`52_dynamic_workflow.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/52_dynamic_workflow.py)
+- [\`53_client_defined_tools.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/53_client_defined_tools.py)
 
 ### [\`02_remote_agent_server/\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server)
 
@@ -4233,6 +4377,8 @@ Source: [\`examples/\`](https://github.com/OpenHands/software-agent-sdk/tree/mai
 - [\`11_conversation_fork.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/11_conversation_fork.py)
 - [\`12_settings_and_secrets_api.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/12_settings_and_secrets_api.py)
 - [\`13_workspace_get_llm.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/13_workspace_get_llm.py)
+- [\`14_client_defined_tools.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/14_client_defined_tools.py)
+- [\`15_openai_compatible_gateway.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/15_openai_compatible_gateway.py)
 - [\`hook_scripts\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server/hook_scripts)
 - [\`scripts\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server/scripts)