@openhands/extensions 0.20.0 → 0.22.0

package/skills/github-delivery-watchdog/scripts/worker.py

@@ -0,0 +1,96 @@
+"""Follow delivery progress and merge only independently accepted, current PRs."""
+
+import json
+import re
+
+from github_client import GitHubRepository, run_repositories
+
+
+class DeliveryWatchdog(GitHubRepository):
+    name = "github-delivery-watchdog"
+
+    def ci_passed(self, sha):
+        """Actions read works with fine-grained PATs; permission errors fail closed."""
+        runs = {}
+        for page in range(1, 11):
+            result = self.gh(
+                "GET", f"/actions/runs?head_sha={sha}&per_page=100&page={page}"
+            )
+            for run in result["workflow_runs"]:
+                if run["head_sha"] != sha:
+                    return False
+                runs[run["id"]] = run
+            if len(result["workflow_runs"]) < 100:
+                if result["total_count"] != len(runs):
+                    return False
+                latest = {}
+                for run in sorted(
+                    runs.values(), key=lambda r: r["run_number"], reverse=True
+                ):
+                    # A newer execution supersedes the same workflow trigger,
+                    # but a passing push must not hide a failing PR workflow.
+                    latest.setdefault(
+                        (run["workflow_id"], run["event"], run["head_branch"]), run
+                    )
+                return set(self.config.get("required_workflow_ids", [])) <= {
+                    r["workflow_id"] for r in latest.values()
+                } and all(
+                    r["status"] == "completed" and r["conclusion"] == "success"
+                    for r in latest.values()
+                )
+        return False
+
+    def merge(self, number, sha):
+        pr = self.gh("GET", f"/pulls/{number}")
+        prefix = re.escape(self.config.get("branch_prefix", "openhands/issue"))
+        if not (
+            pr["state"] == "open"
+            and pr["head"]["sha"] == sha
+            and pr["base"]["ref"] == self.base_branch
+            and re.fullmatch(prefix + r"-\d+", pr["head"]["ref"])
+            and not pr["draft"]
+            and pr["mergeable"] is True
+        ):
+            return None
+        statuses = self.statuses(sha)
+        required = ("software-factory/tests", "software-factory/review")
+        if not all(statuses.get(c) == "success" for c in required):
+            return None
+        if not all(
+            value == "success" for value in statuses.values()
+        ) or not self.ci_passed(sha):
+            return None
+        comparison = self.gh("GET", f"/compare/{pr['base']['sha']}...{sha}")
+        if comparison["status"] in ("behind", "diverged") and comparison.get(
+            "behind_by", 0
+        ):
+            self.gh(
+                "POST",
+                f"/issues/{number}/labels",
+                {"labels": [self.config.get("trigger_label", "openhands-review")]},
+            )
+            return self.gh(
+                "PUT", f"/pulls/{number}/update-branch", {"expected_head_sha": sha}
+            )
+        if comparison["status"] not in ("ahead", "identical"):
+            return None
+        return self.gh(
+            "PUT", f"/pulls/{number}/merge", {"sha": sha, "merge_method": "squash"}
+        )
+
+    def run(self):
+        for pr in self.gh_pages("/pulls?state=open"):
+            try:
+                result = self.merge(pr["number"], pr["head"]["sha"])
+            except Exception as exc:  # noqa: BLE001 - one PR must not block other repositories
+                # A conflict, permission failure, or unavailable API cannot
+                # authorize a merge or prevent checking unrelated pull requests.
+                result = {
+                    "error": type(exc).__name__,
+                    "status": getattr(exc, "code", None),
+                }
+            print(json.dumps({"pr": pr["number"], "merge": result}), flush=True)
+
+
+if __name__ == "__main__":
+    run_repositories(DeliveryWatchdog)

package/skills/github-issue-to-pr/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "github-issue-to-pr",
+  "version": "1.0.0",
+  "description": "Create an automation that implements GitHub issues when a configurable trigger label is applied. It clones the default branch, starts one OpenHands conversation per label event, then commits, pushes, and opens the pull request itself, without ever handing the agent a GitHub credential.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "issue",
+    "pull-request",
+    "automation",
+    "integration"
+  ]
+}

