@openhands/extensions 0.28.0 → 0.30.0

package/skills/github-issue-triage/scripts/agent_conversation.py

@@ -3,7 +3,9 @@
 import json
 import os
 import time
+from collections.abc import Callable
 from urllib.error import HTTPError
+from urllib.parse import urlencode
 from urllib.request import Request, urlopen
 from uuid import NAMESPACE_URL, UUID, uuid4, uuid5
 
@@ -113,6 +115,10 @@ class CloudConversations:
             },
         )
 
+    def agent_profiles(self) -> list[dict]:
+        listing = self._request("GET", "/api/agent-profiles")
+        return (listing or {}).get("profiles") or []
+
     def run(self, conversation: dict) -> None:
         """Start the next turn of an idle conversation on its own Agent Server."""
         try:
@@ -152,6 +158,17 @@ def _user_message(text: str) -> dict:
     return {"role": "user", "content": [{"type": "text", "text": text}]}
 
 
+def _render(prompt, conversation_id) -> str:
+    """The text of `prompt` for the conversation it is delivered to.
+
+    A caller that must name the receiving conversation in its own prompt (a
+    marker the deterministic side later looks for, say) passes a function of
+    the conversation id, because only delivery decides which conversation that
+    is.
+    """
+    return prompt(str(conversation_id)) if callable(prompt) else prompt
+
+
 class AgentConversationDispatcher:
     """Deliver one revision at a time to a stable conversation for each subject."""
 
@@ -189,7 +206,11 @@ class AgentConversationDispatcher:
         return self._workspace.__exit__(*args)
 
     def deliver(
-        self, subject: str, delivery: str, prompt: str, head: str = ""
+        self,
+        subject: str,
+        delivery: str,
+        prompt: str | Callable[[str], str],
+        head: str = "",
     ) -> dict[str, str]:
         """Deliver one revision of `subject`, deduping a repeated head.
 
@@ -202,6 +223,7 @@ class AgentConversationDispatcher:
         A conversation already running for this head is reported `in_progress`
         and left alone, whatever the new delivery says. Callers with no revision
         identity leave `head` empty and keep the delivery-key-only behavior.
+        `prompt` may be a function of the receiving conversation's id.
         """
         conversation_id = uuid5(NAMESPACE_URL, f"{self.automation_id}:{subject}")
         state_key = f"{_CONVERSATION_KEY_PREFIX}{conversation_id}"
@@ -252,6 +274,67 @@ class AgentConversationDispatcher:
             "conversation_id": str(conversation_id),
         }
 
