@openhands/extensions 0.21.0 → 0.22.0

package/skills/frontend-design/.codex-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "frontend-design",
+  "version": "1.0.0",
+  "description": "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications. Generates c...",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "frontend",
+    "design",
+    "ui",
+    "web",
+    "react",
+    "html",
+    "css"
+  ]
+}

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

@@ -0,0 +1,19 @@
+{
+  "name": "github",
+  "version": "1.0.0",
+  "description": "Interact with GitHub repositories, pull requests, issues, and workflows using the GITHUB_TOKEN environment variable and GitHub CLI. Use when working with code hosted on GitHub or managing GitHub re...",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "git",
+    "pull-request",
+    "issues",
+    "workflows"
+  ]
+}

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

@@ -0,0 +1,19 @@
+{
+  "name": "github",
+  "version": "1.0.0",
+  "description": "Interact with GitHub repositories, pull requests, issues, and workflows using the GITHUB_TOKEN environment variable and GitHub CLI. Use when working with code hosted on GitHub or managing GitHub re...",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "git",
+    "pull-request",
+    "issues",
+    "workflows"
+  ]
+}

package/skills/github/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/scripts/github_client.py

@@ -12,6 +12,29 @@ 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,
@@ -61,6 +84,7 @@ class GitHubRepository:
         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"]
@@ -71,11 +95,10 @@ class GitHubRepository:
                 "Expected the environment variable containing the GitHub token"
             )
         self.token_name = github_token_secret
-        self.token = os.environ[github_token_secret]
-        if not self.token:
-            raise ValueError("The GitHub credential is empty")
+        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"
@@ -175,7 +198,7 @@ class GitHubRepository:
         )
 
 
-def run_repositories(automation_type, conversation=None):
+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()
@@ -186,11 +209,14 @@ def run_repositories(automation_type, conversation=None):
     repositories = config.get("repos") or [config["repository"]]
     failures = []
     for repository in repositories:
-        automation = automation_type(
+        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

package/skills/github-actions/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "github-actions",
+  "version": "1.0.0",
+  "description": "Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating workflows, or troubleshooting GitHub Actions.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github-actions",
+    "workflows",
+    "ci-cd",
+    "automation",
+    "actions"
+  ]
+}

package/skills/github-actions/.codex-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "github-actions",
+  "version": "1.0.0",
+  "description": "Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating workflows, or troubleshooting GitHub Actions.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github-actions",
+    "workflows",
+    "ci-cd",
+    "automation",
+    "actions"
+  ]
+}

package/skills/github-agents-md-maintainer/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "github-agents-md-maintainer",
+  "version": "1.0.0",
+  "description": "Create an automation that keeps AGENTS.md current in one or more GitHub repositories. On a schedule it clones the default branch, has an agent read the repository and create or update AGENTS.md, and opens a pull request - staying quiet while one of its own pull requests is still open.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "agents-md",
+    "documentation",
+    "maintenance",
+    "automation"
+  ]
+}

package/skills/github-agents-md-maintainer/.codex-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "github-agents-md-maintainer",
+  "version": "1.0.0",
+  "description": "Create an automation that keeps AGENTS.md current in one or more GitHub repositories. On a schedule it clones the default branch, has an agent read the repository and create or update AGENTS.md, and opens a pull request - staying quiet while one of its own pull requests is still open.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "agents-md",
+    "documentation",
+    "maintenance",
+    "automation"
+  ]
+}

package/skills/github-agents-md-maintainer/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/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "github-delivery-watchdog",
+  "version": "1.0.0",
+  "description": "Periodically check pull requests and merge only current heads with independent review, tests, and passing CI.",
+  "author": {
+    "name": "OpenHands"
+  },
+  "license": "MIT"
+}

package/skills/github-delivery-watchdog/.codex-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "github-delivery-watchdog",
+  "version": "1.0.0",
+  "description": "Periodically check pull requests and merge only current heads with independent review, tests, and passing CI.",
+  "author": {
+    "name": "OpenHands"
+  },
+  "license": "MIT"
+}

package/skills/github-delivery-watchdog/.plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "github-delivery-watchdog",
+  "version": "1.0.0",
+  "description": "Periodically check pull requests and merge only current heads with independent review, tests, and passing CI.",
+  "author": {
+    "name": "OpenHands"
+  },
+  "license": "MIT"
+}

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

@@ -0,0 +1,10 @@
+# GitHub delivery watchdog
+
+Periodically check pull requests and merge only current heads with independent review, tests, and passing CI.
+
+Run this independently from issue triage, implementation, and review. Configure
+a repository-scoped fine-grained PAT by its saved secret name. The watchdog uses
+Actions and commit statuses and sends a conditional merge request for the exact
+accepted head. It does not create an agent or change application code.
+
+See [SKILL.md](SKILL.md) for permissions, acceptance gates, and configuration.

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

@@ -0,0 +1,35 @@
+---
+name: github-delivery-watchdog
+description: Periodically check pull requests and merge only current heads with independent review, tests, and passing CI.
+triggers:
+- /github-delivery-watchdog
+---
+
+# GitHub delivery watchdog
+
+This is a deterministic scheduled host command. It creates no agent or
+conversation and needs no agent profile. Configure a repository-scoped
+fine-grained PAT with Contents and Issues read/write plus Pull requests, Actions,
+Commit statuses, and Metadata read. Contents write permits merge; Issues write
+retains the review label when the branch is updated. Never put the token value in
+the automation definition.
+
+Package `scripts/worker.py` as `worker.py` and the shared
+`scripts/github_client.py` as `github_client.py`.
+The catalog bundle declares these exact files. Its `config.json` supplies
+`repos`, `branch_prefix`, and the saved secret name. The shared GitHub client
+resolves only that named secret. Automation owns scheduling and cancellation.
+
+Set `branch_prefix` (default `openhands/issue`), `base_branch` (defaults to the repository's default branch),
+and `required_workflow_ids` when particular Actions workflows must run. The
+watchdog requires `software-factory/tests` and `software-factory/review` success
+statuses on the exact head, all other statuses and Actions passing, a current
+base, a non-draft PR, and GitHub reporting it mergeable. Missing, pending, failed,
+or inaccessible evidence does not permit merge. A changed head requires fresh
+review and tests. When an accepted branch is behind the base, the watchdog asks
+GitHub to update it and retains the review trigger label; it considers the new
+head only on a later run. The merge request includes the expected head SHA.
+
+Actions are optional when `required_workflow_ids` is empty; the two acceptance
+statuses remain mandatory. Configure workflow IDs when GitHub Actions must also
+supply evidence. Branch protection remains GitHub's final merge gate.