package/skills/github-issue-to-pr/.codex-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "github-issue-to-pr",
+  "version": "1.0.0",
+  "description": "Create an automation that implements GitHub issues when a configurable trigger label is applied. It clones the default branch, starts one OpenHands conversation per label event, then commits, pushes, and opens the pull request itself, without ever handing the agent a GitHub credential.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "issue",
+    "pull-request",
+    "automation",
+    "integration"
+  ]
+}

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

@@ -11,6 +11,13 @@ triggers:
 
 # GitHub Issue to PR Automation
 
+## Agent Canvas catalog
+
+For new Agent Canvas installations, use the **GitHub issue to PR** catalog
+entry. Its deterministic `worker.py` scanner delegates each eligible issue to a
+stable conversation using the selected agent profile. The manual upload flow
+below remains for existing deployments and is deprecated for new installations.
+
 Create a cron automation that watches one or more GitHub repositories for issues
 with a trigger label, starts an OpenHands conversation once per label event with
 the repository's default branch already checked out, and opens a pull request
@@ -40,6 +47,11 @@ environment of a command that mentions it, and masks it in the output.
 
 ---
 
+The script imports shared GitHub transport from
+`scripts/github_client.py`, installed with this skill. Include it beside
+`main.py` when packaging manually, as shown below; catalog bundles include it
+automatically.
+
 ## Prerequisites
 
 ### Required secret
@@ -205,9 +217,11 @@ Use a safe string writer such as `json.dumps(value)` when inserting user-provide
 repository names, labels, or prefixes into Python string literals.
 `json.dumps(list_of_repos)` produces the whole `REPOS` list safely in one step.
 
-Write the customized script to a temporary build directory:
+Run these commands from this skill's directory and write the customized script
+to a temporary build directory:
 ```bash
 mkdir -p /tmp/issue-to-pr-build
+cp -L scripts/github_client.py /tmp/issue-to-pr-build/github_client.py
 # write the customized main.py to /tmp/issue-to-pr-build/main.py
 ```
 

package/skills/github-issue-to-pr/scripts/agent_conversation.py

