@openhands/extensions 0.21.0 → 0.22.1

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

@@ -782,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.
 
@@ -794,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 "
@@ -827,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 "

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

@@ -0,0 +1,172 @@
+"""Select ready GitHub work and delegate each subject to a sandboxed agent."""
+
+import json
+import re
+
+import main as workflow
+from agent_conversation import AgentConversationDispatcher
+from github_client import GitHubRepository, run_repositories
+
+
+class IssueToPR(GitHubRepository):
+    name = "github-issue-to-pr"
+
+    def _workspace_instructions(self, branch, revision):
+        token = self.token_name
+        if revision:
+            checkout = f"check out the existing remote branch `{branch}`"
+        else:
+            checkout = (
+                f"create and check out `{branch}` from the repository's base branch"
+            )
+        return (
+            "The workspace starts empty. Clone the repository into it with "
+            f"`GH_TOKEN=${{{token}}} gh repo clone {self.repository} .`, then {checkout}. "
+            "Keep the remote free of embedded credentials."
+        )
+
+    def _prompt(self, issue, branch, base_branch, base_sha, *, revision=None):
+        review_label = self.config.get("review_label", "openhands-review")
+        prompt = workflow._build_implementation_prompt(
+            self.repository,
+            issue,
+            {
+                "id": issue.get("updated_at", "?"),
+                "created_at": issue.get("updated_at", "?"),
+            },
+            branch,
+            base_branch,
+            base_sha,
+            workspace_instructions=self._workspace_instructions(branch, revision),
+            github_token_secret=self.token_name,
+        )
+        if revision:
+            prompt = (
+                f"Revise existing PR #{revision['number']} at exact head "
+                f"`{revision['head']['sha']}`. Read its current reviews, inline "
+                "comments, discussion, and failing checks directly from GitHub. "
+                "Address each current finding or explain with evidence why no code "
+                "change is warranted. Push revisions to the existing branch; do not "
+                "open another pull request. After responding, remove and reapply the "
+                f"`{review_label}` label so the exact new head is reviewed. If no code "
+                "change is needed, post that evidence on the PR before reapplying it.\n\n"
+                + prompt
+            )
+        else:
+            prompt += (
+                f"\n\nAfter opening the pull request, add the `{review_label}` label so "
+                "the independent reviewer checks its exact head."
+            )
+        return prompt
+
+    def _submit(
+        self, repository_id, issue, branch, base_branch, base_sha, *, revision=None
+    ):
+        revision_sha = revision["head"]["sha"] if revision else None
+        key = revision_sha or issue.get("updated_at") or str(issue["number"])
+        result = self.dispatcher.deliver(
+            subject=f"{repository_id}:issue:{issue['number']}",
+            delivery=f"{issue['number']}:{key}",
+            prompt=self._prompt(
+                issue,
+                branch,
+                base_branch,
+                revision_sha or base_sha,
+                revision=revision,
+            ),
+        )
+        print(
+            json.dumps(
+                {
+                    "repository": self.repository,
+                    "issue": issue["number"],
+                    "pr": revision["number"] if revision else None,
+                    "disposition": result["disposition"],
+                    "conversation_id": result["conversation_id"],
+                }
+            ),
+            flush=True,
+        )
+
+    def _try_submit(
+        self, repository_id, issue, branch, base_branch, base_sha, *, revision=None
+    ):
+        try:
+            self._submit(
+                repository_id,
+                issue,
+                branch,
+                base_branch,
+                base_sha,
+                revision=revision,
+            )
+        except Exception as exc:  # noqa: BLE001 - one issue must not block the scan
+            print(
+                f"Failed to submit {self.repository} issue "
+                f"#{issue.get('number', '?')}: {exc}",
+                flush=True,
+            )
+
+    def run(self):
+        trigger_label = self.config.get("trigger_label", workflow.TRIGGER_LABEL)
+        branch_prefix = self.config.get("branch_prefix", workflow.BRANCH_PREFIX)
+        repository = self.gh("GET", "")
+        repository_id = repository["id"]
+        base_branch = self.config.get("base_branch") or repository["default_branch"]
+        base_sha = self.gh("GET", f"/git/ref/heads/{base_branch}")["object"]["sha"]
+        issues = {issue["number"]: issue for issue in self.open_issues()}
+
+        open_prs = self.gh_pages("/pulls?state=open")
+        issue_prs = {}
+        for pr in open_prs:
+            match = re.fullmatch(
+                re.escape(branch_prefix) + r"-(\d+)", pr["head"]["ref"]
+            )
+            if match:
+                issue_prs[int(match[1])] = pr
+
+        for issue_number, pr in sorted(issue_prs.items()):
+            issue = issues.get(issue_number)
+            if issue is None:
+                continue
+            if self.statuses(pr["head"]["sha"]).get("software-factory/review") not in {
+                "failure",
+                "error",
+            }:
+                continue
+            self._try_submit(
+                repository_id,
+                issue,
+                pr["head"]["ref"],
+                (pr.get("base") or {}).get("ref") or base_branch,
+                base_sha,
+                revision=pr,
+            )
+
+        ready = [
+            issue
+            for issue in issues.values()
+            if issue["number"] not in issue_prs
+            and trigger_label in {label["name"] for label in issue.get("labels", [])}
+            and self.dependencies_complete(issue)
+        ]
+        for issue in sorted(
+            ready,
+            key=lambda item: (
+                "priority:high"
+                not in {label["name"] for label in item.get("labels", [])},
+                item["number"],
+            ),
+        ):
+            self._try_submit(
+                repository_id,
+                issue,
+                f"{branch_prefix}-{issue['number']}",
+                base_branch,
+                base_sha,
+            )
+
+
+if __name__ == "__main__":
+    with AgentConversationDispatcher() as dispatcher:
+        run_repositories(IssueToPR, dispatcher=dispatcher)

