@openhands/extensions 0.29.0 → 0.31.0

package/skills/github-pr-reviewer/README.md

@@ -66,9 +66,30 @@ This skill is activated by:
   assertions, generated mockups, and reconstructed captures cannot substitute.
   Missing evidence yields a COMMENT review that names the gap, so no approval
   and no maintainer handoff
+- Ends each published review, fallback comment, and error comment with the LLM
+  profile and model of the conversation that wrote it:
+  `LLM profile: <profile> · Model: <model>`. The deterministic script appends
+  the footer, never the agent. With default agent publication, it updates only
+  a review whose hidden run marker names that conversation, so automations that
+  share a bot account cannot relabel each other's reviews. Opt-in worker
+  publication formats the claimed conversation's footer before its durable
+  publication intent is saved. The catalog worker records each review's
+  server-derived metadata or an explicit `unknown` fallback in its
+  automation-scoped KV store before updating the review; only that record,
+  never an agent-written footer, establishes
+  attribution. It keeps those values if the agent profile changes later; a
+  failed lookup is logged and never holds up the verdict or maintainer handoff.
+  Failed lookups and uncertain KV writes are reconciled against the saved
+  metadata; failure on one review does not prevent the worker from correcting
+  other owned reviews.
+  The first tuple, including an `unknown` fallback, is retained for that review.
+  If KV cannot establish or validate a tuple, the edit is skipped and logged.
+  The manual upload flow retries a failed lookup or edit on its next poll
 - Posts acknowledgement comments with AI disclosure
 - Configurable review tone and polling schedule
-- Optional human handoff after an exact-head approval. The scanner ranks the
+- Optional human handoff after an exact-head approval or a maintainer-decision
+  scope stop, only when a same-repository closing issue is successfully fetched
+  and labeled `priority:medium` or `priority:high`. The scanner ranks the
   configured maintainers by recent commits to changed paths, then by their open
   GitHub review-request count, and requests one without merging the PR. Use at
   least two repository collaborators so a maintainer can author a PR without
@@ -76,12 +97,32 @@ This skill is activated by:
 
 ## Prerequisites
 
+The catalog worker starts each review conversation from the automation's
+agent profile, which the server resolves. Its footer reads the model back from
+that conversation, so a reused conversation reports the LLM it actually runs,
+and takes the LLM profile name from the agent profile while it is still at its
+launch revision (`unknown` once the profile has been edited since).
+For local ACP profiles, the model is the server's reported session model;
+without that metadata it is `unknown`, since the configured override and
+`acp-managed` placeholder do not establish which model produced the review.
+
+The manual upload flow reports `default` and the concrete model from the
+server settings it already uses to start the conversation. That label describes
+the settings source; it does not infer a named profile from the active-profile
+pointer.
+
 Set `GITHUB_PERSONAL_ACCESS_TOKEN` in OpenHands Settings -> Secrets. The token
 must be able to read the repositories and their contents, read issue events,
 write issue comments, and **write pull request reviews** — the review is
 published and the optional human reviewer is requested through the pull request
 API, so read-only pull request access is not enough.
 
+On OpenHands Cloud and Enterprise, the Agent Canvas catalog template needs no
+saved secret when GitHub is connected under Settings -> Integrations: a secret
+saved under the configured name is used if present, otherwise the connected
+account's token, and the review is published by that account. Set the
+requested reviewer to that account's login.
+
 ## Quick Start
 
 Ask OpenHands for either trigger mode:
@@ -96,3 +137,70 @@ can instead use a configured label and re-apply it for another review.
 ## See Also
 
 - [SKILL.md](SKILL.md) - Full setup workflow reference