@@ -0,0 +1,143 @@
+"""Idempotently deliver automation work to profile-backed conversations."""
+
+import json
+import os
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+from uuid import NAMESPACE_URL, UUID, uuid5
+
+import httpx
+from openhands.sdk import RemoteConversation
+from openhands.sdk.conversation.request import (
+    SendMessageRequest,
+    StartConversationRequest,
+)
+from openhands.sdk.conversation.state import ConversationExecutionStatus
+from openhands.sdk.llm.message import TextContent
+from openhands.sdk.workspace import LocalWorkspace, RemoteWorkspace
+
+_CONVERSATION_KEY_PREFIX = "agent-conversation-"
+
+
+def _register_tools() -> None:
+    """Register tool models needed to deserialize an attached agent."""
+    from openhands.tools import register_default_tools
+
+    register_default_tools()
+
+
+def _kv_request(key: str, method: str, value: dict | None = None) -> dict | None:
+    base_url = os.environ.get("AUTOMATION_API_URL", "").rstrip("/")
+    token = os.environ.get("AUTOMATION_KV_TOKEN", "")
+    if not base_url or not token:
+        raise RuntimeError("Automation KV is required for agent conversation dispatch")
+    request = Request(
+        f"{base_url}/v1/kv/{key}",
+        data=json.dumps(value).encode() if value is not None else None,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+        method=method,
+    )
+    try:
+        with urlopen(request, timeout=90) as response:
+            body = json.load(response)
+    except HTTPError as exc:
+        if method == "GET" and exc.code == 404:
+            return None
+        raise
+    return body.get("value") if method == "GET" else body
+
+
+class AgentConversationDispatcher:
+    """Deliver one revision at a time to a stable conversation for each subject."""
+
+    def __init__(self) -> None:
+        self.agent_url = os.environ["AGENT_SERVER_URL"]
+        self.api_key = os.environ["SESSION_API_KEY"]
+        self.profile_id = UUID(os.environ["AUTOMATION_AGENT_PROFILE_ID"])
+        payload = json.loads(os.environ["AUTOMATION_EVENT_PAYLOAD"])
+        self.automation_id = str(payload["automation_id"])
+        self._workspace: RemoteWorkspace | None = None
+
+    def __enter__(self):
+        _register_tools()
+        self._workspace = RemoteWorkspace(
+            host=self.agent_url,
+            api_key=self.api_key,
+            working_dir=os.environ.get("WORKSPACE_BASE", "/workspace"),
+        )
+        self._workspace.__enter__()
+        return self
+
+    def __exit__(self, *args):
+        assert self._workspace is not None
+        return self._workspace.__exit__(*args)
+
+    def deliver(self, subject: str, delivery: str, prompt: str) -> dict[str, str]:
+        conversation_id = uuid5(NAMESPACE_URL, f"{self.automation_id}:{subject}")
+        state_key = f"{_CONVERSATION_KEY_PREFIX}{conversation_id}"
+        record = _kv_request(state_key, "GET") or {}
+        if self._workspace is None:
+            raise RuntimeError("AgentConversationDispatcher must be used as a context")
+
+        same_delivery = record.get("delivery") == delivery
+
+        try:
+            conversation = RemoteConversation.attach(
+                self._workspace, conversation_id, visualizer=None
+            )
+            disposition = "resumed"
+        except httpx.HTTPStatusError as exc:
+            if exc.response.status_code != 404:
+                raise
+            conversation = RemoteConversation.create(
+                self._workspace,
+                StartConversationRequest(
+                    workspace=LocalWorkspace(working_dir="/workspace"),
+                    conversation_id=conversation_id,
+                    agent_profile_id=self.profile_id,
+                    initial_message=SendMessageRequest(
+                        content=[TextContent(text=prompt)], run=True
+                    ),
+                ),
+                visualizer=None,
+            )
+            disposition = "created"
+        try:
+            if disposition == "resumed":
+                if same_delivery:
+                    if conversation.state.execution_status in (
+                        ConversationExecutionStatus.IDLE,
+                        ConversationExecutionStatus.RUNNING,
+                        ConversationExecutionStatus.PAUSED,
+                    ):
+                        conversation.run(blocking=False)
+                    else:
+                        disposition = "deduplicated"
+                else:
+                    conversation.send_message(prompt)
+                    conversation.run(blocking=False)
+        finally:
+            conversation.close()
+
+        if disposition == "deduplicated":
+            return {
+                "disposition": disposition,
+                "conversation_id": str(conversation_id),
+            }
+
+        _kv_request(
+            state_key,
+            "PUT",
+            {
+                "subject": subject,
+                "conversation_id": str(conversation_id),
+                "delivery": delivery,
+            },
+        )
+        return {
+            "disposition": disposition,
+            "conversation_id": str(conversation_id),
+        }

package/skills/github-issue-to-pr/scripts/github_client.py

