@openhands/extensions 0.23.0 → 0.24.0

package/skills/github-pr-reviewer/README.md

@@ -14,7 +14,12 @@ This skill is activated by:
 - Reviews PRs on demand from a GitHub reviewer request or label event
 - Watches several repositories from a single automation, each with its own state
 - Processes each review request or label application idempotently
-- Supports re-review by requesting the bot again or re-applying the label
+- Supports re-review by requesting the bot again or re-applying the label. Each
+  explicit request refreshes mutable GitHub state (head, PR body, reviews,
+  comments, review requests, linked issues, and current-head checks) instead of
+  trusting what an earlier turn observed, so a same-head re-review sees a linked
+  issue that has since gained or lost readiness, or a check that has since moved.
+  Repository analysis already done, such as reading `AGENTS.md`, is retained
 - Suppresses stale reviews when the PR head commit changes mid-review
 - Hands the agent the reviewed commit already checked out, and removes that
   checkout when the review ends, so nothing accumulates between runs

package/skills/github-pr-reviewer/SKILL.md

@@ -29,6 +29,28 @@ state persistence, stale-result suppression, the repository checkout, and its
 removal are all handled in Python. The LLM is invoked only for the review
 itself.
 
+Each explicit review request - a re-applied trigger label, or a new reviewer
+request in event mode - is a fresh review. The conversation for a PR is reused,
+but its earlier turns must not be trusted as current: before deciding a verdict
+the reviewer re-fetches the mutable GitHub state (the exact head, the PR body,
+review comments and threads, review requests, the linked issues' bodies and
+labels, and the current-head Actions results) and ignores any earlier finding,
+verdict, or label/priority claim that state no longer supports. Repository
+analysis the conversation already did, such as reading `AGENTS.md`, stays
+useful and is not repeated.
+
+The review prompt starts with a scope gate: using the repository's own guidance
+(its scope categories and ownership boundaries, not a list of individual PR
+numbers), the reviewer decides whether the change belongs in this repository
+and has the product/architecture direction it needs. When it does not, the review
+stops with a single `event: COMMENT` review that says whether the change should
+move repositories, close, or receive a maintainer decision, and ends with the
+`🛑 MAINTAINER DECISION REQUIRED` verdict. That outcome is **neither an approval
+nor a change request**: it does not approve or merge the PR. The completion
+handler recognizes the verdict and requests one configured maintainer through the
+same handoff used after an approval. An in-scope change continues the existing
+review unchanged.
+
 The script prepares each review's workspace before the agent starts: the pull
 request's head commit is downloaded as a tarball and extracted to a directory of
 its own, which becomes the conversation's working directory. The agent is told
@@ -278,7 +300,8 @@ For each repository:
      paths, and symlinks skipped rather than materialised.
    - Starts an OpenHands conversation **whose working directory is that
      checkout**, with a review prompt carrying PR metadata, the exact head SHA,
-     and label event details.
+     label event details, and the requirement to re-fetch the current mutable
+     GitHub state before deciding a verdict.
    - Posts an acknowledgement comment with the label event, head SHA, and
      conversation link.
    - Records the review in state with `status: "active"` and the checkout path.

package/skills/github-pr-reviewer/scripts/main.py

@@ -52,6 +52,12 @@ REVIEW_STYLE_INSTRUCTIONS = ""
 REPO_REVIEW_GUIDE_PATH = ".agents/skills/custom-codereview-guide.md"
 DEFAULT_OPENHANDS_URL = "http://localhost:8000"
 
+# A review that ends with this marker is a scope stop: the reviewer found the
+# change out of scope, or needing a product/architecture decision, before the
+# technical review. The completion handler hands it to a maintainer without
+# approving or merging the PR.
+MAINTAINER_DECISION_VERDICT = "🛑 MAINTAINER DECISION REQUIRED"
+
 CONFIG_FILENAME = "config.json"
 
 # Config keys, paired with the type each must have. A wrong type is a hard
