@openhands/extensions 0.29.0 → 0.31.0

package/plugins/vulnerability-remediation/skills/github/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/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.29.0"
+version = "0.31.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 dependencies = [

package/python/openhands_extensions/_version.py

@@ -18,7 +18,7 @@ from importlib.metadata import PackageNotFoundError, version
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
 #: release-please only rewrites a semver found on the annotated line itself, so
 #: the annotation must stay on the assignment; on its own line it is a no-op.
-_FALLBACK_VERSION = "0.29.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.31.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")

package/skills/canvas-extension-api/references/backend-safety.md

@@ -10,14 +10,14 @@ For a CLI, binary, compiler, database, or Sidecar, read [sidecar-pattern.md](sid
 
 ## Package-owned managed backends
 
-The managed-backend contract requires the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Until a release containing both lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` through `GET /server_info`; never infer support from an endpoint failure, Canvas internals, or a guessed port. Use the host helper only at the minimum host version documented in [v1-contract.md](v1-contract.md).
+The managed-backend contract requires the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Remote artifact sources additionally require [software-agent-sdk PR #5503](https://github.com/OpenHands/software-agent-sdk/pull/5503). Until releases containing the needed changes land, those revisions or PR heads are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` through `GET /server_info`; never infer support from an endpoint failure, Canvas internals, or a guessed port. Use the host helper only at the minimum host version documented in [v1-contract.md](v1-contract.md).
 
 A managed backend is declarative, not an install hook. Installation, enablement, activation, and ordinary page mounts never prepare or start it. Show the resolved revision and backend declaration, then require explicit user consent before calling prepare and start with that exact revision. Updating or replacing the package invalidates approval. Never put a credential in the manifest, argv, browser bundle, URL, or log.
 
 For embedded backend views, require the configured ingress to be a separate browser origin from Canvas. That origin is the isolation boundary. Apply the server-returned sandbox exactly, including `allow-same-origin`; removing it breaks Origin validation, partitioned-cookie delivery, and Worker creation in Chromium. Do not replace origin isolation with an opaque sandbox origin.
 
-The Agent Server selects the current platform artifact, verifies its lowercase SHA-256 checksum, extracts it safely to immutable content-addressed storage, and runs only the declared structured argv without a shell. The executable must remain inside `{artifact_dir}`. Supported placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`. Inherited environment names are restricted to the server's non-credential allowlist; ambient Agent Server credentials do not flow to the child.
+The Agent Server selects the current platform artifact, verifies its lowercase SHA-256 checksum, extracts it safely to immutable content-addressed storage, and runs only the declared structured argv without a shell. An artifact may use either a contained package-relative `path` or a credential-free HTTPS `url`, never both. Remote downloads enforce redirect, size, scheme, checksum, and archive-entry constraints; `strip_components` is bounded from 0 through 16. The executable must remain inside `{artifact_dir}`. Supported placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`. The child receives an App-owned `HOME` below `{data_dir}`. Inherited environment names are restricted to the server's non-credential allowlist; ambient Agent Server credentials do not flow to the child.
 
-Only local Linux amd64 and arm64 artifacts are supported initially. Treat `unsupported` as an explicit UI state. The owned process is constrained by its launch contract and process group but is not OS-isolated; run untrusted backend code only inside a suitably isolated Agent Server runtime.
+Only local Agent Server hosts on Linux amd64 and arm64 are supported initially. Treat `unsupported` as an explicit UI state. The owned process is constrained by its launch contract and process group but is not OS-isolated; run untrusted backend code only inside a suitably isolated Agent Server runtime.
 
 Backend data belongs to the service independently of the installed bundle. Disable and uninstall stop the owned process and revoke browser sessions but preserve mutable data. Data deletion is a separate explicit action. Installed Apps and their backends belong to one Agent Server; do not assume a service or its data is shared across isolated conversation runtimes.

package/skills/canvas-extension-api/references/v1-contract.md

@@ -48,8 +48,10 @@ interface CanvasExtensionManifest {
 interface CanvasExtensionBackend {
   schema_version: 1;
   artifacts: Partial<Record<"linux-amd64" | "linux-arm64", {
-    path: string;
+    path?: string;
+    url?: string;
     sha256: string;
+    strip_components?: number;
   }>>;
   argv: string[];
   health?: {
@@ -71,7 +73,7 @@ interface CanvasExtensionPageContribution {
 
 Required manifest fields are `schema_version`, `name`, `version`, and `entrypoint`. A useful page package also supplies `display_name`, `description`, and at least one `contributes.pages` entry. `backend` is optional: omitting it preserves a browser-only App or a manual/deployment-owned Sidecar.
 
-The managed-backend contract requires the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Until a release containing both lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` in `GET /server_info`; the same response must provide `app_backend_ingress_url`.
+The managed-backend contract requires the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Remote artifact sources additionally require [software-agent-sdk PR #5503](https://github.com/OpenHands/software-agent-sdk/pull/5503). Until releases containing the needed changes land, those revisions or PR heads are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` in `GET /server_info`; the same response must provide `app_backend_ingress_url`.
 
 The minimum host is the Agent Canvas revision that adds the optional `host.appBackendView` helper specified under Host API 1 below — the frontend change in OpenHands/OpenHands#17641, which this document's PR lists as a merge prerequisite. No upstream release pins that helper yet, so there is no release number to name; until there is, the minimum host is exactly "the build whose `host.appBackendView` is present", and feature-detecting that helper is the only supported test. Absence is an actionable unsupported state, not a reason to guess an ingress port or read Canvas internals.
 
@@ -80,8 +82,9 @@ All references in this bundle to "the minimum host version documented in `v1-con
 For a managed backend:
 
 - Key `artifacts` only by `linux-amd64` or `linux-arm64`; one matching entry is sufficient.
-- Keep each artifact `path` package-relative, contained, and ending in `.tar.gz`.
-- Set `sha256` to exactly 64 lowercase hexadecimal characters.
+- Declare exactly one artifact source: either a package-relative, contained `.tar.gz` `path`, or a credential-free HTTPS `.tar.gz` `url`.
+- For remote archives, optionally set `strip_components` to an integer from 0 through 16; it defaults to 0 and is invalid for local paths.
+- Set `sha256` to exactly 64 lowercase hexadecimal characters. Remote downloads are accepted only when this digest matches.
 - Use a non-empty structured `argv`; `argv[0]` must resolve inside `{artifact_dir}`.
 - Use only `{artifact_dir}`, `{data_dir}`, and `{port}` placeholders.
 - Keep `health.path` root-relative. Defaults are `/health`, 30 seconds, and 0.1 seconds.

package/skills/canvas-extension-api/scripts/validate-extension.mjs

@@ -62,7 +62,23 @@ if (manifest.backend !== undefined && manifest.backend !== null) {
         const label = `backend.artifacts[${platform}]`;
         if (!new Set(["linux-amd64", "linux-arm64"]).has(platform)) fail(`${label} uses an unsupported platform.`);
         if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) { fail(`${label} must be an object.`); continue; }
-        if (typeof artifact.path !== "string" || !artifact.path || artifact.path.startsWith("/") || artifact.path.split(/[\\/]/).includes("..") || !artifact.path.endsWith(".tar.gz")) fail(`${label}.path must be a contained relative .tar.gz path.`);
+        const hasPath = typeof artifact.path === "string" && artifact.path.length > 0;
+        const hasUrl = typeof artifact.url === "string" && artifact.url.length > 0;
+        if (hasPath === hasUrl) {
+          fail(`${label} must declare exactly one of path or url.`);
+        } else if (hasPath && (artifact.path.startsWith("/") || artifact.path.split(/[\\/]/).includes("..") || !artifact.path.endsWith(".tar.gz"))) {
+          fail(`${label}.path must be a contained relative .tar.gz path.`);
+        } else if (hasUrl) {
+          let url;
+          try { url = new URL(artifact.url); } catch { url = null; }
+          if (!url || url.protocol !== "https:" || url.username || url.password || url.hash || !url.pathname.endsWith(".tar.gz")) {
+            fail(`${label}.url must be a credential-free HTTPS .tar.gz URL.`);
+          }
+          if (artifact.strip_components !== undefined && (!Number.isInteger(artifact.strip_components) || artifact.strip_components < 0 || artifact.strip_components > 16)) {
+            fail(`${label}.strip_components must be an integer from 0 through 16.`);
+          }
+        }
+        if (hasPath && artifact.strip_components !== undefined && artifact.strip_components !== 0) fail(`${label}.strip_components is supported only for remote artifacts.`);
         if (typeof artifact.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(artifact.sha256)) fail(`${label}.sha256 must be a lowercase SHA-256 checksum.`);
       }
     }

package/skills/canvas-extension-api/scripts/validate-extension.test.mjs

@@ -93,6 +93,55 @@ test("accepts a package-owned backend declaration", async () => {
   }
 });
 
+test("accepts checksum-pinned remote backend artifacts", async () => {
+  const root = await createApp("extension.js", {
+    backend: {
+      ...backend,
+      artifacts: {
+        "linux-amd64": {
+          url: "https://example.com/service.tar.gz",
+          sha256: "a".repeat(64),
+          strip_components: 1,
+        },
+      },
+    },
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.equal(result.status, 0, result.stderr);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects insecure or ambiguous remote backend artifacts", async () => {
+  const artifacts = [
+    { url: "http://example.com/service.tar.gz", sha256: "a".repeat(64) },
+    {
+      path: "backend/service.tar.gz",
+      url: "https://example.com/service.tar.gz",
+      sha256: "a".repeat(64),
+    },
+    {
+      url: "https://example.com/service.tar.gz",
+      sha256: "a".repeat(64),
+      strip_components: 17,
+    },
+  ];
+  for (const artifact of artifacts) {
+    const root = await createApp("extension.js", {
+      backend: { ...backend, artifacts: { "linux-amd64": artifact } },
+    });
+    try {
+      const result = validate(root, "--dist");
+      assert.notEqual(result.status, 0);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+});
+
+
 test("rejects a backend artifact path outside the package", async () => {
   const root = await createApp("extension.js", {
     backend: {