@@ -0,0 +1,230 @@
+"""Shared GitHub transport and repository operations for GitHub automations."""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+from functools import cached_property
+from pathlib import Path
+from urllib.error import HTTPError
+from urllib.parse import parse_qsl, urlencode, urlsplit
+from urllib.request import Request, urlopen
+
+
+def _load_secret(name: str) -> str:
+    """Read one named secret from the environment or configured Agent Server."""
+    value = os.environ.get(name)
+    if value:
+        return value
+
+    from openhands.sdk.workspace import RemoteWorkspace
+
+    workspace = RemoteWorkspace(
+        host=os.environ["AGENT_SERVER_URL"],
+        api_key=os.environ["SESSION_API_KEY"],
+        working_dir=os.environ.get("WORKSPACE_BASE", "/workspace"),
+    )
+    try:
+        secret = workspace.get_secrets([name]).get(name)
+        value = secret.get_value() if secret else None
+    finally:
+        workspace.reset_client()
+    if not value:
+        raise ValueError(f"The GitHub credential {name} is unavailable")
+    return value
+
+
+def github_request(
+    token: str,
+    method: str,
+    path: str,
+    params: dict | None = None,
+    body: dict | None = None,
+    accept: str = "application/vnd.github+json",
+) -> tuple:
+    url = f"https://api.github.com{path}"
+    if params:
+        url = f"{url}?{urlencode(params)}"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": accept,
+        "X-GitHub-Api-Version": "2022-11-28",
+        "Content-Type": "application/json",
+    }
+    data = json.dumps(body).encode() if body is not None else None
+    req = Request(url, data=data, headers=headers, method=method)
+    with urlopen(req, timeout=90) as r:
+        raw = r.read()
+        return (json.loads(raw) if raw.strip() else {}), dict(r.headers)
+
+
+def github_paginate(token: str, path: str, params: dict | None = None) -> list:
+    results = []
+    base_params = dict(params or {})
+    base_params.setdefault("per_page", 100)
+    for page in range(1, 101):
+        base_params["page"] = page
+        data, _ = github_request(token, "GET", path, params=base_params)
+        if not isinstance(data, list):
+            raise TypeError("Expected a paginated GitHub list")
+        results.extend(data)
+        if len(data) < int(base_params["per_page"]):
+            return results
+    raise RuntimeError("GitHub pagination exceeded limit")
+
+
+class GitHubRepository:
+    name = "GitHub automation"
+
+    def __init__(
+        self,
+        config_path=Path("config.json"),
+        *,
+        github_token_secret,
+        repository=None,
+        conversation=None,
+        dispatcher=None,
+    ):
+        self.config = json.loads(Path(config_path).read_text())
+        self.repository = repository or self.config["repository"]
+        if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", self.repository):
+            raise ValueError("repository must be owner/repo")
+        if not re.fullmatch(r"[A-Z_][A-Z0-9_]*", github_token_secret):
+            raise ValueError(
+                "Expected the environment variable containing the GitHub token"
+            )
+        self.token_name = github_token_secret
+        self.token = _load_secret(github_token_secret)
+        self.conversation = conversation
+        self.conversation_id = str(conversation.id) if conversation else None
+        self.dispatcher = dispatcher
+        self.workspace = Path(os.environ["WORKSPACE_BASE"])
+        self.project = self.workspace
+        self.evidence = self.workspace / "evidence"
+        self.evidence.mkdir(exist_ok=True)
+        self._completed_dependencies = {}
+
+    @cached_property
+    def base_branch(self):
+        return self.config.get("base_branch") or self.gh("GET", "")["default_branch"]
+
+    @property
+    def github_instructions(self):
+        return (
+            f"Use `GH_TOKEN=${self.token_name} gh api` for GitHub requests. "
+            "Never print the credential value. "
+            f"Only {self.repository} is in scope. Work in {self.project}. "
+            "Do not modify the automation bundle or its configuration."
+        )
+
+    def gh(self, method, path, body=None):
+        return github_request(
+            self.token, method, f"/repos/{self.repository}" + path, body=body
+        )[0]
+
+    def shell(self, args, cwd=None, timeout=300):
+        result = subprocess.run(
+            args,
+            cwd=cwd or self.project,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            timeout=timeout,
+            check=False,
+        )
+        if result.returncode:
+            raise RuntimeError(
+                f"{args[0]} failed: {result.stdout[-4000:].replace(self.token, '[REDACTED]')}"
+            )
+        return result.stdout.strip()
+
+    def comment(self, number, text):
+        return self.gh(
+            "POST",
+            f"/issues/{number}/comments",
+            {
+                "body": text
+                + f"\n\nFactory role: `{self.name}`; conversation: `{self.conversation_id}`."
+                + "\n\n_This comment was posted by an AI agent (OpenHands)._"
+            },
+        )
+
+    def open_issues(self):
+        return [
+            i for i in self.gh_pages("/issues?state=open") if "pull_request" not in i
+        ]
+
+    def statuses(self, sha):
+        result = {}
+        for item in self.gh_pages(f"/commits/{sha}/statuses"):
+            result.setdefault(item["context"], item["state"])
+        return result
+
+    def completed_dependency(self, number):
+        if number in self._completed_dependencies:
+            return self._completed_dependencies[number]
+        try:
+            dependency = self.gh("GET", f"/issues/{number}")
+        except HTTPError as exc:
+            if exc.code == 404:
+                return False
+            raise
+        completed = (
+            dependency["state"] == "closed"
+            and dependency.get("state_reason") == "completed"
+        )
+        self._completed_dependencies[number] = completed
+        return completed
+
+    def dependencies_complete(self, issue):
+        """Honor explicit Depends on lines; unknown/incomplete issues remain blocked."""
+        for line in re.findall(
+            "^Depends on:\\s*(.+)$",
+            issue.get("body") or "",
+            re.MULTILINE | re.IGNORECASE,
+        ):
+            for number in re.findall("#(\\d+)", line):
+                if not self.completed_dependency(number):
+                    return False
+        return True
+
+    def gh_pages(self, endpoint):
+        split = urlsplit(endpoint)
+        return github_paginate(
+            self.token,
+            f"/repos/{self.repository}" + split.path,
+            params=dict(parse_qsl(split.query)),
+        )
+
+
+def run_repositories(automation_type, conversation=None, dispatcher=None):
+    parser = argparse.ArgumentParser(description=automation_type.__doc__)
+    parser.add_argument("--github-token-secret")
+    args = parser.parse_args()
+    config = json.loads(Path("config.json").read_text())
+    token_name = args.github_token_secret or config.get(
+        "github_token_secret", "GITHUB_PERSONAL_ACCESS_TOKEN"
+    )
+    repositories = config.get("repos") or [config["repository"]]
+    failures = []
+    for repository in repositories:
+        options = dict(
+            github_token_secret=token_name,
+            repository=repository,
+            conversation=conversation,
+        )
+        if dispatcher is not None:
+            options["dispatcher"] = dispatcher
+        automation = automation_type(**options)
+        try:
+            automation.run()
+        except Exception as exc:  # noqa: BLE001 - one repository must not block others
+            failures.append(repository)
+            print(
+                json.dumps({"repository": repository, "error": type(exc).__name__}),
+                flush=True,
+            )
+    if failures:
+        raise RuntimeError("Automation failed for: " + ", ".join(failures))
+    return str(conversation.id) if conversation else None

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