package/skills/github-issue-triage/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "github-issue-triage",
+  "version": "1.0.0",
+  "description": "Prioritize open issues and establish acceptance criteria before marking them ready for development.",
+  "author": {
+    "name": "OpenHands"
+  },
+  "license": "MIT"
+}

package/skills/github-issue-triage/.codex-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "github-issue-triage",
+  "version": "1.0.0",
+  "description": "Prioritize open issues and establish acceptance criteria before marking them ready for development.",
+  "author": {
+    "name": "OpenHands"
+  },
+  "license": "MIT"
+}

package/skills/github-issue-triage/SKILL.md

@@ -9,29 +9,26 @@ triggers:
 
 Prioritize open issues and establish acceptance criteria before marking them ready for development.
 
-Create this automation separately from implementation and review. Select an agent
-profile on its definition. The profile owns the model, tools, and `secret_refs`;
-this workflow does not choose a profile or discover credentials from host settings.
-Use a fine-grained GitHub PAT limited to the selected repositories with
-Issues: read and write. Store it in the Agent Server secret store and select its name in
-the profile. Never put the token value in the automation definition or prompt.
+Create this automation separately from implementation and review. Use a
+fine-grained GitHub PAT limited to the selected repositories with Issues: read and
+write. Never put the token value in the automation definition or prompt.
 
-Package the files in this skill’s `scripts/` directory together.
-`github_client.py` is installed alongside `worker.py` from the shared GitHub source.
-The catalog bundle declares these exact files. Supply `config.json` with `repos`
-(an array of `owner/repo` names). The entrypoint is `python3 worker.py
---github-token-secret GITHUB_PERSONAL_ACCESS_TOKEN`; if the selected profile uses
-another secret name, pass that name instead. Naming a secret does not grant it:
-the Agent Server only supplies secrets allowed by the profile.
+Package `worker.py` with the shared `github_client.py` and
+`agent_conversation.py` helpers. Supply `config.json` with `repos` and the saved
+GitHub secret name; the entrypoint is `python3 worker.py`. Include that secret in
+the selected profile so the delegated agent can use GitHub. Naming it in the
+automation does not grant it to the agent.
 
-The same bundle runs in local and Docker workspaces. The Automation Service
-provides the conversation, workspace, and scoped server connection; it owns
-scheduling, concurrency, cancellation, and cleanup.
+The scanner is an ordinary Automation host command. It submits selected issues
+through the shared KV-backed conversation dispatcher, which creates or resumes
+one stable conversation per issue through the Software Agent SDK. Only that
+agent workspace is local or Docker. Automation owns scheduling, cancellation,
+and cleanup.
 
 Honor `Depends on: #12, #13` lines. A dependency must be closed as completed.
 Post readable acceptance criteria and rationale. Add `ready-for-dev` only when
 criteria are actionable; preserve existing issue labels. Unclear issues stay open
 for clarification. Do not implement code or accept pull requests.
 
-Each scheduled run triages at most one changed issue per repository. Choose the
-schedule frequency accordingly when processing an existing backlog.
+Each scheduled run submits every changed eligible issue. A failure on one issue is
+reported and does not prevent the remaining issues from being submitted.