@openhands/extensions 0.29.0 → 0.30.0

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

@@ -1,16 +1,75 @@
 # GitHub issue triage
 
-Prioritize open issues and establish acceptance criteria before marking them ready for development.
-
-Schedule this automation independently and select its agent profile. The profile
-chooses the model, tools, and GitHub credential; the PAT needs Issues write access
-only. Explicit issue dependencies must be completed before development starts.
-The agent checks repository guidance and adjacent code, preserves the author's
-issue description, and maintains accepted criteria in one clearly marked section
-at the end of the issue body. This lets repository readiness checks evaluate the
-same source that developers and reviewers use. When a material design decision
-remains unclear after repository research, the agent leaves the body unchanged,
-asks focused follow-up questions in a marked comment, and withholds the readiness
-label.
-
-See [SKILL.md](SKILL.md) for configuration and the catalog bundle for its files.
+Prioritize issues and define observable acceptance criteria using
+[SKILL.md](SKILL.md). The scanner honors dependencies and sends changed issues
+to conversations using the selected profile.
+
+## Publication modes
+
+Legacy agent publication is the default. The optional `triage_publication.py`
+helper validates JSON recommendations and checks human inputs before every write.
+It preserves text outside managed markers and edits/deletes only triage-marked
+comments from the authenticated account. It skips identical writes and stops on
+ambiguous markers. GitHub Actions readiness comments provide context, but neither
+change the human-input fingerprint nor override policy.
+
+This opt-in is **not credential isolation**: the agent can still write directly.
+Enforced isolation needs a separate trusted publisher, read-only agent credentials,
+and runtime support for passing results to the publisher.
+
+## Operator setup
+
+Bundle `worker.py`, `triage_publication.py`, `github_client.py`, and
+`agent_conversation.py`. Entrypoint: `python3 worker.py`.
+
+1. Place the publisher, `github_client.py`, and protected config in the delegated
+   workspace. Set `triage_publisher_path` and `triage_publisher_config_path` to
+   absolute file paths. Set both or neither; neither keeps legacy mode.
+2. Set `triage_publisher_workspace: "shared-host"` only after checking manually
+   that the agent can access those paths. The flag asserts access; it does not
+   prove sandbox visibility. The scanner checks files and the repository allowlist before dispatch, then
+   loads readiness policies from that same protected publisher config for its
+   input fingerprints. Do not duplicate policies in the scanner config. Remote/container paths are unsupported. If the
+   agent cannot invoke the helper, stop; do not fall back to direct writes.
+3. Cloud conversations are unsupported: bundling does not provision their files,
+   and the dispatcher cannot retrieve structured results from them.
+
+Publisher config uses existing `repos` and optional `triage_readiness_policies`:
+
+```json
+{
+  "repos": ["owner/repo"],
+  "triage_readiness_policies": {
+    "owner/repo": {
+      "mode": "authorized-writers",
+      "files": {".github/workflows/issue-readiness-check.yml": "<audited GitHub blob SHA>"}
+    }
+  }
+}
+```
+
+Audit current policy and pin every relevant file to its actual 40-character
+GitHub blob SHA (the file-content identifier). Only writer-only policies are
+supported: the helper checks current SHAs and live `write`/`maintain`/`admin`
+permission. Never select this mode for a policy that checks issue content.
+Unknown, changed, or unsupported policies block new readiness grants, preserve
+existing labels, and still allow criteria publication. No repository checker runs.
+
+Precreate `ready-for-dev` and `priority:low/medium/high` labels. Use the same
+GitHub account for scanner and publisher. Its fine-grained PAT needs selected-repo
+Issues read/write, Contents read, and permission lookup access. Never put token
+values in prompts or automation definitions.
+
+## Races and retries
+
+- Checks and writes are not atomic: people or other automations can change inputs
+  between GET and PATCH. There is no shared lock or all-or-nothing update across
+  issue bodies, comments, and labels. Changed inputs stop publication; the next
+  scan recomputes the recommendation.
+- The input fingerprint includes human readiness-label changes from the issue
+  timeline, but excludes the publisher's and GitHub Actions' label changes.
+- A completion receipt is saved only after publication finishes. Partial writes
+  change the guarded-mode delivery key, allowing retries. If an unchanged failure
+  is marked finished by the dispatcher, manually retry the same command.
+- Configured policy changes affect the fingerprint. Upstream policy changes alone
+  do not automatically retriage unchanged issues with managed markers.

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