@@ -33,7 +33,9 @@ import urllib.error
 import urllib.request
 from collections.abc import Callable
 from pathlib import Path
-from urllib.parse import urlencode
+
+from github_client import github_request as _github_request
+from github_client import github_paginate as _github_paginate
 
 # Configuration. Two setup paths write it, and both end up here:
 #
@@ -350,45 +352,6 @@ def save_state(repo: str, state: dict) -> None:
 # ── GitHub REST ───────────────────────────────────────────────────────────────
 
 
-def _github_request(
-    token: str,
-    method: str,
-    path: str,
-    params: dict | None = None,
-    body: dict | None = None,
-) -> tuple:
-    url = f"https://api.github.com{path}"
-    if params:
-        url = f"{url}?{urlencode(params)}"
-    headers = {
-        "Authorization": f"Bearer {token}",
-        "Accept": "application/vnd.github+json",
-        "X-GitHub-Api-Version": "2022-11-28",
-        "Content-Type": "application/json",
-    }
-    data = json.dumps(body).encode() if body is not None else None
-    req = urllib.request.Request(url, data=data, headers=headers, method=method)
-    with urllib.request.urlopen(req) as r:
-        raw = r.read()
-        return (json.loads(raw) if raw.strip() else {}), dict(r.headers)
-
-
-def _github_paginate(token: str, path: str, params: dict | None = None) -> list:
-    results = []
-    page = 1
-    base_params = dict(params or {})
-    base_params.setdefault("per_page", 100)
-    while True:
-        base_params["page"] = page
-        data, _ = _github_request(token, "GET", path, params=base_params)
-        if not isinstance(data, list):
-            break
-        results.extend(data)
-        if len(data) < base_params["per_page"]:
-            break
-        page += 1
-    return results
-
 
 def _resolve_github_token() -> str:
     try:
@@ -819,6 +782,9 @@ def _build_implementation_prompt(
     branch: str,
     base_branch: str,
     base_sha: str,
+    *,
+    workspace_instructions: str | None = None,
+    github_token_secret: str = "GITHUB_PERSONAL_ACCESS_TOKEN",
 ) -> str:
     """Name the issue and let the agent gather the rest.
 
@@ -831,28 +797,31 @@ def _build_implementation_prompt(
     title = issue.get("title", "(no title)").replace('"', "'")
     draft_words = " as a draft" if DRAFT_PULL_REQUEST else " ready for review"
     draft_flag = " --draft" if DRAFT_PULL_REQUEST else ""
+    secret_ref = f"${github_token_secret}"
+    workspace = workspace_instructions or (
+        f"It is a clone of `{base_branch}` at `{base_sha}`, already on branch "
+        f"`{branch}`. Do not clone or check out anything else: the code you need is "
+        "already here, and the branch is the one the pull request comes from."
+    )
 
     return (
-        "You are an autonomous software engineer. Implement the GitHub issue below in "
-        "the repository already checked out as your working directory.\n\n"
+        "You are an autonomous software engineer. Implement the GitHub issue below.\n\n"
         f"Repository : {repo}\n"
         f"Issue      : #{number} - \"{title}\"\n"
         f"URL        : {issue.get('html_url', '')}\n"
         f"Trigger    : latest `{TRIGGER_LABEL}` labeled event {label_event.get('id', '?')} "
         f"at {label_event.get('created_at', '?')}\n\n"
         "Your workspace:\n"
-        f"- It is a clone of `{base_branch}` at `{base_sha}`, already on branch "
-        f"`{branch}`. Do not clone or check out anything else: the code you need is "
-        "already here, and the branch is the one the pull request comes from.\n"
-        "- `origin` carries no credential. Every command that talks to GitHub must "
-        "name `GITHUB_PERSONAL_ACCESS_TOKEN`, because the value is only put in the "
+        f"- {workspace}\n"
+        "- Every command that talks to GitHub must explicitly name "
+        f"`{github_token_secret}`, because the value is only put in the "
         "environment of a command that mentions it. Never echo it.\n\n"
         "Required workflow:\n"
         "1. Read the issue first. Its title above is all you have been told; fetch the "
         "rest yourself:\n"
         f"   `gh issue view {number} --repo {repo} --comments`, or the REST API - "
         f"`/repos/{repo}/issues/{number}` and `/repos/{repo}/issues/{number}/comments` - "
-        "authenticated with `GITHUB_PERSONAL_ACCESS_TOKEN`. Never print the token.\n"
+        "using the GitHub credential named above. Never print the token.\n"
         "2. Follow what the issue points at as far as it matters: linked issues and pull "
         "requests, referenced files, failing runs, prior art in the history.\n"
         "3. Read enough of the codebase to place the change where it belongs and to "
@@ -864,10 +833,10 @@ def _build_implementation_prompt(
         "6. Delete scratch files, build output, and virtualenvs the repository does not "
         f"already ignore, then commit everything on `{branch}`.\n"
         "7. Push the branch:\n"
-        f"   `git push \"https://x-access-token:$GITHUB_PERSONAL_ACCESS_TOKEN@github.com/"
+        f"   `git push \"https://x-access-token:{secret_ref}@github.com/"
         f"{repo}.git\" HEAD:refs/heads/{branch}`\n"
         f"8. Open the pull request{draft_words}:\n"
-        f"   `GH_TOKEN=$GITHUB_PERSONAL_ACCESS_TOKEN gh pr create --repo {repo} "
+        f"   `GH_TOKEN={secret_ref} gh pr create --repo {repo} "
         f"--base {base_branch} --head {branch}{draft_flag} --title \"[#{number}] {title}\" "
         "--body-file <file>`\n"
         "   The body is your pull request description - what changed, why, and what a "