+
+## Opt-in worker publication
+
+Legacy agent publication is the default. With `structured_publication: true`,
+`worker.py` publishes the agent's JSON result, validating `head_sha`,
+`code_assessment` (`clean`, `material_findings`, `inconclusive`),
+`merge_readiness` (`ready`, `blocked`, `unknown`), summary, findings, and evidence.
+It chooses the event and footer. Only clean, ready results approve;
+clean self-reviews use COMMENT. Missing merge requirements are not code defects.
+**This mode puts findings in the body, not inline threads.**
+
+The publisher appends the claimed conversation's profile/model metadata before
+saving its publication intent. Receipt recovery uses that saved body, so a later
+profile edit cannot relabel the review. An unavailable metadata read is logged
+and leaves publication and handoff available.
+
+### Operator prerequisites
+
+Keep disabled until you verify these prerequisites; setup is not automatic.
+
+- Bundle `publication.py`. Run periodic scans alongside event intake. Both recover
+  finished conversations before selecting new work.
+- Set `REVIEW_COORDINATION_AUTOMATION_ID` to the same namespace for both automations,
+  plus `REVIEW_COORDINATION_API_KEY` (a user-authorized automation API key) and
+  `AUTOMATION_API_URL`. The API must support `automation_id` user auth, metadata
+  versions, create-if-absent, and writes conditional on the stored version. The
+  run's automation-scoped KV JWT (key-value storage token) is insufficient.
+  Unsupported APIs stop publication.
+- Set `review_read_token_secret` and `review_profile_read_only: true` only after
+  independently verifying profile/sandbox isolation. This flag **does not enforce
+  isolation**. Agents must have read-only GitHub access, no publisher/coordination
+  credentials, and no write-capable MCP tools. The separate read token needs
+  pull-request, repository-content, and linked-issue read access; the worker
+  also needs issue read access to check handoff priority. Never add the coordination key to
+  the agent profile.
+- Verify Agent Server exposes execution status and
+  `/api/conversations/{id}/agent_final_response` returning `response`. Only
+  `finished` results are used; no workspace-file transport is supported.
+- Set `scan_window: true` for the VM's rotating discovery window of ten unrequested
+  PRs. Explicit candidates bypass this window. Automatic maintainer handoff for
+  both approvals and scope stops requires a successfully fetched same-repository
+  closing issue labeled `priority:medium` or `priority:high`. Missing links,
+  missing priority labels, low/normal priorities, unresolved references, and PR
+  references do not qualify. One qualifying issue permits handoff even when
+  other references are low-priority or missing. Non-404 lookup errors propagate
+  without requesting a review. Existing manual review requests are unchanged.
+
+### Recovery and limits
+
+Time-limited locks (leases) coordinate work for each repository/PR/reviewer.
+The head, latest request and label events, and latest non-bot clarification
+identify a work version (generation) across triggers.
+
+Intent is recorded before POST. Lost responses/receipts trigger a search by
+exact marker, account, and head. **An empty search never
+permits retrying an uncertain POST.** Completed/rejected generations stay recorded.
+Missing/failed starts are held for inspection, including records left in
+`starting` after a crash. Inspect the recorded conversation ID and server status
+before repairing the record; do not blindly restart a possibly running agent.
+Invalid/stale results wait for new work. Handoff intent is retained: crashes during handoff require operator
+reconciliation. Inspect shared `review-work-*` records before manual repair.
+Never delete uncertain POST intents just because a review is not yet visible.
+
+Publication is **not guaranteed exactly once**. GitHub cannot reject a review POST
+based on an expired lease or require the head to remain unchanged. The worker pins
+`commit_id` and rechecks the head, but a push can still race the POST. JSON validation
+cannot prove that written evidence claims are true.

package/skills/github-pr-reviewer/SKILL.md

@@ -186,8 +186,12 @@ move repositories, close, or receive a maintainer decision, and ends with the
 `🛑 MAINTAINER DECISION REQUIRED` verdict. That outcome is **neither an approval
 nor a change request**: it does not approve or merge the PR. The completion
 handler recognizes the verdict and requests one configured maintainer through the
-same handoff used after an approval. An in-scope change continues the existing
-review unchanged.
+same handoff used after an approval. Both paths require a successfully fetched
+same-repository closing issue labeled `priority:medium` or `priority:high`; a
+missing link or priority label, low/normal priority, unresolved reference, or PR
+reference does not authorize handoff. One qualifying issue is sufficient even
+with other low-priority or missing references. Existing manual review requests
+are unchanged. An in-scope change continues the existing review unchanged.
 
 Before approving a change to user-visible UI behavior, the prompt requires live
 evidence from a real running application when the repository's guidance demands
@@ -201,6 +205,23 @@ deterministic maintainer handoff does not fire. Non-UI changes keep the existing
 requirement of the real command and its observed output, with tests insufficient
 as sole proof.
 
