@openhands/extensions 0.28.0 → 0.30.0

package/skills/github-pr-reviewer/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-pr-reviewer/scripts/main.py

@@ -24,6 +24,7 @@ import tarfile
 import time
 import urllib.error
 import urllib.request
+import uuid
 from collections.abc import Callable
 from pathlib import Path, PurePosixPath
 
@@ -427,7 +428,7 @@ def _latest_trigger_label_event(token: str, repo: str, pr_number: int) -> dict |
     return max(matching, key=lambda event: (event.get("created_at") or "", int(event.get("id") or 0)))
 
 
-def _post_github_comment(token: str, repo: str, pr_number: int, body: str) -> None:
+def _post_github_comment(token: str, repo: str, pr_number: int, body: str) -> bool:
     try:
         _github_request(
             token,
@@ -437,28 +438,28 @@ def _post_github_comment(token: str, repo: str, pr_number: int, body: str) -> No
         )
     except Exception as exc:
         print(f"  Warning: failed to post comment on PR #{pr_number}: {exc}")
+        return False
+    return True
 
 
-def _matching_review_exists(token: str, repo: str, pr_number: int, head_sha: str) -> bool:
-    """Has this token's user already published a review for this exact commit?
+def _published_reviews(token: str, repo: str, pr_number: int, head_sha: str) -> list[dict]:
+    """This token's user's submitted reviews of this exact commit.
 
     The agent is asked to report success, but a report is not evidence: reviews
     have been reported as posted when none existed. GitHub is the source of
-    truth for whether the review landed.
+    truth for whether the review landed. A listing failure is raised rather
+    than read as "no review", so the caller retries instead of posting the
+    result a second time.
     """
     if not head_sha or not _AUTH_LOGIN:
-        return False
-    try:
-        reviews = _github_paginate(token, f"/repos/{repo}/pulls/{pr_number}/reviews")
-    except Exception as exc:
-        print(f"  Warning: could not list reviews for PR #{pr_number}: {exc}")
-        return False
-    for review in reviews:
-        if (review.get("user") or {}).get("login", "").lower() != _AUTH_LOGIN.lower():
-            continue
-        if review.get("commit_id") == head_sha:
-            return True
-    return False
+        return []
+    return [
+        review
+        for review in _github_paginate(token, f"/repos/{repo}/pulls/{pr_number}/reviews")
+        if (review.get("user") or {}).get("login", "").lower() == _AUTH_LOGIN.lower()
+        and review.get("commit_id") == head_sha
+        and review.get("state") in {"COMMENTED", "APPROVED", "CHANGES_REQUESTED"}
+    ]
 
 
 # ── Repository checkout ───────────────────────────────────────────────────────
@@ -666,12 +667,17 @@ def create_conversation(
     api_key: str,
     initial_message: str,
     workspace_dir: Path,
+    agent: dict | None = None,
+    conversation_id: str | None = None,
 ) -> str:
     payload: dict = {
         "workspace": {"working_dir": str(workspace_dir)},
-        "agent": _get_agent_dict(agent_url, api_key),
+        "agent": agent or _get_agent_dict(agent_url, api_key),
         "initial_message": {"content": [{"text": initial_message}]},
     }
+    if conversation_id:
+        # Chosen by the caller so the prompt can name it before it exists.
+        payload["conversation_id"] = conversation_id
     secrets = _build_secrets_payload(agent_url, api_key)
     if secrets:
         payload["secrets"] = secrets
@@ -733,6 +739,52 @@ def _with_ai_disclosure(body: str) -> str:
     return f"{body}\n\n{disclosure}" if body else disclosure
 
 
+def _llm_provenance(profile: str, model: str) -> str:
+    return f"LLM profile: `{profile}` · Model: `{model}`"
+
+
+def _without_llm_provenance(body: str) -> str:
+    """The body with any provenance footer removed, for reading its verdict."""
+    return "\n".join(
+        line
+        for line in (body or "").splitlines()
+        if not re.fullmatch(r"LLM profile: .* · Model: .*", line.strip())
+    ).strip()
+
+
+def _with_llm_provenance(body: str, profile: str, model: str) -> str:
+    provenance = _llm_provenance(profile, model)
+    body = _without_llm_provenance(body)
+    return f"{body}\n\n{provenance}" if body else provenance
+
+
+# Two automations can share one bot account and review the same head, so the
+# login, commit, and submission time cannot say which run published a review.
+# The review agent copies this hidden marker, naming its own conversation, into
+# the review body; the deterministic script then annotates only the reviews
+# that carry exactly one marker, and only that conversation's own.
+_REVIEW_RUN_MARKER_RE = re.compile(r"<!-- openhands-review-run: ([0-9A-Za-z-]+) -->")
+
+
+def _review_run_marker(conversation_id: str) -> str:
+    return f"<!-- openhands-review-run: {conversation_id} -->"
+
+
+def _own_reviews(reviews: list[dict], conversation_id: str) -> list[dict]:
+    """The reviews whose only run marker names `conversation_id`.
+
+    A review with no marker, another run's marker, or several markers (an
+    agent quoting another review) is never attributed to this conversation.
+    """
+    if not conversation_id:
+        return []
+    return [
+        review
+        for review in reviews
+        if _REVIEW_RUN_MARKER_RE.findall(review.get("body") or "") == [str(conversation_id)]
+    ]
+
+
 def _load_repo_review_guide(workspace_dir: Path) -> str | None:
     """Read the repo-specific review guide from the checked-out repository.
 