+    def subject_conversation(self, subject: str) -> str | None:
+        """The conversation this automation currently delivers `subject` to."""
+        conversation_id = uuid5(NAMESPACE_URL, f"{self.automation_id}:{subject}")
+        record = _kv_request(f"{_CONVERSATION_KEY_PREFIX}{conversation_id}", "GET")
+        return (record or {}).get("conversation_id") or None
+
+    def llm_provenance(self, conversation_id: str) -> tuple[str, str] | None:
+        """The LLM profile name and model a conversation runs, or None if it is gone.
+
+        Both are read back from the conversation, never from the automation's
+        current settings: the server resolves the agent profile when it starts
+        the conversation, and a reused conversation keeps that LLM after the
+        profile is edited. The model is the conversation's own. The LLM profile
+        name comes from the launching agent profile only while that profile is
+        still at its launch revision, and is `unknown` otherwise.
+        """
+        if self._cloud:
+            conversation = self._cloud.get(conversation_id)
+            if conversation is None:
+                return None
+            model = conversation.get("llm_model")
+        else:
+            try:
+                conversation = self._agent_server_get(
+                    f"/api/conversations/{conversation_id}"
+                )
+            except HTTPError as exc:
+                if exc.code == 404:
+                    return None
+                raise
+            agent = conversation.get("agent") or {}
+            model = conversation.get("current_model_id")
+            if model is None and agent.get("kind") != "ACPAgent":
+                model = (agent.get("llm") or {}).get("model")
+        launched = conversation.get("launched_agent_profile") or {}
+        profile = "unknown"
+        if launched.get("agent_profile_id"):
+            try:
+                if self._cloud:
+                    profiles = self._cloud.agent_profiles()
+                else:
+                    listing = self._agent_server_get("/api/agent-profiles")
+                    profiles = (listing or {}).get("profiles") or []
+            except Exception as exc:  # noqa: BLE001 - the model is still known
+                print(f"Could not read agent profiles: {type(exc).__name__}: {exc}")
+                profiles = []
+            for item in profiles:
+                if str(item.get("id")) == str(launched["agent_profile_id"]):
+                    if item.get("revision") == launched.get("revision"):
+                        profile = item.get("llm_profile_ref") or "unknown"
+                    break
+        return profile, model or "unknown"
+
+    def _agent_server_get(self, path: str) -> dict:
+        request = Request(
+            f"{self.agent_url.rstrip('/')}{path}",
+            headers={"X-Session-API-Key": self.api_key},
+        )
+        with urlopen(request, timeout=90) as response:
+            return json.load(response)
+
     def _deliver_cloud(
         self,
         record,
@@ -287,7 +370,9 @@ class AgentConversationDispatcher:
 
         if conversation is None:
             new_id = uuid4() if record else conversation_id
-            self._cloud.start(new_id, self.profile_id, subject, prompt)
+            self._cloud.start(
+                new_id, self.profile_id, subject, _render(prompt, new_id)
+            )
             return "created", new_id
 
         status = conversation.get("execution_status")
@@ -303,10 +388,10 @@ class AgentConversationDispatcher:
                 # The API reports an execution status only while the sandbox
                 # runs, so an errored conversation whose sandbox was already
                 # paused is not seen here and keeps reporting deduplicated.
-                self._cloud.send(conversation, prompt)
+                self._cloud.send(conversation, _render(prompt, current_id))
                 return "retried", current_id
             return "deduplicated", current_id
-        self._cloud.send(conversation, prompt)
+        self._cloud.send(conversation, _render(prompt, current_id))
         return "resumed", current_id
 
     def _deliver_local(
@@ -326,12 +411,13 @@ class AgentConversationDispatcher:
             conversation = RemoteConversation.create(
                 self._workspace,
                 StartConversationRequest(
-                    workspace=LocalWorkspace(working_dir="/workspace"),
+                    workspace=LocalWorkspace(working_dir=self._workspace.working_dir),
                     conversation_id=conversation_id,
                     agent_profile_id=self.profile_id,
                     secrets=self._secrets,
                     initial_message=SendMessageRequest(
-                        content=[TextContent(text=prompt)], run=True
+                        content=[TextContent(text=_render(prompt, conversation_id))],
+                        run=True,
                     ),
                 ),
                 visualizer=None,
@@ -365,7 +451,7 @@ class AgentConversationDispatcher:
                         # the work finished, so send the revision again rather
                         # than strand it.
                         conversation.update_secrets(self._secrets)
-                        conversation.send_message(prompt)
+                        conversation.send_message(_render(prompt, conversation_id))
                         conversation.run(blocking=False)
                         disposition = "retried"
                     else:
@@ -375,8 +461,138 @@ class AgentConversationDispatcher:
                     # work on the same subject: reuse the conversation and send
                     # the revision as its next turn.
                     conversation.update_secrets(self._secrets)
-                    conversation.send_message(prompt)
+                    conversation.send_message(_render(prompt, conversation_id))
                     conversation.run(blocking=False)
         finally:
             conversation.close()
         return disposition
+
+    def review_snapshot(self, conversation_id):
+        if self._cloud:
+            conversation = self._cloud.get(conversation_id)
+            if conversation is None:
+                return "missing", ""
+            status = conversation.get("execution_status", "unknown")
+            if status != "finished":
+                return status, ""
+            result = self._cloud._request(
+                "GET",
+                f"{conversation['conversation_url']}/agent_final_response",
+                headers={"X-Session-API-Key": conversation["session_api_key"]},
+            )
+            return status, result.get("response", "")
+        headers = {"X-Session-API-Key": self.api_key}
+        base = f"{self.agent_url.rstrip('/')}/api/conversations/{conversation_id}"
+        try:
+            with urlopen(Request(base, headers=headers), timeout=90) as response:
+                status = json.load(response).get("execution_status", "unknown")
+        except HTTPError as exc:
+            if exc.code == 404:
+                return "missing", ""
+            raise
+        if status != "finished":
+            return status, ""
+        with urlopen(
+            Request(base + "/agent_final_response", headers=headers), timeout=90
+        ) as response:
+            return status, json.load(response).get("response", "")
+
+    def start_review_work(self, conversation_id, subject, prompt):
+        if self._cloud:
+            self._cloud.start(UUID(conversation_id), self.profile_id, subject, prompt)
+            return
+        if self._workspace is None:
+            raise RuntimeError("Dispatcher must be used as a context")
+        conversation = RemoteConversation.create(
+            self._workspace,
+            StartConversationRequest(
+                workspace=LocalWorkspace(working_dir=self._workspace.working_dir),
+                conversation_id=UUID(conversation_id),
+                agent_profile_id=self.profile_id,
+                secrets=self._secrets,
+                initial_message=SendMessageRequest(
+                    content=[TextContent(text=prompt)], run=True
+                ),
+            ),
+            visualizer=None,
+        )
+        conversation.close()
+
+
+class ReviewCoordination:
+    """CAS against the automation service's shared, user-authorized KV namespace."""
+
+    def __init__(self):
+        namespace = os.environ.get("REVIEW_COORDINATION_AUTOMATION_ID")
+        key = os.environ.get("REVIEW_COORDINATION_API_KEY")
+        if not namespace or not key:
+            raise RuntimeError(
+                "Structured reviews require shared coordination namespace and API key"
+            )
+        self.query = urlencode({"automation_id": str(UUID(namespace))})
+        self.base = os.environ["AUTOMATION_API_URL"].rstrip("/")
+        self.headers = {"X-Session-API-Key": key, "Content-Type": "application/json"}
+
+    def request(self, key, method="GET", value=None, condition=""):
+        request = Request(
+            f"{self.base}/v1/kv/{key}?{self.query}&{condition}",
+            data=None if value is None else json.dumps(value).encode(),
+            headers=self.headers,
+            method=method,
+        )
+        try:
+            with urlopen(request, timeout=90) as response:
+                return json.load(response)
+        except HTTPError as exc:
+            if method == "GET" and exc.code == 404:
+                return None
+            raise
+
+    def claim(self, subject, *, existing_only=False):
+        key = "review-work-" + str(uuid5(NAMESPACE_URL, subject))
+        for _ in range(5):
+            current = self.request(key, condition="meta=true")
+            if current is None and existing_only:
+                return None
+            value = (current or {}).get("value") or {}
+            if value.get("lease_until", 0) > time.time():
+                return None
+            value = {**value, "owner": str(uuid4()), "lease_until": time.time() + 180}
+            condition = f"if_version={current['version']}" if current else "nx=true"
+            try:
+                self.request(key, "PUT", value, condition)
+                return ReviewLease(self, key, value)
+            except HTTPError as exc:
+                if exc.code != 409:
+                    raise
+        return None
+
+
+class ReviewLease:
+    def __init__(self, store, key, value):
+        self.store, self.key, self.value = store, key, value
+        self.owner = value["owner"]
+
+    def save(self, **changes):
+        for _ in range(5):
+            current = self.store.request(self.key, condition="meta=true")
+            value = current["value"]
+            if (
+                value.get("owner") != self.owner
+                or value.get("lease_until", 0) <= time.time()
+            ):
+                raise RuntimeError("Review lease lost; refusing side effects")
+            updated = {**self.value, **changes}
+            try:
+                self.store.request(
+                    self.key, "PUT", updated, f"if_version={current['version']}"
+                )
+                self.value = updated
+                return
+            except HTTPError as exc:
+                if exc.code != 409:
+                    raise
+        raise RuntimeError("Review coordination contention; retry next scan")
+
+    def release(self):
+        self.save(lease_until=0)

package/skills/github-issue-triage/scripts/triage_publication.py

@@ -0,0 +1,293 @@
+"""Pure triage contracts and optimistic, fail-closed GitHub publication."""
+
+import argparse
+import hashlib
+import json
+import re
+from pathlib import Path
+from urllib.parse import quote, unquote
+
+from github_client import GitHubRepository
+
+START = "<!-- openhands-ai-triage:start -->"
+END = "<!-- openhands-ai-triage:end -->"
+VERSION = 3
+DISCLOSURE = "_Generated by an AI agent (OpenHands) on behalf of the automation owner._"
+
+
+def split_body(body):
+    body = body or ""
+    if START not in body and END not in body:
+        return body, "", ""
+    if body.count(START) != 1 or body.count(END) != 1:
+        raise ValueError("Ambiguous managed markers; human repair required")
+    start, end = body.index(START), body.index(END)
+    if end < start:
+        raise ValueError("Reversed managed markers")
+    return body[:start], body[start : end + len(END)], body[end + len(END) :]
+
+
+def author_body(body):
+    before, _, after = split_body(body)
+    return (before + after).rstrip()
+
+
+def owned_comment(comment, login):
+    return (
+        bool(login)
+        and (comment.get("user") or {}).get("login") == login
+        and bool(
+            re.search(r"<!-- triage-source:[a-f0-9]{64} -->", comment.get("body") or "")
+        )
+    )
+
+
+def readiness_comment(comment):
+    return (comment.get("user") or {}).get(
+        "login"
+    ) == "github-actions[bot]" and "<!-- issue-readiness-check -->" in (
+        comment.get("body") or ""
+    )
+
+
+def readiness_transitions(repo, number, login):
+    return [
+        (e.get("id"), e.get("event"), e.get("created_at"))
+        for e in repo.gh_pages(f"/issues/{number}/timeline")
+        if e.get("event") in {"labeled", "unlabeled"}
+        and (e.get("label") or {}).get("name") == "ready-for-dev"
+        and (e.get("actor") or {}).get("login") != login
+        and (e.get("actor") or {}).get("login") != "github-actions[bot]"
+    ]
+
+
+def fingerprint(issue, comments, login, transitions=(), policy=None):
+    return hashlib.sha256(
+        json.dumps(
+            [
+                VERSION,
+                issue["title"],
+                author_body(issue.get("body")),
+                list(transitions),
+                policy,
+                [
+                    (
+                        c["id"],
+                        c.get("updated_at"),
+                        c.get("body"),
+                        (c.get("user") or {}).get("login"),
+                    )
+                    for c in comments
+                    if not owned_comment(c, login) and not readiness_comment(c)
+                ],
+            ],
+            sort_keys=True,
+        ).encode()
+    ).hexdigest()
+
+
+def parse_recommendation(value):
+    if isinstance(value, str):
+        value = json.loads(value)
+    required = {"decision", "priority", "scope", "non_goals", "criteria", "questions"}
+    if not isinstance(value, dict) or set(value) != required:
+        raise ValueError("Recommendation must contain exactly the documented fields")
+    if value["decision"] not in ("ready", "decision_needed") or value[
+        "priority"
+    ] not in ("high", "medium", "low"):
+        raise ValueError("Invalid decision or priority")
+    for key in ("scope", "non_goals"):
+        if not isinstance(value[key], str) or not value[key].strip():
+            raise ValueError(f"Missing {key}")
+    for key in ("criteria", "questions"):
+        if not isinstance(value[key], list) or any(
+            not isinstance(s, str) or not s.strip() for s in value[key]
+        ):
+            raise ValueError(f"Invalid {key}")
+    if value["decision"] == "ready":
+        if not value["criteria"] or value["questions"]:
+            raise ValueError("Ready requires criteria and no open questions")
+    elif not value["questions"] or value["criteria"]:
+        raise ValueError(
+            "Decision needed requires questions and no provisional criteria"
+        )
+    if "<!--" in json.dumps(value) or len(json.dumps(value)) > 20000:
+        raise ValueError("Embedded markers or oversized recommendation")
+    return value
+
+
+def render(body, recommendation, digest):
+    r = parse_recommendation(recommendation)
+    before, old, after = split_body(body)
+    marker = f"<!-- triage-source:{digest} -->"
+    if not re.fullmatch(r"[a-f0-9]{64}", digest):
+        raise ValueError("Invalid input digest")
+    if r["decision"] == "decision_needed":
+        return before + after, f"{DISCLOSURE}\n\n### Decision needed\n" + "\n".join(
+            f"- {q}" for q in r["questions"]
+        ) + f"\n\n{marker}"
+    section = (
+        f"{START}\n## OpenHands AI triage\n{DISCLOSURE}\n\n"
+        f"### Scope\n{r['scope']}\n\n### Non-goals\n{r['non_goals']}\n\n"
+        "### Acceptance Criteria\n"
+        + "\n".join(f"- [ ] {c}" for c in r["criteria"])
+        + f"\n\n{marker}\n{END}"
+    )
+    return before + ("" if old else "\n\n") + section + after, None
+
+
+def writer_policy_allows(repo, login):
+    """Only deployment-audited writer-only policies are supported, never repo code."""
+    policy = repo.config.get("triage_readiness_policies", {}).get(repo.repository, {})
+    if policy.get("mode") != "authorized-writers" or not policy.get("files"):
+        return False
+    for path, sha in policy["files"].items():
+        if not re.fullmatch(r"[a-f0-9]{40}", sha):
+            return False
+        current = repo.gh("GET", f"/contents/{quote(path, safe='/')}")
+        if current.get("sha") != sha:
+            return False
+    permission = repo.gh("GET", f"/collaborators/{quote(login, safe='')}/permission")
+    return permission.get("permission") in {"write", "maintain", "admin"}
+
+
+def publish(repo, number, expected, recommendation):
+    r = parse_recommendation(recommendation)
+    login = repo.api("GET", "/user")["login"]
+    path = f"/issues/{number}"
+    initial = repo.gh("GET", path)
+    comments = repo.gh_pages(path + "/comments")
+    if initial.get("state") != "open" or "pull_request" in initial:
+        raise ValueError("Issue no longer eligible")
+    if (
+        fingerprint(
+            initial,
+            comments,
+            login,
+            readiness_transitions(repo, number, login),
+            repo.config.get("triage_readiness_policies"),
+        )
+        != expected
+    ):
+        raise ValueError("Human inputs changed; recompute recommendation")
+    body, comment = render(initial.get("body"), r, expected)
+    receipt = f"<!-- triage-complete:{expected} -->"
+    body = body.replace(receipt, "")
+    labels = {label["name"] for label in initial.get("labels", [])}
+    writes = 0
+
+    def guarded(method, target, data=None):
+        nonlocal initial, writes
+        current = repo.gh("GET", path)
+        fresh_comments = repo.gh_pages(path + "/comments")
+        if (
+            current.get("state") != "open"
+            or {l["name"] for l in current.get("labels", [])} != labels
+            or current.get("body") != initial.get("body")
+            or fingerprint(
+                current,
+                fresh_comments,
+                login,
+                readiness_transitions(repo, number, login),
+                repo.config.get("triage_readiness_policies"),
+            )
+            != expected
+        ):
+            raise ValueError("Inputs changed before write; recompute recommendation")
+        result = repo.gh(method, target, data)
+        writes += 1
+        if target == path and method == "PATCH":
+            initial = {**initial, "body": data["body"]}
+        if target == path + "/labels" and method == "POST":
+            labels.update(data["labels"])
+        elif target.startswith(path + "/labels/") and method == "DELETE":
+            labels.discard(unquote(target.rsplit("/", 1)[1]))
+        return result
+
+    # Revoke readiness before changing its supporting criteria.
+    labels = {label["name"] for label in initial.get("labels", [])}
+    allowed = r["decision"] == "ready" and writer_policy_allows(repo, login)
+    if "ready-for-dev" in labels and r["decision"] == "decision_needed":
+        guarded("DELETE", path + "/labels/ready-for-dev")
+    completed_body = (
+        body.replace(END, receipt + "\n" + END) if r["decision"] == "ready" else body
+    )
+    if body != (initial.get("body") or "") and completed_body != (
+        initial.get("body") or ""
+    ):
+        guarded("PATCH", path, {"body": body})
+    own = [c for c in comments if owned_comment(c, login)]
+    if comment and not any(
+        c.get("body") in (comment, comment + "\n" + receipt) for c in own
+    ):
+        if own:
+            guarded("PATCH", f"/issues/comments/{own[0]['id']}", {"body": comment})
+            own = own[1:]
+        else:
+            guarded("POST", path + "/comments", {"body": comment})
+    else:
+        own = [
+            c
+            for c in own
+            if c.get("body")
+            not in (comment, (comment + "\n" + receipt) if comment else None)
+        ]
+    for c in own:
+        guarded("DELETE", f"/issues/comments/{c['id']}")
+    priority = "priority:" + r["priority"]
+    for other in sorted(
+        labels
+        & {"priority:normal", "priority:high", "priority:medium", "priority:low"}
+        - {priority}
+    ):
+        guarded("DELETE", path + "/labels/" + quote(other, safe=""))
+    if priority not in labels:
+        guarded("POST", path + "/labels", {"labels": [priority]})
+    if allowed and "ready-for-dev" not in labels and writer_policy_allows(repo, login):
+        guarded("POST", path + "/labels", {"labels": ["ready-for-dev"]})
+    if r["decision"] == "ready":
+        if completed_body != (initial.get("body") or ""):
+            guarded("PATCH", path, {"body": completed_body})
+    elif comment:
+        current_comments = repo.gh_pages(path + "/comments")
+        target = next(
+            c
+            for c in current_comments
+            if owned_comment(c, login) and expected in c.get("body", "")
+        )
+        completed_comment = comment + "\n" + receipt
+        if target.get("body") != completed_comment:
+            guarded(
+                "PATCH", f"/issues/comments/{target['id']}", {"body": completed_comment}
+            )
+    return {"writes": writes, "readiness_policy_allowed": allowed}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config", required=True)
+    parser.add_argument("--repository", required=True)
+    parser.add_argument("--number", required=True, type=int)
+    parser.add_argument("--expected", required=True)
+    parser.add_argument("--recommendation", required=True)
+    parser.add_argument("--github-token-secret", required=True)
+    args = parser.parse_args()
+    config = json.loads(Path(args.config).read_text())
+    if args.repository not in (config.get("repos") or [config.get("repository")]):
+        raise ValueError("Repository not allowed by deployment")
+    repo = GitHubRepository(
+        args.config,
+        repository=args.repository,
+        github_token_secret=args.github_token_secret,
+    )
+    print(
+        json.dumps(
+            publish(
+                repo, args.number, args.expected, Path(args.recommendation).read_text()
+            )
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()