+Every review ends with the LLM profile and model of the conversation that wrote
+it, after the verdict: `LLM profile: <profile> · Model: <model>`. The agent does
+not write this footer. The prompt gives it a hidden marker naming its own
+conversation, `<!-- openhands-review-run: <conversation-id> -->`, to copy under
+the disclosure, and the deterministic script appends the footer to the reviews
+that carry exactly that marker and no other. Login, head, and submission time
+cannot tell two automations that share a bot account apart, so a review without
+the marker, with another run's marker, or with several markers is never edited.
+The catalog worker reads the values back from the marked conversation: the
+model it runs, and the LLM profile its agent profile referenced at launch
+(`unknown` once that agent profile has been edited). It never substitutes the
+scanner's own settings, and a reused conversation keeps reporting the LLM it
+was launched with. A review is stamped once, so a later agent profile edit
+cannot rewrite its footer, and a provenance failure is logged without holding
+up the verdict or the maintainer handoff. The completion handler reads the
+verdict above the footer.
+
 The script prepares each review's workspace before the agent starts: the pull
 request's head commit is downloaded as a tarball and extracted to a directory of
 its own, which becomes the conversation's working directory. The agent is told
@@ -233,6 +254,13 @@ requesting the handoff.
 
 When several repositories are monitored, the token must cover all of them.
 
+On OpenHands Cloud and Enterprise, the Agent Canvas catalog template needs no
+saved secret when GitHub is connected under Settings -> Integrations: a secret
+saved under the configured name is used if present, otherwise the connected
+account's token, and the review is published by that account. The requested
+reviewer should be that account's login. The steps below apply to the local
+setup through this skill.
+
 Check with:
 ```bash
 curl -s https://api.github.com/user \
@@ -449,10 +477,13 @@ For each repository:
      `{WORKSPACE_BASE}/repositories/{owner}__{repo}/pr-{number}-{sha12}`. The
      archive is checked as it is unpacked: a single root, no absolute or `..`
      paths, and symlinks skipped rather than materialised.
+   - Records `default` and the concrete model from the server settings already
+     used to start the conversation, for the review footer.
    - Starts an OpenHands conversation **whose working directory is that
-     checkout**, with a review prompt carrying PR metadata, the exact head SHA,
-     label event details, and the requirement to re-fetch the current mutable
-     GitHub state before deciding a verdict.
+     checkout**, under an id chosen before it starts, with a review prompt
+     carrying PR metadata, the exact head SHA, label event details, the
+     requirement to re-fetch the current mutable GitHub state before deciding
+     a verdict, and that conversation's review marker.
    - Posts an acknowledgement comment with the label event, head SHA, and
      conversation link.
    - Records the review in state with `status: "active"` and the checkout path.
@@ -463,9 +494,12 @@ For each repository:
    - Suppresses stale results if the PR head SHA changed after the review was
      queued.
    - When the conversation reaches `idle`, `finished`, `error`, or `stuck`,
-     asks GitHub whether a review by the token's own user exists for that head
-     SHA. If it does, the review is complete. If it does not, the agent's final
-     response is posted as a comment so the work is not lost.
+     verifies a submitted review by the token's own user at that head SHA and
+     appends the recorded LLM profile and model to each review carrying this
+     conversation's marker before marking the review complete. Reviews without
+     that marker are confirmed but never edited. If no review exists, the
+     agent's final response is posted as a comment with provenance. Failed
+     verification or publication is retried on the next poll.
    - Abandons a conversation that has not reached a terminal status within two
      hours, so its checkout can be reclaimed.
 6. Removes the checkout of every finished review, but only after confirming the

package/skills/github-pr-reviewer/references/state-schema.md

@@ -81,6 +81,8 @@ Value: **ReviewRecord**
   "status": "active",
   "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
   "workspace_dir": "/workspace/repositories/owner__repo/pr-42-0123456789ab",
+  "llm_profile": "default",
+  "llm_model": "openai/review-model",
   "last_activity": 1717200000.0
 }
 ```
@@ -97,6 +99,12 @@ Value: **ReviewRecord**
 
 When a review becomes stale, `stale_reason` records the old and new head SHAs.
 When a review closes after posting, `completed_at` records the completion time.
+`llm_profile` labels the server's default settings as `default`, and `llm_model`
+records the concrete model already used to start the conversation. They become
+the footer of each review
+whose hidden `<!-- openhands-review-run: {conversation_id} -->` marker names
+this record's `conversation_id`; no other review is edited. A record written
+before these fields existed reports both as `unknown`.
 When a review expires, `expired_after` records how many seconds it had been
 waiting.
 

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)