@@ -787,22 +793,45 @@ def _build_review_prompt(
         f"\nPR Description:\n---\n{body}\n---\n\n"
         "Required workflow:\n"
         f"1. {workspace}\n"
-        "2. Before reviewing, you MUST read the repository's own guidance to understand the repo first.\n"
+        "2. CURRENT STATE - treat this request as a fresh review, never a continuation of "
+        "earlier observations. Before the scope gate and before deciding any verdict, re-fetch "
+        "the current mutable GitHub state for this pull request and act only on what you read "
+        "now: whether the exact head still matches the Head SHA above, the current PR title and "
+        "body, the current review comments and threads, the current review requests, the current "
+        "GitHub Actions check results for that head, and the current body and labels of every "
+        "linked issue the PR references - a linked issue may have gained or lost a readiness "
+        "label (for example `ready-for-dev`) or changed priority since an earlier turn. If an "
+        "earlier turn in this conversation reviewed this PR or its linked issues, that analysis "
+        "and the repository guidance you read remain useful background, but every mutable fact "
+        "above must be re-established now; never repeat an earlier finding, verdict, or "
+        "label/priority claim that the state you just read does not support.\n"
+        f"   Use `gh` or GitHub REST API calls with `{github_token_secret}`; never print secret values.\n"
+        "3. Before reviewing, you MUST read the repository's own guidance to understand the repo first.\n"
         "   Read `AGENTS.md` at the repository root (and any nested `AGENTS.md` covering the "
         "changed files), plus other relevant docs when present - e.g. `CONTRIBUTING.md`, "
         "`CLAUDE.md`, `.cursorrules`, and any review or coding-guideline docs. Apply that "
         "guidance to your review.\n"
-        "   Then inspect the PR discussion, existing review comments, changed files, and the diff, "
-        "together with the surrounding code in the workspace.\n"
-        f"   Use `gh` or GitHub REST API calls with `{github_token_secret}`; never print secret values.\n"
-        "3. Ground every finding in the workspace code. Before using an inline location, verify that "
+        "4. SCOPE GATE - before inspecting changed files, reading the diff, or running any test, "
+        "use the repository guidance above (its scope categories and ownership boundaries) to decide "
+        "whether this change belongs in this repository and has the product/architecture direction "
+        "it needs. If it does, continue the technical review unchanged. If it does not, or needs a "
+        "product/architecture decision, stop here and publish exactly one review with "
+        f"`POST /repos/{repo}/pulls/{number}/reviews`, using `commit_id` equal to the Head SHA above "
+        "and `event: COMMENT`. Briefly say whether the change should move repositories, close, or "
+        "receive a maintainer decision; when it belongs elsewhere, name the likely owning repository "
+        "only if the evidence supports it. Do not run tests or report implementation findings. This "
+        "outcome is not an approval, and its body ends with the verdict on its own line: "
+        f"`{MAINTAINER_DECISION_VERDICT}`.\n"
+        "5. Otherwise continue the technical review. Inspect the PR discussion, existing review "
+        "comments, changed files, and the diff, together with the surrounding code in the workspace.\n"
+        "6. Ground every finding in the workspace code. Before using an inline location, verify that "
         "the path and line are part of this pull request's diff. Compare every changed branch with "
         "the base behavior, including side effects outside the reported bug; a revision, event, or "
         "delivery identifier proves only the inputs it actually includes, not that unrelated profile, "
         "credential, configuration, or external state stayed unchanged. Do not add speculative or "
         "out-of-scope notes: every blocking or non-blocking observation must identify demonstrated "
         "behavior on the current head and explain why it matters to the merge decision.\n"
-        f"4. Publish one review with `POST /repos/{repo}/pulls/{number}/reviews`, using "
+        f"7. Publish one review with `POST /repos/{repo}/pulls/{number}/reviews`, using "
         "`commit_id` equal to the Head SHA above. Use `event: APPROVE` when there are "
         "no material findings; otherwise use `event: COMMENT`. Never use "
         "`REQUEST_CHANGES`.\n"
@@ -813,19 +842,19 @@ def _build_review_prompt(
         "   Put the overall assessment in `body`, and each line-specific finding in the `comments` "
         "array with `path`, `line`, `side: RIGHT`, and `body`.\n"
         "   Only create inline comments for actionable findings; do not open praise or nitpick threads.\n"
-        "5. If a finding cannot be attached to a changed line, put it in the review body instead. "
+        "8. If a finding cannot be attached to a changed line, put it in the review body instead. "
         "If the API rejects the inline positions, retry with every finding in the body and no `comments` array. "
         "If GitHub forbids the configured bot from approving its own PR, retry the clean review with "
         "`event: COMMENT` and keep the approved verdict.\n"
-        "6. Begin the review body with this disclosure: "
+        "9. Begin the review body with this disclosure: "
         "`_This review was posted by an AI agent (OpenHands)._`\n"
-        "7. End the review body with a verdict on its own line: either `✅ APPROVED` "
+        "10. End the review body with a verdict on its own line: either `✅ APPROVED` "
         "or `🔄 CHANGES REQUESTED`.\n"
-        "8. If there are no material issues, still publish a review saying so, with the "
+        "11. If there are no material issues, still publish a review saying so, with the "
         "disclosure and the verdict.\n"
         f"\nReview instructions:\n{tone}{extra}{guide_section}\n\n"
         "After GitHub accepts the review, output exactly `GITHUB_REVIEW_POSTED`. "
-        "If publishing still fails after the fallback in step 5, output the complete review text "
+        "If publishing still fails after the fallback in step 8, output the complete review text "
         "so it can be posted as a comment instead."
     )
 

package/skills/github-pr-reviewer/scripts/worker.py

@@ -123,7 +123,10 @@ class PullRequestReviewer(GitHubRepository):
             "the repository's appropriate focused tests in the workspace. Do not "
             "modify tracked files.\n"
             f"- Re-read {self.repository} PR #{number} immediately before reporting. "
-            f"If its head is no longer `{sha}`, {moved_head_instruction}.\n"
+            "Confirm its current body, labels, review threads, and the head's check "
+            "results, and re-read every linked issue's current body and labels: an "
+            "issue's readiness or priority may have changed since an earlier turn. "
+            f"If the head is no longer `{sha}`, {moved_head_instruction}.\n"
             f"- {trigger_completion} after completing any configured "
             "human-review handoff. Never paste JSON artifacts or full command logs "
             "into comments.\n"
@@ -148,6 +151,7 @@ class PullRequestReviewer(GitHubRepository):
         if not completed:
             return False
         approved = None
+        maintainer_decision = False
         for review in sorted(
             completed, key=lambda item: item["submitted_at"], reverse=True
         ):
@@ -158,9 +162,14 @@ class PullRequestReviewer(GitHubRepository):
             if body.endswith("🔄 CHANGES REQUESTED"):
                 approved = False
                 break
-        if approved is None:
+            if body.endswith(workflow.MAINTAINER_DECISION_VERDICT):
+                maintainer_decision = True
+                break
+        if approved is None and not maintainer_decision:
             return False
-        if approved:
+        # A scope stop is not an approval: it requests the maintainer decision
+        # the change is missing, through the same handoff as an approval.
+        if approved or maintainer_decision:
             maintainers = parse_maintainers(self.config.get("maintainers"))
             if maintainers:
                 try:

package/skills/github-pr-reviewer/tests/test_main.py

@@ -538,6 +538,75 @@ class TestRepoReviewGuide(unittest.TestCase):
         self.assertIn("Do not add speculative or out-of-scope notes", prompt)
         self.assertIn("forbids the configured bot from approving its own PR", prompt)
 
+    def test_prompt_requires_refreshing_mutable_github_state(self):
+        """A resumed conversation must not trust an earlier turn's observations."""
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        assert "CURRENT STATE" in prompt
+        for surface in (
+            "still matches the Head SHA",
+            "current PR title and body",
+            "current review comments and threads",
+            "current review requests",
+            "GitHub Actions check results",
+            "body and labels of every linked issue",
+        ):
+            self.assertIn(surface, prompt)
+        # The readiness case from the report: a linked issue gaining a label.
+        self.assertIn("ready-for-dev", prompt)
+
+    def test_prompt_forbids_repeating_an_earlier_observation(self):
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        self.assertIn("fresh review", prompt)
+        self.assertIn("re-established now", prompt)
+        self.assertIn(
+            "never repeat an earlier finding, verdict, or "
+            "label/priority claim",
+            prompt,
+        )
+
+    def test_prompt_refreshes_state_before_the_scope_gate_and_keeps_analysis(self):
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        # The refresh precedes the verdict-shaping steps, while the repository
+        # analysis the conversation already did stays part of the workflow.
+        self.assertLess(prompt.index("CURRENT STATE"), prompt.index("SCOPE GATE"))
+        self.assertLess(prompt.index("CURRENT STATE"), prompt.index("MUST read"))
+        self.assertIn("useful background", prompt)
+        self.assertIn("AGENTS.md", prompt)
+
+    def test_prompt_scope_gate_stops_before_the_technical_review(self):
+        prompt = main._build_review_prompt(
+            "owner/repo",
+            self._pr(),
+            "0123456789abcdef",
+            {"id": "1", "created_at": "t"},
+        )
+
+        gate = prompt.index("SCOPE GATE")
+        self.assertLess(gate, prompt.index("Inspect the PR discussion"))
+        self.assertLess(gate, prompt.index("Ground every finding"))
+        self.assertIn("before inspecting changed files, reading the diff, or running", prompt)
+        self.assertIn("scope categories and ownership boundaries", prompt)
+        self.assertIn("continue the technical review unchanged", prompt)
+        self.assertIn("move repositories, close, or receive a maintainer decision", prompt)
+
 
 class TestNormalizeRepo(unittest.TestCase):
     """A repository is written down in more than one way, and every API path in

package/skills/index.js

@@ -19,7 +19,7 @@ export const SKILLS_CATALOG = [
     "name": "add-skill",
     "description": "Import an existing skill from a GitHub repository URL into the current workspace. Use only when the user provides or references a GitHub URL/repo to fetch from (e.g., `/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview` or \"add the codereview skill from https://github.com/OpenHands/extensions/\"). Handles fetching the skill files and placing them in .agents/skills/. This does not author new skills — to create a new skill from scratch (no source URL), use the skill-creator skill instead.",
     "triggers": [],
-    "content": "# Add Skill\n\nImport skills from GitHub repositories into the current workspace.\n\n## Workflow\n\nWhen a user requests to add a skill from a GitHub URL:\n\n1. **Parse the URL** to extract repository owner, name, and skill path\n2. **Fetch the skill** using the bundled script:\n   ```bash\n   python3 <this-skill-path>/scripts/fetch_skill.py \"<github-url>\" \"<workspace-path>\"\n   ```\n3. **Verify** that SKILL.md exists in the destination\n4. **Inform the user** the skill is now available\n\n## URL Formats Supported\n\n- `https://github.com/owner/repo/tree/main/path/to/skill`\n- `https://github.com/owner/repo/skill-name`\n- `github.com/owner/repo/skill-name`\n- `owner/repo/skill-name` (shorthand)\n\n## Example\n\nUser: `/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview`\n\n```bash\n# Run the fetch script\npython3 scripts/fetch_skill.py \"https://github.com/OpenHands/extensions/tree/main/skills/codereview\" \"/path/to/workspace\"\n\n# Verify installation\nls /path/to/workspace/.agents/skills/codereview/SKILL.md\n```\n\nOn Windows, use `python` if `python3` is not available and verify with PowerShell, for example: `Test-Path C:\\path\\to\\workspace\\.agents\\skills\\codereview\\SKILL.md`.\n\nResponse: \"✅ Added `codereview` to your workspace. The skill is now available.\"\n\n## Notes\n\n- Creates `.agents/skills/` directory if it doesn't exist\n- Uses `GITHUB_TOKEN` for authentication (required for private repos)\n- Warns before overwriting existing skills with the same name",
+    "content": "# Add Skill\n\nImport skills from GitHub repositories into the current workspace.\n\n## Workflow\n\nWhen a user requests to add a skill from a GitHub URL:\n\n1. **Parse the URL** to extract repository owner, name, and skill path\n2. **Fetch the skill** using the bundled script. Run it from this skill's\n   directory (the directory containing this SKILL.md file):\n   ```bash\n   python3 scripts/fetch_skill.py \"<github-url>\" \"<workspace-path>\"\n   ```\n3. **Verify** that SKILL.md exists in the destination\n4. **Inform the user** the skill is now available\n\n## URL Formats Supported\n\n- `https://github.com/owner/repo/tree/main/path/to/skill`\n- `https://github.com/owner/repo/skill-name`\n- `github.com/owner/repo/skill-name`\n- `owner/repo/skill-name` (shorthand)\n\n## Example\n\nUser: `/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview`\n\n```bash\n# Run the fetch script\npython3 scripts/fetch_skill.py \"https://github.com/OpenHands/extensions/tree/main/skills/codereview\" \"/path/to/workspace\"\n\n# Verify installation\nls /path/to/workspace/.agents/skills/codereview/SKILL.md\n```\n\nOn Windows, use `python` if `python3` is not available and verify with PowerShell, for example: `Test-Path C:\\path\\to\\workspace\\.agents\\skills\\codereview\\SKILL.md`.\n\nResponse: \"✅ Added `codereview` to your workspace. The skill is now available.\"\n\n## Notes\n\n- Installs workspace-locally into `<workspace>/.agents/skills/<skill-name>/`,\n  not globally; that workspace is where the skill becomes available\n- Creates `.agents/skills/` directory if it doesn't exist\n- Uses `GITHUB_TOKEN` for authentication (required for private repos)\n- Warns before overwriting existing skills with the same name",
     "category": "agent-authoring",
     "defaultEnabled": true
   },
@@ -101,6 +101,14 @@ export const SKILLS_CATALOG = [
     "content": "You are working with **Bitbucket Data Center** (self-hosted Bitbucket Server). You have\naccess to an environment variable, `BITBUCKET_DATA_CENTER_TOKEN`, which contains a basic\nauth token in the format `username:your-token` that allows you to interact with the git\nrepository and the REST API.\n\n> Environment variable names are case-sensitive. If `BITBUCKET_DATA_CENTER_TOKEN` is not\n> present, use whichever case variant actually exists (for example\n> `bitbucket_data_center_token`). Run `env | grep -i 'bitbucket_data_center'` to find it.\n\n- REST API base URL: `https://{domain}/rest/api/1.0`\n- Repository identifier format: `PROJECT/repo_slug` (project key, slash, repo slug)\n\nYou can use this token to interact with the Bitbucket Data Center REST API:\n```bash\ncurl -u \"${BITBUCKET_DATA_CENTER_TOKEN}\" https://{domain}/rest/api/1.0/...\n```\n\n<IMPORTANT>\nALWAYS use the Bitbucket Data Center API for operations instead of a web browser.\nALWAYS use the `create_bitbucket_data_center_pr` tool to open a pull request\n</IMPORTANT>\n\nIf you encounter authentication issues when pushing to Bitbucket Data Center (such as password prompts or permission errors), the old token may have expired. In such case, update the remote URL to include the current token: `git remote set-url origin https://${BITBUCKET_DATA_CENTER_TOKEN}@{domain}/scm/{project_lower}/{repo}.git`\n\nThe token is a `username:token` pair, so if the username or token contains characters that are reserved in URLs (such as `@`), split on the first `:` and URL-encode each part before embedding it in a remote:\n\n```bash\nBB_USER=\"${BITBUCKET_DATA_CENTER_TOKEN%%:*}\" && \\\nBB_PASS=\"${BITBUCKET_DATA_CENTER_TOKEN#*:}\" && \\\nENCODED_USER=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=\"\"))' \"$BB_USER\") && \\\nENCODED_PASS=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=\"\"))' \"$BB_PASS\") && \\\ngit remote set-url origin \"https://${ENCODED_USER}:${ENCODED_PASS}@{domain}/scm/{project_lower}/{repo}.git\"\n```\n\nHere are some instructions for pushing, but ONLY do this if the user asks you to:\n* NEVER push directly to the `main` or `master` branch\n* Git config (username and email) is pre-set. Do not modify.\n* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.\n* Use the `create_bitbucket_data_center_pr` tool to create a pull request, if you haven't already\n* Once you've created your own branch or a pull request, continue to update it. Do NOT create a new one unless you are explicitly asked to. Update the PR title and description as necessary, but don't change the branch name.\n* Use the main branch as the base branch, unless the user requests otherwise\n* After opening or updating a pull request, send the user a short message with a link to the pull request.\n* Do NOT mark a pull request as ready to review unless the user explicitly says so\n* Do all of the above in as few steps as possible. E.g. you could push changes with one step by running the following bash commands:\n```bash\ngit remote -v && git branch # to find the current org, repo and branch\ngit checkout -b create-widget && git add . && git commit -m \"Create widget\" && git push -u origin create-widget\n```",
     "category": "code-hosting"
   },
+  {
+    "name": "canvas-extension-api",
+    "description": "This skill should be used when the user asks to \"create an OpenHands App\", \"scaffold a Canvas App\", \"build an app with the Canvas Extensions API\", \"build an Agent Canvas App\", \"bundle a single-file Canvas App\", \"build a Sidecar-backed Canvas App\", \"add onboarding for an App service\", \"add a custom interface to Agent Canvas\", \"validate an OpenHands App\", or mentions Canvas Apps, Agent Canvas extensions, Blob-importable app bundles, registerPage, app pages, Sidecars, or canvas extension packages.",
+    "triggers": [],
+    "content": "# Canvas Extensions API\n\nBuild and validate OpenHands Apps with the Canvas Extensions API, targeting the currently implemented manifest schema 1 and host API 1 routed-page ABI.\n\nUse the naming layers consistently:\n\n- **OpenHands Apps** - customer-facing category for interfaces people discover, install, enable, and open.\n- **Apps for Agent Canvas** - product phrasing that clarifies where apps run.\n- **Canvas Extensions API** - developer platform used to build apps.\n- **Canvas extension package** - technical artifact containing `canvas-extension.json` and its entrypoint.\n- **OpenHands Extensions** - ecosystem and repository umbrella for apps, skills, plugins, automations, and integrations.\n\nUse current product labels in user-facing instructions: **Apps for Agent Canvas**, **Add app**, **Installed apps**, **App source**, **Enable trusted app**, and **Build an app**. Keep technical identifiers such as `canvas-extension.json`, `/api/canvas-extensions/*`, `host.extension`, and `/extensions/*` unchanged unless the target implementation changes them.\n\nTreat apps as trusted, same-realm browser code owned by the active Agent Server. Keep the categories distinct: apps extend what people can do in Agent Canvas, plugins extend agent runtime capabilities, and skills provide agent instructions and knowledge.\n\n\n## Prefer the proven App authoring loop\n\nTreat an App as one authenticated browser dependency graph that Canvas imports from a Blob URL. Do not build a hosted SPA: the production result must be exactly one self-contained browser ESM entrypoint that exports `activate(host)`. Always ship this UI package even when it uses a separately installed Sidecar; make the App page the guided UI for Sidecar setup after the App is opened. Never treat a Sidecar as another browser chunk or an automatic extension install hook.\n\nFor a new App, create an independent package in the target repository and implement its own UI, tests, and build tooling. Follow the Vite library-build reference in `references/packaging-recipes.md`; do not copy a shared starter or introduce a repository-wide runtime/workspace unless the target repository explicitly requires it.\n\nKeep all source, scripts, dependencies, tests, and checked-in `extension.js` inside the App package. Implement one declared page with explicit root, nested, and unknown-route behavior. Inject scoped CSS per mount and clean it up with framework roots, requests, listeners, timers, Workers, and object URLs. Build validation must verify `dist/extension.js` before synchronizing it to the App root. Do not synchronize an unverified artifact. Use `CHROME_PATH` when the Chrome executable is elsewhere.\n\nFor an existing App, run the reusable static gate before and after its own checks:\n\n```sh\nnode /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app\nnode /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app --dist --marker <required-feature-marker>\n```\n\nTreat the static validator as a gate, not a replacement for the browser Blob smoke test. Read `references/packaging-recipes.md` before adding CSS, raw assets, dynamic modules, Workers, or WASM. Read `references/backend-safety.md` before any Agent Server integration or persistence. Read `references/sidecar-pattern.md` before designing a separately installed service or its onboarding. Read `references/acceptance-checklist.md` before reporting local Canvas compatibility.\n\n## Establish the target\n\nStart by locating the target directory instead of assuming the current workspace. Inspect repository instructions, existing package management, build tooling, tests, and git status before editing.\n\nMake an early architecture decision: browser-only App, Agent Server-integrated App, Sidecar-backed App, or explicitly deployment-specific App. Keep the portable host API 1 surface separate from deployment-owned capabilities.\n\nClarify only choices that materially affect implementation:\n\n- app purpose and page behavior;\n- target repository and subdirectory;\n- dependency-free JavaScript versus a bundled TypeScript/framework project;\n- Agent Server endpoints or host metadata required;\n- whether to build only, install locally, or prepare publication instructions;\n- for a Sidecar: execution location, owner, connection route, secrets and data, lifecycle actions, and portability across Agent Canvas deployments.\n\nDefault to one app with one routed page when requirements are otherwise clear. Keep the first implementation small and dependency-free unless the requested UI clearly benefits from a framework or the repository already has a bundler.\n\nWhen creating multiple Apps in one repository, give every App an independent package root containing its own `canvas-extension.json`, entrypoint, version, tests, README, and build tooling. Do not introduce a monorepo, shared runtime, or common build foundation unless the target repository explicitly requires one. Keep app manifest names globally distinct within the Agent Server installation.\n\nTreat installation as one app per request. The current Customize -> Apps flow accepts one `source`, optional `ref`, and optional `repo_path`; it does not recursively discover or bulk-install every manifest in a repository. For a remote repository, add each app separately using the same source/ref and its own `repo_path`. For a backend-local source, select each app package directory as the source path.\n\nRead `references/v1-contract.md` before implementing unfamiliar Canvas Extensions API behavior. Read `references/connections.md` before connecting to Agent Server, the Automation service, or WebSocket endpoints. Read `references/sidecar-pattern.md` before proposing a Sidecar bridge, onboarding, or operator action. Read `references/testing-and-installation.md` before installing or testing inside Agent Canvas, especially for a multi-app repository.\n\n## Inspect current upstream behavior\n\nTreat the v1 contract as young and subject to change. Before substantial work, compare the installed or target OpenHands version with the current upstream sources when access is available:\n\n- `specs/canvas-extensions.md`\n- `src/types/canvas-extension.ts`\n- `src/components/features/canvas-extensions/canvas-extensions-runtime.tsx`\n- `src/routes/canvas-extension-page.tsx`\n- `docs/CANVAS_EXTENSIONS_TESTING.md`\n\nDo not invent planned surfaces such as conversation tabs, slots, themes, or visualizer replacement. Implement only contributions supported by the target version. Routed pages are the only implemented contribution in host API 1.\n\n## Create the app package\n\nPlace `canvas-extension.json` at the app package root. Point `entrypoint` to one self-contained browser ESM file inside that root.\n\nUse this minimal manifest shape:\n\n```json\n{\n  \"schema_version\": 1,\n  \"name\": \"example-dashboard\",\n  \"display_name\": \"Example dashboard\",\n  \"version\": \"0.1.0\",\n  \"description\": \"A backend-specific project dashboard.\",\n  \"entrypoint\": \"extension.js\",\n  \"contributes\": {\n    \"pages\": [\n      {\n        \"id\": \"dashboard\",\n        \"title\": \"Dashboard\",\n        \"path\": \"/dashboard\",\n        \"nav_label\": \"Dashboard\"\n      }\n    ]\n  }\n}\n```\n\nFollow these invariants:\n\n- Use lowercase letters, digits, and hyphens for app names and page IDs.\n- Use absolute kebab-case page paths with a leading slash.\n- Keep every manifest path within the app package root.\n- Give each page ID and path a unique value.\n- Register only page IDs declared in the manifest.\n- Keep the entrypoint free of unresolved bare imports and external chunks.\n- Bundle dependencies, CSS, and small assets into the entrypoint when using build tooling.\n\nAdd a concise `README.md` when the app is intended for reuse or publication. Document purpose, build command if any, output entrypoint, installation coordinate, and verification steps. Avoid adding explanatory change-log documents.\n\n## Implement activation and pages\n\nExport an `activate` function from the ESM entrypoint:\n\n```js\nexport function activate(host) {\n  if (host.apiVersion !== \"1\") {\n    throw new Error(`This app requires host API 1.`);\n  }\n\n  return host.registerPage(\"dashboard\", ({ container, path, navigate }) => {\n    const root = document.createElement(\"section\");\n    root.textContent = path ? `Nested route: ${path}` : \"Dashboard\";\n    container.append(root);\n\n    return () => root.remove();\n  });\n}\n```\n\nUse the host contract deliberately:\n\n- Read immutable metadata from `host.extension` and `host.backend`.\n- Call `host.registerPage(id, mount)` during activation.\n- Use the mount callback's `path` as the route remainder below the declared page path.\n- Treat every nested-route navigation as a fresh mount: Canvas disposes the previous mount, clears the container, and invokes the mount callback with the new remainder. DOM and framework state do not persist across route changes; keep intentional cross-route state in the URL, backend, or activation-scoped state and clean it up on deactivation.\n- Use `navigate(absoluteCanvasPath)` for Canvas-aware routing.\n- Use `host.agentServer.request({ path, method, body, headers })` for authenticated calls to the owning Agent Server.\n- Pass only root-relative request paths beginning with one `/`; never pass absolute URLs or `//` paths.\n\nPrefer [`@openhands/typescript-client`](https://github.com/OpenHands/software-agent-sdk/tree/main/clients/typescript) for bundled TypeScript integrations whenever it covers the required Agent Server API and the necessary connection inputs are available. Prefer its typed clients, models, compatibility checks, and WebSocket lifecycle over hand-written transport code. Bundle the client into the self-contained app entrypoint; never leave a bare package import or external runtime chunk.\n\nRespect the host API 1 connection boundary:\n\n- Treat `host.agentServer.request` as the portable Agent Server HTTP path; Canvas selects the active backend and supplies authentication.\n- Do not derive an Agent Server URL from `window.location` or extract session keys from Canvas internals.\n- Do not send Automation service requests through `host.agentServer.request` unless the backend explicitly documents an Agent Server proxy for them. Automation is a separate service with deployment-provided base URL and authentication.\n- Do not open a direct Agent Server WebSocket from a portable v1 app. The host currently exposes neither the owning server origin nor a WebSocket/auth capability. Poll through `host.agentServer.request`, add a backend-owned bridge, or feature-detect a future host subscription API.\n- Use the TypeScript client's Agent Server WebSocket support in trusted standalone or future host-enabled contexts, and stop it during disposal. Do not treat the Agent Server client as an Automation service client.\n\nReturn cleanup from every layer that creates effects:\n\n- Return the unregister function or an activation disposer from `activate`.\n- Return a mount disposer for DOM nodes, timers, listeners, observers, subscriptions, and outstanding state.\n- Make async work disposal-aware so late responses cannot mutate an unmounted page.\n- Remove injected styles when the page unmounts.\n\nAssume activation, mounting, and disposal may happen repeatedly during hot enable/disable, updates, backend switches, reconnects, and route changes.\n\n## Build a production-quality page\n\nRender within the supplied `container`; do not replace unrelated Canvas DOM. Scope CSS under an app-specific root class. Prefer Canvas CSS variables with sensible fallbacks rather than copying host implementation classes.\n\nProvide:\n\n- semantic structure and headings inside the supplied container. Canvas already owns the outer `<main aria-label={page title}>`, so do not add a nested `main` or duplicate page landmark label;\n- keyboard-operable controls and visible focus;\n- responsive behavior for narrow layouts;\n- loading, empty, stale, and error states;\n- reduced-motion handling for animation;\n- text-safe rendering through DOM APIs or escaping rather than untrusted `innerHTML`;\n- clear handling for malformed or partial Agent Server responses.\n\nAvoid global event handlers, prototype changes, global CSS selectors, and ambient state unless unavoidable. Same-realm execution means these effects have full Canvas authority and cleanup is only best-effort.\n\n## Add tests\n\nTest real app code with a DOM environment and a small Canvas Extensions API host test double. Test at minimum:\n\n1. `activate` registers every declared page exactly once.\n2. The mount renders its initial state.\n3. Agent Server requests use the expected root-relative path and method.\n4. Nested navigation disposes the prior mount and remounts with the correct route remainder; test any intentionally preserved state explicitly.\n5. The mount disposer removes DOM and stops effects.\n6. The activation disposer unregisters contributions.\n7. Unsupported host API versions fail clearly when compatibility is checked.\n8. Network and malformed-response errors render safely.\n\nUse the repository's existing test infrastructure. Do not introduce a new framework when adequate tests already exist. For dependency-free fixtures, Vitest with a DOM environment matches the upstream example, but it is not part of the Canvas Extensions API runtime contract.\n\n## Validate the package\n\nRun the bundled validator before reporting completion:\n\n```sh\nnode /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app-package\n```\n\nThen run the target repository's formatter, linter, tests, and build. Inspect the final entrypoint rather than assuming the bundler configuration worked:\n\n- confirm the file exists at the manifest path;\n- confirm it exports `activate`;\n- reject bare imports and dynamic external chunks;\n- confirm CSS and required small assets are bundled or embedded;\n- confirm the output runs as browser ESM without Node globals.\n\nTreat validator warnings as prompts for inspection, not proof of invalidity. The helper uses conservative static checks and cannot replace loading the app bundle in Canvas.\n\n## Install and verify safely\n\nInstall only when requested. Installation and enablement are separate product actions: installation must leave the app disabled, and enabling executes trusted same-realm code.\n\nFor a backend-local app, install the path as interpreted on the Agent Server machine. For a Git-hosted app, provide `source`, optional `ref`, and optional `repo_path`. Never assume a frontend-local path exists inside a remote or containerized backend.\n\nFor multiple apps in one repository, produce an install matrix listing app name, manifest directory, source, ref, and `repo_path`. Submit one Add app operation per row. For remote repositories, omit `repo_path` only when the selected app lives at the repository root. For backend-local sources, make `source` the selected app package directory. Do not claim that selecting a repository root installs nested apps.\n\nValidate and test every app package independently, then run shared repository checks once. Report partial failures by app name rather than treating one passing app package as validation of the entire repository.\n\nVerify the lifecycle in Canvas:\n\n1. Install and confirm the inventory entry is disabled.\n2. Review source, revision, manifest metadata, and contributions.\n3. Enable and accept the trusted-code disclosure: “This app runs trusted JavaScript inside Agent Canvas and can make authenticated requests to the active Agent Server. Review its source and revision before enabling it.”\n4. Open the navigation item and exercise root and nested routes.\n5. Disable and confirm navigation and mounted UI disappear.\n6. Re-enable without restarting Canvas.\n7. Switch backend or reconnect when relevant and confirm isolation.\n8. Uninstall only when requested.\n\nDo not enable, uninstall, publish, push, or open a pull request without the user's authorization.\n\n## Report completion\n\nSummarize:\n\n- app location and contributed pages;\n- manifest schema and host API targeted;\n- build output and validation results;\n- tests run and their results;\n- installation status, explicitly stating whether it remains disabled;\n- remaining limitations tied to the current v1 ABI.\n\n## Resources\n\n- `references/v1-contract.md` - exact manifest, host API, lifecycle, routing, trust, and current limitations.\n- `references/connections.md` - Agent Server HTTP, Automation service, WebSocket, and TypeScript client connection guidance.\n- `references/testing-and-installation.md` - test strategy, manual Canvas workflow, and installation coordinates.\n- `references/packaging-recipes.md` - one-file Vite, CSS, assets, Workers, and WASM rules.\n- `references/backend-safety.md` - authenticated requests, command safety, persistence, and prerequisite onboarding.\n- `references/acceptance-checklist.md` - automated checks and the local install/enable/reload lifecycle.\n- `scripts/validate-extension.mjs` - dependency-free static artifact validator for an App package directory.",
+    "category": "agent-authoring",
+    "defaultEnabled": true
+  },
   {
     "name": "code-review",
     "description": "Review code changes for material correctness, security, compatibility, and maintainability risks, grounded in the current repository and acceptance criteria.",
@@ -275,7 +283,7 @@ export const SKILLS_CATALOG = [
     "triggers": [
       "/pr-reviewer:setup"
     ],
-    "content": "# GitHub PR Reviewer Automation\n\n## Agent Canvas catalog\n\nFor new Agent Canvas installations, use the **GitHub code review** catalog\nentry. Its deterministic `worker.py` delegates each requested exact head to a\nstable conversation using the selected agent profile. It supports GitHub\nreviewer-request events and scheduled label scans. The manual upload flow below\nremains for existing deployments and is deprecated for new installations.\n\nCreate a cron automation that watches one or more GitHub repositories for pull\nrequests with a review trigger label, starts an OpenHands review conversation\nonce per label event, and publishes the AI review to GitHub.\nWindows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in `references/windows.md`.\n\nThe automation script is deterministic: PR discovery, label-event tracking,\nstate persistence, stale-result suppression, the repository checkout, and its\nremoval are all handled in Python. The LLM is invoked only for the review\nitself.\n\nThe script prepares each review's workspace before the agent starts: the pull\nrequest's head commit is downloaded as a tarball and extracted to a directory of\nits own, which becomes the conversation's working directory. The agent is told\nnot to clone, fetch, check out, or delete anything, and the script removes the\ncheckout once the conversation has stopped. Nothing accumulates between runs.\n\n---\n\nThe script imports shared GitHub transport from\n`scripts/github_client.py`, installed with this skill. Include it beside\n`main.py` when packaging manually, as shown below; catalog bundles include it\nautomatically.\n\n## Prerequisites\n\n### Required secret\n\nVerify that the following secret is set in **OpenHands Settings -> Secrets**:\n\n| Secret name | Token type | Minimum permissions |\n|---|---|---|\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` for private repos or `public_repo` for public repos |\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Contents: Read, Metadata: Read, Pull requests: **Read and Write**, Issues: Read and Write |\n\nPull-request **write** access is required because the agent publishes a pull\nrequest review, not just an issue comment. The Agent Canvas catalog worker may\nalso request a configured human reviewer after approval. A token with only Pull\nrequests: Read will poll happily and then fail at the point of publishing or\nrequesting the handoff.\n\nWhen several repositories are monitored, the token must cover all of them.\n\nCheck with:\n```bash\ncurl -s https://api.github.com/user \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))\"\n```\n\nIf the token is missing or invalid, inform the user and stop.\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1 - Verify `GITHUB_PERSONAL_ACCESS_TOKEN`\n\nRun the `curl` check above.\n\n- If absent: *\"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in\n  OpenHands Settings -> Secrets.\"* Stop.\n- If the API returns `{\"message\": \"Bad credentials\"}`: tell the user the\n  token is invalid and ask them to update it. Stop.\n\n### Step 2 - Collect repositories\n\nAsk: *\"Which GitHub repositories should be monitored?\n(Format: `owner/repo`, e.g. `myorg/backend`. List several separated by commas to\nreview them all from one automation.)\"*\n\nValidate access to **each** repository:\n```bash\ncurl -s \"https://api.github.com/repos/{owner}/{repo}\" \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  | python3 -c \"\nimport json, sys\nd = json.load(sys.stdin)\nif 'message' in d:\n    print('ERROR:', d['message'])\nelse:\n    print(f\\\"Accessible. Private: {d.get('private')}. Permissions: {d.get('permissions')}\\\")\n\"\n```\n\nRecord every accepted repository into `REPOS = [\"{owner}/{repo}\", ...]`. If one\nrepository fails the check, say which and ask whether to continue without it.\n\nEach repository is polled independently and keeps its own state, so pull-request\nnumbers never collide between them. The trigger label, tone, and schedule are\nshared by all of them; a repository needing different settings wants its own\nautomation.\n\n### Step 3 - Collect trigger label\n\nAsk: *\"Which PR label should trigger a review?\n(Press Enter for the default: `openhands-review`.)\"*\n\nRecord the answer as `TRIGGER_LABEL`. If the label does not exist yet, tell the\nuser that GitHub will still record the event once the label is created and\napplied to a PR.\n\nThe automation reviews a PR when it sees the latest matching `labeled` event for\nthat label. To request another review later, remove and re-apply the label.\n\n### Step 4 - Collect review tone\n\nAsk: *\"What review tone should the reviewer use?\n  1. Thorough (default) - comprehensive coverage of correctness, security, tests, style\n  2. Concise - high-signal only, skips minor style feedback\n  3. Friendly - constructive and encouraging\n(Press Enter for Thorough, or type your choice or any custom style description)\"*\n\nMap the choice to `REVIEW_TONE`:\n\n| Answer | `REVIEW_TONE` | `REVIEW_STYLE_INSTRUCTIONS` |\n|---|---|---|\n| 1 / Enter | `\"thorough\"` | `\"\"` |\n| 2 | `\"concise\"` | `\"\"` |\n| 3 | `\"friendly\"` | `\"\"` |\n| Custom text, e.g. `strict but kind` | `\"thorough\"` | the custom text verbatim |\n\n### Step 5 - Collect cron schedule\n\nAsk: *\"How often should the automation poll for labeled PRs?\n(Press Enter for the default: every 5 minutes.\nUse a cron expression for a different interval, e.g. `0 * * * *` = hourly)\"*\n\nDefault: `*/5 * * * *`.\n\nRecord as `CRON_SCHEDULE`.\n\n### Step 6 - Generate the automation script\n\nRead `scripts/main.py` from this skill's directory. Apply exactly six constant\nsubstitutions near the top of the file:\n\n> The script also reads a `config.json` shipped beside it, if there is one, over\n> these constants. That is how the catalog entry\n> (`automations/catalog/github-pr-reviewer/`) configures an unmodified copy,\n> since a declarative host cannot rewrite Python. This setup path substitutes the\n> constants and ships no `config.json`, so the two never collide.\n\n| Placeholder | Replace with |\n|---|---|\n| `REPOS = [\"owner/repo\"]` | `REPOS = [\"{owner_repo}\", ...]` - one entry per repository collected in Step 2 |\n| `TRIGGER_LABEL = \"openhands-review\"` | `TRIGGER_LABEL = \"{trigger_label}\"` |\n| `REVIEW_TONE = \"thorough\"` | `REVIEW_TONE = \"{review_tone}\"` |\n| `REVIEW_STYLE_INSTRUCTIONS = \"\"` | `REVIEW_STYLE_INSTRUCTIONS = \"{style_instructions}\"` |\n| `REPO_REVIEW_GUIDE_PATH = \".agents/skills/custom-codereview-guide.md\"` | leave unchanged to auto-load a repo review guide at this path, or set to `\"\"` to disable |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | leave unchanged unless the user has a preference |\n\nUse a safe string writer such as `json.dumps(value)` when inserting user-provided\nrepository names, labels, or style instructions into Python string literals.\n`json.dumps(list_of_repos)` produces the whole `REPOS` list safely in one step.\n\nRun these commands from this skill's directory and write the customized script\nto a temporary build directory:\n```bash\nmkdir -p /tmp/pr-reviewer-build\ncp -L scripts/github_client.py /tmp/pr-reviewer-build/github_client.py\n# write the customized main.py to /tmp/pr-reviewer-build/main.py\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/pr-reviewer-build/main.py && echo \"Syntax OK\"\n```\n\nFix any syntax errors before proceeding.\n\n### Step 7 - Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- **OPENHANDS_HOST**: the Automation backend `url_from_agent`\n- **Auth**: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\n```bash\ntar -czf /tmp/pr-reviewer.tar.gz -C /tmp/pr-reviewer-build .\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-pr-reviewer\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/pr-reviewer.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\n### Step 8 - Register the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"GitHub PR Reviewer: {repo_summary} label {trigger_label}\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"{cron_schedule}\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 600\n  }\" | python3 -m json.tool\n```\n\nUse the single repository as `{repo_summary}` when there is one, and something\nlike `3 repos` when there are several. A poll now downloads a tarball per queued\nreview, so the timeout allows for that; a run never waits for a review to\nfinish, only for it to be started.\n\nRecord the returned `id`.\n\n### Step 9 - Confirm\n\nTell the user:\n\n> ✅ **GitHub PR Reviewer** is running!\n>\n> - Automation ID: `{id}`\n> - Repositories: `{owner}/{repo}`, ... (one line each)\n> - Trigger label: `{trigger_label}`\n> - Review tone: `{tone}`\n> - Polling schedule: `{cron_schedule}`\n> - State file per repository:\n>   `~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_{id}_{owner}__{repo}.json`\n>\n> Apply the `{trigger_label}` label to a pull request to queue a review. Each\n> label event is processed once. To request another review, remove and re-apply\n> the label.\n>\n> The review is published as a pull request review on the head commit, with\n> inline comments where a finding maps to a changed line.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which resolves and validates\n`GITHUB_PERSONAL_ACCESS_TOKEN` once, then processes every repository in `REPOS`\nindependently. One repository failing does not stop the others; the run fails\nonly if every repository fails.\n\nFor each repository:\n\n1. Loads that repository's state (see `references/state-schema.md`).\n2. Verifies repository access.\n3. Lists open PRs, newest-updated first.\n4. For each open PR carrying `TRIGGER_LABEL`:\n   - Refetches current PR metadata to avoid acting on stale list data.\n   - Finds the latest matching GitHub `labeled` issue event.\n   - Skips the event if it has already been tracked.\n   - Downloads the PR's head commit as a tarball and extracts it to\n     `{WORKSPACE_BASE}/repositories/{owner}__{repo}/pr-{number}-{sha12}`. The\n     archive is checked as it is unpacked: a single root, no absolute or `..`\n     paths, and symlinks skipped rather than materialised.\n   - Starts an OpenHands conversation **whose working directory is that\n     checkout**, with a review prompt carrying PR metadata, the exact head SHA,\n     and label event details.\n   - Posts an acknowledgement comment with the label event, head SHA, and\n     conversation link.\n   - Records the review in state with `status: \"active\"` and the checkout path.\n   - If the checkout or the conversation cannot be created, the checkout is\n     removed and nothing is recorded, so the next poll retries the label event.\n5. For each active review conversation:\n   - Marks it closed without posting if the PR has closed or merged.\n   - Suppresses stale results if the PR head SHA changed after the review was\n     queued.\n   - When the conversation reaches `idle`, `finished`, `error`, or `stuck`,\n     asks GitHub whether a review by the token's own user exists for that head\n     SHA. If it does, the review is complete. If it does not, the agent's final\n     response is posted as a comment so the work is not lost.\n   - Abandons a conversation that has not reached a terminal status within two\n     hours, so its checkout can be reclaimed.\n6. Removes the checkout of every finished review, but only after confirming the\n   conversation has stopped - deleting it under a running agent would remove its\n   working directory. When that cannot be confirmed the directory is left alone\n   and the next poll tries again.\n7. Saves that repository's state atomically.\n\nThe completion callback fires once for the whole run.\n\n---\n\n## Additional Resources\n\n- **`references/state-schema.md`** - State JSON schema, field definitions, and\n  review lifecycle diagram.\n- **`scripts/main.py`** - The complete automation script. Customize the five\n  constants at the top before packaging.\n- **`tests/test_main.py`** - Unit tests for the checkout, its removal, and state\n  handling. Run them from the skill root with `python -m pytest tests/` after\n  editing the script.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot never queues reviews | Trigger label not present or no matching `labeled` event | Apply the configured label to the PR |\n| \"Bad credentials\" in run logs | Token expired | Rotate and update `GITHUB_PERSONAL_ACCESS_TOKEN` |\n| 404 on repo access | Repo name wrong or no access | Re-check the entry in `REPOS` and the token's permissions |\n| One repository is skipped, others work | That repository failed its access check | Read the `=== owner/repo ===` block in the run log |\n| Same PR not reviewed after new commits | Label event was already processed | Remove and re-apply the trigger label |\n| Review result never posts | Conversation still running or stuck | Open the conversation link from the acknowledgement comment |\n| Stale review suppressed | PR head SHA changed while the agent was reviewing | Re-apply the trigger label after the latest commit |\n| Review arrives as a plain comment, not a review | Publishing failed, so the script posted the text as a fallback | Check that the token has Pull requests: Read and Write |\n| Agent reports it cannot clone the repo | Prompt asked it not to; the workspace is already the checkout | No action - the code is at the head SHA in its working directory |\n| Checkouts remain under `repositories/` | Their conversations had not stopped yet | They are removed by a later poll once the conversation is terminal |",
+    "content": "# GitHub PR Reviewer Automation\n\n## Agent Canvas catalog\n\nFor new Agent Canvas installations, use the **GitHub code review** catalog\nentry. Its deterministic `worker.py` delegates each requested exact head to a\nstable conversation using the selected agent profile. It supports GitHub\nreviewer-request events and scheduled label scans. The manual upload flow below\nremains for existing deployments and is deprecated for new installations.\n\nCreate a cron automation that watches one or more GitHub repositories for pull\nrequests with a review trigger label, starts an OpenHands review conversation\nonce per label event, and publishes the AI review to GitHub.\nWindows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in `references/windows.md`.\n\nThe automation script is deterministic: PR discovery, label-event tracking,\nstate persistence, stale-result suppression, the repository checkout, and its\nremoval are all handled in Python. The LLM is invoked only for the review\nitself.\n\nEach explicit review request - a re-applied trigger label, or a new reviewer\nrequest in event mode - is a fresh review. The conversation for a PR is reused,\nbut its earlier turns must not be trusted as current: before deciding a verdict\nthe reviewer re-fetches the mutable GitHub state (the exact head, the PR body,\nreview comments and threads, review requests, the linked issues' bodies and\nlabels, and the current-head Actions results) and ignores any earlier finding,\nverdict, or label/priority claim that state no longer supports. Repository\nanalysis the conversation already did, such as reading `AGENTS.md`, stays\nuseful and is not repeated.\n\nThe review prompt starts with a scope gate: using the repository's own guidance\n(its scope categories and ownership boundaries, not a list of individual PR\nnumbers), the reviewer decides whether the change belongs in this repository\nand has the product/architecture direction it needs. When it does not, the review\nstops with a single `event: COMMENT` review that says whether the change should\nmove repositories, close, or receive a maintainer decision, and ends with the\n`🛑 MAINTAINER DECISION REQUIRED` verdict. That outcome is **neither an approval\nnor a change request**: it does not approve or merge the PR. The completion\nhandler recognizes the verdict and requests one configured maintainer through the\nsame handoff used after an approval. An in-scope change continues the existing\nreview unchanged.\n\nThe script prepares each review's workspace before the agent starts: the pull\nrequest's head commit is downloaded as a tarball and extracted to a directory of\nits own, which becomes the conversation's working directory. The agent is told\nnot to clone, fetch, check out, or delete anything, and the script removes the\ncheckout once the conversation has stopped. Nothing accumulates between runs.\n\n---\n\nThe script imports shared GitHub transport from\n`scripts/github_client.py`, installed with this skill. Include it beside\n`main.py` when packaging manually, as shown below; catalog bundles include it\nautomatically.\n\n## Prerequisites\n\n### Required secret\n\nVerify that the following secret is set in **OpenHands Settings -> Secrets**:\n\n| Secret name | Token type | Minimum permissions |\n|---|---|---|\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` for private repos or `public_repo` for public repos |\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Contents: Read, Metadata: Read, Pull requests: **Read and Write**, Issues: Read and Write |\n\nPull-request **write** access is required because the agent publishes a pull\nrequest review, not just an issue comment. The Agent Canvas catalog worker may\nalso request a configured human reviewer after approval. A token with only Pull\nrequests: Read will poll happily and then fail at the point of publishing or\nrequesting the handoff.\n\nWhen several repositories are monitored, the token must cover all of them.\n\nCheck with:\n```bash\ncurl -s https://api.github.com/user \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))\"\n```\n\nIf the token is missing or invalid, inform the user and stop.\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1 - Verify `GITHUB_PERSONAL_ACCESS_TOKEN`\n\nRun the `curl` check above.\n\n- If absent: *\"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in\n  OpenHands Settings -> Secrets.\"* Stop.\n- If the API returns `{\"message\": \"Bad credentials\"}`: tell the user the\n  token is invalid and ask them to update it. Stop.\n\n### Step 2 - Collect repositories\n\nAsk: *\"Which GitHub repositories should be monitored?\n(Format: `owner/repo`, e.g. `myorg/backend`. List several separated by commas to\nreview them all from one automation.)\"*\n\nValidate access to **each** repository:\n```bash\ncurl -s \"https://api.github.com/repos/{owner}/{repo}\" \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  | python3 -c \"\nimport json, sys\nd = json.load(sys.stdin)\nif 'message' in d:\n    print('ERROR:', d['message'])\nelse:\n    print(f\\\"Accessible. Private: {d.get('private')}. Permissions: {d.get('permissions')}\\\")\n\"\n```\n\nRecord every accepted repository into `REPOS = [\"{owner}/{repo}\", ...]`. If one\nrepository fails the check, say which and ask whether to continue without it.\n\nEach repository is polled independently and keeps its own state, so pull-request\nnumbers never collide between them. The trigger label, tone, and schedule are\nshared by all of them; a repository needing different settings wants its own\nautomation.\n\n### Step 3 - Collect trigger label\n\nAsk: *\"Which PR label should trigger a review?\n(Press Enter for the default: `openhands-review`.)\"*\n\nRecord the answer as `TRIGGER_LABEL`. If the label does not exist yet, tell the\nuser that GitHub will still record the event once the label is created and\napplied to a PR.\n\nThe automation reviews a PR when it sees the latest matching `labeled` event for\nthat label. To request another review later, remove and re-apply the label.\n\n### Step 4 - Collect review tone\n\nAsk: *\"What review tone should the reviewer use?\n  1. Thorough (default) - comprehensive coverage of correctness, security, tests, style\n  2. Concise - high-signal only, skips minor style feedback\n  3. Friendly - constructive and encouraging\n(Press Enter for Thorough, or type your choice or any custom style description)\"*\n\nMap the choice to `REVIEW_TONE`:\n\n| Answer | `REVIEW_TONE` | `REVIEW_STYLE_INSTRUCTIONS` |\n|---|---|---|\n| 1 / Enter | `\"thorough\"` | `\"\"` |\n| 2 | `\"concise\"` | `\"\"` |\n| 3 | `\"friendly\"` | `\"\"` |\n| Custom text, e.g. `strict but kind` | `\"thorough\"` | the custom text verbatim |\n\n### Step 5 - Collect cron schedule\n\nAsk: *\"How often should the automation poll for labeled PRs?\n(Press Enter for the default: every 5 minutes.\nUse a cron expression for a different interval, e.g. `0 * * * *` = hourly)\"*\n\nDefault: `*/5 * * * *`.\n\nRecord as `CRON_SCHEDULE`.\n\n### Step 6 - Generate the automation script\n\nRead `scripts/main.py` from this skill's directory. Apply exactly six constant\nsubstitutions near the top of the file:\n\n> The script also reads a `config.json` shipped beside it, if there is one, over\n> these constants. That is how the catalog entry\n> (`automations/catalog/github-pr-reviewer/`) configures an unmodified copy,\n> since a declarative host cannot rewrite Python. This setup path substitutes the\n> constants and ships no `config.json`, so the two never collide.\n\n| Placeholder | Replace with |\n|---|---|\n| `REPOS = [\"owner/repo\"]` | `REPOS = [\"{owner_repo}\", ...]` - one entry per repository collected in Step 2 |\n| `TRIGGER_LABEL = \"openhands-review\"` | `TRIGGER_LABEL = \"{trigger_label}\"` |\n| `REVIEW_TONE = \"thorough\"` | `REVIEW_TONE = \"{review_tone}\"` |\n| `REVIEW_STYLE_INSTRUCTIONS = \"\"` | `REVIEW_STYLE_INSTRUCTIONS = \"{style_instructions}\"` |\n| `REPO_REVIEW_GUIDE_PATH = \".agents/skills/custom-codereview-guide.md\"` | leave unchanged to auto-load a repo review guide at this path, or set to `\"\"` to disable |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | leave unchanged unless the user has a preference |\n\nUse a safe string writer such as `json.dumps(value)` when inserting user-provided\nrepository names, labels, or style instructions into Python string literals.\n`json.dumps(list_of_repos)` produces the whole `REPOS` list safely in one step.\n\nRun these commands from this skill's directory and write the customized script\nto a temporary build directory:\n```bash\nmkdir -p /tmp/pr-reviewer-build\ncp -L scripts/github_client.py /tmp/pr-reviewer-build/github_client.py\n# write the customized main.py to /tmp/pr-reviewer-build/main.py\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/pr-reviewer-build/main.py && echo \"Syntax OK\"\n```\n\nFix any syntax errors before proceeding.\n\n### Step 7 - Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- **OPENHANDS_HOST**: the Automation backend `url_from_agent`\n- **Auth**: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\n```bash\ntar -czf /tmp/pr-reviewer.tar.gz -C /tmp/pr-reviewer-build .\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-pr-reviewer\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/pr-reviewer.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\n### Step 8 - Register the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"GitHub PR Reviewer: {repo_summary} label {trigger_label}\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"{cron_schedule}\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 600\n  }\" | python3 -m json.tool\n```\n\nUse the single repository as `{repo_summary}` when there is one, and something\nlike `3 repos` when there are several. A poll now downloads a tarball per queued\nreview, so the timeout allows for that; a run never waits for a review to\nfinish, only for it to be started.\n\nRecord the returned `id`.\n\n### Step 9 - Confirm\n\nTell the user:\n\n> ✅ **GitHub PR Reviewer** is running!\n>\n> - Automation ID: `{id}`\n> - Repositories: `{owner}/{repo}`, ... (one line each)\n> - Trigger label: `{trigger_label}`\n> - Review tone: `{tone}`\n> - Polling schedule: `{cron_schedule}`\n> - State file per repository:\n>   `~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_{id}_{owner}__{repo}.json`\n>\n> Apply the `{trigger_label}` label to a pull request to queue a review. Each\n> label event is processed once. To request another review, remove and re-apply\n> the label.\n>\n> The review is published as a pull request review on the head commit, with\n> inline comments where a finding maps to a changed line.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which resolves and validates\n`GITHUB_PERSONAL_ACCESS_TOKEN` once, then processes every repository in `REPOS`\nindependently. One repository failing does not stop the others; the run fails\nonly if every repository fails.\n\nFor each repository:\n\n1. Loads that repository's state (see `references/state-schema.md`).\n2. Verifies repository access.\n3. Lists open PRs, newest-updated first.\n4. For each open PR carrying `TRIGGER_LABEL`:\n   - Refetches current PR metadata to avoid acting on stale list data.\n   - Finds the latest matching GitHub `labeled` issue event.\n   - Skips the event if it has already been tracked.\n   - Downloads the PR's head commit as a tarball and extracts it to\n     `{WORKSPACE_BASE}/repositories/{owner}__{repo}/pr-{number}-{sha12}`. The\n     archive is checked as it is unpacked: a single root, no absolute or `..`\n     paths, and symlinks skipped rather than materialised.\n   - Starts an OpenHands conversation **whose working directory is that\n     checkout**, with a review prompt carrying PR metadata, the exact head SHA,\n     label event details, and the requirement to re-fetch the current mutable\n     GitHub state before deciding a verdict.\n   - Posts an acknowledgement comment with the label event, head SHA, and\n     conversation link.\n   - Records the review in state with `status: \"active\"` and the checkout path.\n   - If the checkout or the conversation cannot be created, the checkout is\n     removed and nothing is recorded, so the next poll retries the label event.\n5. For each active review conversation:\n   - Marks it closed without posting if the PR has closed or merged.\n   - Suppresses stale results if the PR head SHA changed after the review was\n     queued.\n   - When the conversation reaches `idle`, `finished`, `error`, or `stuck`,\n     asks GitHub whether a review by the token's own user exists for that head\n     SHA. If it does, the review is complete. If it does not, the agent's final\n     response is posted as a comment so the work is not lost.\n   - Abandons a conversation that has not reached a terminal status within two\n     hours, so its checkout can be reclaimed.\n6. Removes the checkout of every finished review, but only after confirming the\n   conversation has stopped - deleting it under a running agent would remove its\n   working directory. When that cannot be confirmed the directory is left alone\n   and the next poll tries again.\n7. Saves that repository's state atomically.\n\nThe completion callback fires once for the whole run.\n\n---\n\n## Additional Resources\n\n- **`references/state-schema.md`** - State JSON schema, field definitions, and\n  review lifecycle diagram.\n- **`scripts/main.py`** - The complete automation script. Customize the five\n  constants at the top before packaging.\n- **`tests/test_main.py`** - Unit tests for the checkout, its removal, and state\n  handling. Run them from the skill root with `python -m pytest tests/` after\n  editing the script.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot never queues reviews | Trigger label not present or no matching `labeled` event | Apply the configured label to the PR |\n| \"Bad credentials\" in run logs | Token expired | Rotate and update `GITHUB_PERSONAL_ACCESS_TOKEN` |\n| 404 on repo access | Repo name wrong or no access | Re-check the entry in `REPOS` and the token's permissions |\n| One repository is skipped, others work | That repository failed its access check | Read the `=== owner/repo ===` block in the run log |\n| Same PR not reviewed after new commits | Label event was already processed | Remove and re-apply the trigger label |\n| Review result never posts | Conversation still running or stuck | Open the conversation link from the acknowledgement comment |\n| Stale review suppressed | PR head SHA changed while the agent was reviewing | Re-apply the trigger label after the latest commit |\n| Review arrives as a plain comment, not a review | Publishing failed, so the script posted the text as a fallback | Check that the token has Pull requests: Read and Write |\n| Agent reports it cannot clone the repo | Prompt asked it not to; the workspace is already the checkout | No action - the code is at the head SHA in its working directory |\n| Checkouts remain under `repositories/` | Their conversations had not stopped yet | They are removed by a later poll once the conversation is terminal |",
     "category": "automations"
   },
   {
@@ -676,5 +684,5 @@ export const SKILLS_CATALOG = [
     "category": "integrations"
   }
 ];
-export const DEFAULT_ENABLED_SKILL_NAMES = ["add-skill","agent-canvas-environment","agent-memory","agent-sdk-builder","code-review","docker","github","openhands-api","openhands-automation","openhands-sdk","skill-creator"];
+export const DEFAULT_ENABLED_SKILL_NAMES = ["add-skill","agent-canvas-environment","agent-memory","agent-sdk-builder","canvas-extension-api","code-review","docker","github","openhands-api","openhands-automation","openhands-sdk","skill-creator"];
 export default SKILLS_CATALOG;

package/tests/fixtures/automations/github-pr-reviewer.json

@@ -67,7 +67,7 @@
               "timeout": 300,
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.3.0",
+                "version": "1.5.0",
                 "config": {
                   "repos": [
                     "OpenHands/agent-server-gui"
@@ -106,7 +106,7 @@
             "timeout": 300,
             "template": {
               "id": "github-pr-reviewer",
-              "version": "1.3.0",
+              "version": "1.5.0",
               "config": {
                 "repos": [
                   "OpenHands/agent-server-gui"
@@ -209,7 +209,7 @@
               "timeout": 300,
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.3.0",
+                "version": "1.5.0",
                 "config": {
                   "repos": [
                     "OpenHands/agent-server-gui",
@@ -249,7 +249,7 @@
             "timeout": 300,
             "template": {
               "id": "github-pr-reviewer",
-              "version": "1.3.0",
+              "version": "1.5.0",
               "config": {
                 "repos": [
                   "OpenHands/agent-server-gui",
@@ -290,7 +290,7 @@
             "preset_metadata": {
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.3.0",
+                "version": "1.5.0",
                 "config": {
                   "repos": [
                     "OpenHands/agent-server-gui",
@@ -343,7 +343,7 @@
               "timeout": 300,
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.3.0",
+                "version": "1.5.0",
                 "config": {
                   "repos": [
                     "OpenHands/agent-server-gui"
@@ -434,7 +434,7 @@
             "timeout": 300,
             "template": {
               "id": "github-pr-reviewer",
-              "version": "1.3.0",
+              "version": "1.5.0",
               "config": {
                 "repos": [
                   "OpenHands/agent-server-gui"
@@ -528,7 +528,7 @@
             "timeout": 300,
             "template": {
               "id": "github-pr-reviewer",
-              "version": "1.3.0",
+              "version": "1.5.0",
               "config": {
                 "repos": [
                   "OpenHands/agent-server-gui"
@@ -602,7 +602,7 @@
               "timeout": 300,
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.3.0",
+                "version": "1.5.0",
                 "config": {
                   "repos": [
                     "OpenHands/automation"