@@ -764,6 +816,7 @@ def _build_review_prompt(
     workspace_instructions: str | None = None,
     github_token_secret: str = "GITHUB_PERSONAL_ACCESS_TOKEN",
     trigger_description: str | None = None,
+    conversation_id: str | None = None,
 ) -> str:
     number = pr.get("number", "?")
     title = pr.get("title", "(no title)")
@@ -792,6 +845,14 @@ def _build_review_prompt(
         "The workspace is already the repository root at the exact Head SHA above. "
         "Do not clone, fetch, check out, or delete the repository."
     )
+    run_marker = (
+        " On the next line put this hidden marker, copied exactly: "
+        f"`{_review_run_marker(conversation_id)}`. It identifies this conversation's "
+        "review, and the automation uses it to append the LLM profile and model after "
+        "GitHub accepts the review, so do not write that footer yourself."
+        if conversation_id
+        else ""
+    )
 
     return (
         "You are an AI code reviewer. Review the GitHub pull request below and publish "
@@ -827,6 +888,14 @@ def _build_review_prompt(
         "changed files), plus other relevant docs when present - e.g. `CONTRIBUTING.md`, "
         "`CLAUDE.md`, `.cursorrules`, and any review or coding-guideline docs. Apply that "
         "guidance to your review.\n"
+        "   Read `.agents/skills/custom-codereview-guide.md` when present; apply only checks "
+        "relevant to this change. For cross-repo behavior, inspect the owning implementation at "
+        "the supported dependency version (check pins/deployment), not upstream main. software-"
+        "agent-sdk owns execution/events; automation owns scheduling/run state; extensions owns "
+        "reusable skills/API usage. Find where behavior first fails. Distinguish an upstream fix "
+        "from a needed consumer change; state dependency order without filing tickets or editing "
+        "other repos. Respect accepted defaults/non-goals. Do not repeat answered questions or "
+        "block on unrelated pre-existing defects.\n"
         "4. SCOPE GATE - before inspecting changed files, reading the diff, or running any test, "
         "use the repository guidance above (its scope categories and ownership boundaries) to decide "
         "whether this change belongs in this repository and has the product/architecture direction "
@@ -877,8 +946,11 @@ def _build_review_prompt(
         "If GitHub forbids the configured bot from approving its own PR, retry the clean review with "
         "`event: COMMENT` and keep the approved verdict.\n"
         "10. Begin the review body with this disclosure: "
-        "`_This review was posted by an AI agent (OpenHands)._`\n"
-        "11. End the review body with a verdict on its own line: either `✅ APPROVED` "
+        f"`_This review was posted by an AI agent (OpenHands)._`{run_marker}\n"
+        "11. Separate code correctness from merge readiness. Never end with APPROVED while "
+        "material findings or required checks/evidence remain unresolved. Missing evidence "
+        "is not itself a code defect. "
+        "End the review body with a verdict on its own line: either `✅ APPROVED` "
         "or `🔄 CHANGES REQUESTED`.\n"
         "12. If there are no material issues, still publish a review saying so, with the "
         "disclosure and the verdict.\n"
@@ -933,8 +1005,24 @@ def _process_review_request(
         repo_review_guide = _load_repo_review_guide(workspace_dir)
         if repo_review_guide:
             print(f"  Injected repo review guide for PR #{number}")
-        prompt = _build_review_prompt(repo, pr, head_sha, label_event, repo_review_guide)
-        conv_id = create_conversation(agent_url, api_key, prompt, workspace_dir)
+        agent = _get_agent_dict(agent_url, api_key)
+        conv_id = str(uuid.uuid4())
+        prompt = _build_review_prompt(
+            repo,
+            pr,
+            head_sha,
+            label_event,
+            repo_review_guide,
+            conversation_id=conv_id,
+        )
+        conv_id = create_conversation(
+            agent_url,
+            api_key,
+            prompt,
+            workspace_dir,
+            agent=agent,
+            conversation_id=conv_id,
+        )
     except Exception as exc:
         # The claim is dropped so the next poll retries this label event. The
         # checkout goes with it rather than being left behind.
@@ -950,6 +1038,8 @@ def _process_review_request(
             "status": "active",
             "conversation_id": conv_id,
             "workspace_dir": str(workspace_dir),
+            "llm_profile": "default",
+            "llm_model": agent["llm"].get("model") or "unknown",
             "last_activity": time.time(),
         }
     )
@@ -1023,31 +1113,65 @@ def _check_conversation_completion(
     except Exception:
         final = ""
 
+    # A record written before provenance was tracked cannot name either value.
+    llm_profile = rec.get("llm_profile") or "unknown"
+    llm_model = rec.get("llm_model") or "unknown"
     if status in {"error", "stuck"}:
-        _post_github_comment(
+        posted = _post_github_comment(
             github_token,
             repo,
             pr_number,
-            _with_ai_disclosure(
-                f"⚠️ **OpenHands PR Reviewer encountered a problem** at commit `{reviewed_sha[:12]}` "
-                f"(status: `{status}`).\n\n{final}".strip()
+            _with_llm_provenance(
+                _with_ai_disclosure(
+                    f"⚠️ **OpenHands PR Reviewer encountered a problem** at commit `{reviewed_sha[:12]}` "
+                    f"(status: `{status}`).\n\n{final}".strip()
+                ),
+                llm_profile,
+                llm_model,
             ),
         )
-    elif _matching_review_exists(github_token, repo, pr_number, reviewed_sha):
-        print(f"  PR #{pr_number}: review confirmed on GitHub at {reviewed_sha[:12]}")
+        if not posted:
+            return
     else:
-        # The agent was asked to publish the review itself; it did not, so the
-        # work is not lost - post whatever it produced as a comment.
-        _post_github_comment(
-            github_token,
-            repo,
-            pr_number,
-            _with_ai_disclosure(
-                final
-                or f"✅ **OpenHands completed the review for commit `{reviewed_sha[:12]}`.** No review text was produced."
-            ),
-        )
-        print(f"  PR #{pr_number}: no review found on GitHub; posted the result as a comment")
+        try:
+            reviews = _published_reviews(github_token, repo, pr_number, reviewed_sha)
+            own = _own_reviews(reviews, conv_id)
+            for review in own:
+                body = _with_llm_provenance(review.get("body") or "", llm_profile, llm_model)
+                if body != review.get("body"):
+                    _github_request(
+                        github_token,
+                        "PUT",
+                        f"/repos/{repo}/pulls/{pr_number}/reviews/{review['id']}",
+                        body={"body": body},
+                    )
+        except Exception as exc:
+            print(f"  Warning: could not verify or complete review provenance for PR #{pr_number}: {exc}")
+            return
+        if reviews:
+            print(
+                f"  PR #{pr_number}: review confirmed on GitHub at {reviewed_sha[:12]}"
+                + ("" if own else "; none carries this conversation's marker, so none was annotated")
+            )
+        else:
+            if final.strip() == "GITHUB_REVIEW_POSTED":
+                final = ""
+            posted = _post_github_comment(
+                github_token,
+                repo,
+                pr_number,
+                _with_llm_provenance(
+                    _with_ai_disclosure(
+                        final
+                        or f"✅ **OpenHands completed the review for commit `{reviewed_sha[:12]}`.** No review text was produced."
+                    ),
+                    llm_profile,
+                    llm_model,
+                ),
+            )
+            if not posted:
+                return
+            print(f"  PR #{pr_number}: no review found on GitHub; posted the result as a comment")
 
     rec["status"] = "closed"
     rec["completed_at"] = time.time()