@openhands/extensions 0.21.0 → 0.22.0

package/skills/github-delivery-watchdog/commands/github-delivery-watchdog.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Periodically check pull requests and merge only current heads with independent review, tests, and passing CI.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/skills/github-delivery-watchdog/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-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

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),
+        }