@@ -9,49 +9,29 @@ triggers:
 
 Prioritize open issues and establish acceptance criteria before marking them ready for development.
 
-Create this automation separately from implementation and review. Use a
-fine-grained GitHub PAT limited to the selected repositories with Issues: read and
-write. Never put the token value in the automation definition or prompt.
-
-Package `worker.py` with the shared `github_client.py` and
-`agent_conversation.py` helpers. Supply `config.json` with `repos` and the saved
-GitHub secret name; the entrypoint is `python3 worker.py`. Include that secret in
-the selected profile so the delegated agent can use GitHub. Naming it in the
-automation does not grant it to the agent.
-
-The scanner is an ordinary Automation host command. It submits selected issues
-through the shared KV-backed conversation dispatcher, which creates or resumes
-one stable conversation per issue through the Software Agent SDK. Only that
-agent workspace is local or Docker. Automation owns scheduling, cancellation,
-and cleanup.
-
-Honor `Depends on: #12, #13` lines. A dependency must be closed as completed.
-Do not treat an existing `ready-for-dev` label as proof of readiness: inspect the
-issue discussion, repository instructions, and the closest relevant or adjacent
-implementation. Resolve reasonable ambiguity with a bounded scope and explicit
-non-goals. If a material product or design decision still cannot be inferred
-safely, ask only the focused follow-up questions needed to resolve it and withhold
-`ready-for-dev`; do not invent acceptance criteria around an arbitrary choice.
-
-Acceptance criteria must be observable and sufficient for a reviewer to decide
-that the requested behavior is complete. Check the main behavior and every
-applicable boundary: failures and edge cases, compatibility or migration,
-lifecycle and cleanup, permissions and secrets, user-facing documentation, and
-realistic automated or live validation. Avoid subjective criteria and avoid
-prescribing an implementation unless repository policy requires one mechanism.
-
-For an issue that is ready, preserve the author's description and maintain one
-clearly marked OpenHands AI section at the end of the issue body. Put the triage
-scope, any missing repository-required readiness sections, and testable
-acceptance criteria there. Replace only that marked section on later runs and do
-not also post a triage comment. Add `ready-for-dev` only after the final criteria
-pass this standard.
-
-If the design is still unclear, remove any stale managed body section, leave the
-human-owned body unchanged, and post the minimum focused questions in one marked
-comment below the human discussion. Withhold `ready-for-dev`. Preserve unrelated
-labels and never edit or delete human-authored text.
-Do not implement code or accept pull requests.
-
-Each scheduled run submits every changed eligible issue. A failure on one issue is
-reported and does not prevent the remaining issues from being submitted.
+## Setup
+
+Keep triage separate from implementation and review. Follow [README.md](README.md)
+for packaging, credentials, publisher setup, and limits. Never put token values
+in the automation definition or prompt. Legacy agent publication is the default.
+
+## Triage instructions
+
+- Honor explicit dependencies. Read applicable root/local `AGENTS.md`,
+  `.agents/skills/custom-codereview-guide.md` if present, human discussion, and
+  adjacent code. Identify affected versions and the owning component (Canvas,
+  SDK, automation, or extensions).
+- Follow current human decisions over stale generated criteria. Do not repeat
+  answered questions. Keep scope bounded, name non-goals, and ask only unresolved
+  material product/design questions.
+- Define observable completion, not entry requirements. Do not require tests for
+  unwritten code, PR artifacts, or images/videos for every issue. Default priority
+  to low; medium/high need recorded real user pain, not speculation or synthetic
+  tests.
+- Return structured recommendations. If a publisher is configured, use it; never
+  bypass it or its changed-input checks. Legacy direct mode follows the same rules
+  without enforcement.
+- Preserve human text and unrelated labels. Never run repository checkers with
+  credentials. Use current repository policy audited by the deployment owner, not
+  historical checker comments, to decide readiness.
+- Do not implement code or accept pull requests.

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)