optio-opencode 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

optio_opencode/__init__.py

@@ -10,17 +10,22 @@ from optio_host import (
 )
 from optio_opencode.session import create_opencode_task, run_opencode_session
 from optio_opencode.types import (
+    ConversationMode,
     DeliverableCallback,
     HookCallback,
     OpencodeTaskConfig,
+    SeedProvider,
+    ToolVerbosity,
 )
 from optio_opencode.seed_manifest import (
+    OPENCODE_CRED_MANIFEST,
     OPENCODE_SEED_MANIFEST,
     OPENCODE_SEED_SUFFIX,
     delete_seed,
     list_seeds,
     purge_seed,
 )
+from optio_opencode.verify import verify_and_refresh_seed
 
 # asyncssh emits per-connection / per-channel INFO lines ("Opening SSH
 # connection...", "Received channel close", etc.) that flood the worker's
@@ -46,4 +51,9 @@ __all__ = [
     "delete_seed",
     "list_seeds",
     "purge_seed",
+    "OPENCODE_CRED_MANIFEST",
+    "SeedProvider",
+    "ConversationMode",
+    "ToolVerbosity",
+    "verify_and_refresh_seed",
 ]

optio_opencode/conversation.py

@@ -0,0 +1,357 @@
+"""OpencodeConversation — engine-side driver for one opencode session over
+the spawned server's native HTTP+SSE API.
+
+The session body launches the opencode server (``launch_opencode``),
+pre-creates a session, constructs this object with the same
+``(worker_port, password, session_id)`` it already produces, publishes it via
+``ctx.publish_result``, and runs ``run_reader()`` until teardown.
+
+Live events come from ``GET /global/event`` — the per-instance
+``/event?directory=…`` endpoint closes immediately after ``server.connected``
+on the shipped server (verified empirically against 1.14.45, Task 8 fixtures).
+Each ``/global/event`` frame wraps the event as
+``{"directory"?, "project"?, "payload": {"id", "type", "properties"}}``
+(``server.connected``/``server.heartbeat`` carry no ``directory``); the driver
+drops frames for other directories and fans the unwrapped payload out to
+``on_event`` subscribers as a dict, unmodified (``{"id", "type",
+"properties"}``). Synthetic events use the ``x-optio-`` type prefix.
+Permission requests are event-driven (``permission.asked``) with a
+list-endpoint sweep on every SSE (re)connect, so requests that fired during a
+stream gap are never lost.
+
+See docs/2026-06-11-opencode-conversation-mode-design.md.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+
+import aiohttp
+
+from optio_agents.conversation import (
+    ConversationClosed,
+    PermissionDecision,
+    PermissionRequest,
+)
+
+_LOG = logging.getLogger(__name__)
+
+# Reconnect backoff for the SSE reader (capped; the session body cancels the
+# reader at teardown, so there is no give-up path while the task is alive).
+_RECONNECT_DELAYS = (0.2, 0.5, 1.0, 2.0, 5.0)
+
+
+class OpencodeConversation:
+    """Implements optio_agents.conversation.Conversation for opencode."""
+
+    def __init__(
+        self, *, port: int, password: str, session_id: str, directory: str,
+    ) -> None:
+        self._base = f"http://127.0.0.1:{port}"
+        self._auth = aiohttp.BasicAuth("opencode", password)
+        self._session_id = session_id
+        self._directory = directory
+        # The server resolves instance directories (symlinks etc.) before
+        # stamping them onto /global/event frames; compare against realpath too.
+        self._directory_real = os.path.realpath(directory)
+        self._pending = False
+        self._closed = asyncio.Event()
+        self._close_reason: str | None = None
+        # Cooperative-shutdown request towards the owning task body.
+        self.close_requested = asyncio.Event()
+        self._event_queue: asyncio.Queue[dict] = asyncio.Queue()
+        self._event_handlers: list = []
+        self._message_handlers: list = []
+        self._permission_handler = None
+        self._queued_permission_requests: list[dict] = []
+        self._answered_permissions: set[str] = set()
+        # Text parts of the in-flight assistant message, keyed by part id —
+        # joined and fired via on_message when the message completes.
+        self._part_texts: dict[str, dict[str, str]] = {}
+        self._dispatcher_task: asyncio.Task | None = None
+        self._http: aiohttp.ClientSession | None = None
+
+    # -- wiring ------------------------------------------------------------
+
+    async def run_reader(self) -> None:
+        """Connect to /global/event and dispatch frames until cancelled (by
+        the session body at teardown) or closed. Reconnects with backoff."""
+        self._dispatcher_task = asyncio.create_task(self._dispatch_loop())
+        self._http = aiohttp.ClientSession(auth=self._auth)
+        attempt = 0
+        try:
+            while not self._closed.is_set():
+                try:
+                    await self._consume_sse()
+                    attempt = 0  # clean EOF: server still alive, reconnect fresh
+                except (aiohttp.ClientError, ConnectionError, asyncio.TimeoutError) as exc:
+                    _LOG.info("conversation: SSE drop (%s); reconnecting", exc)
+                delay = _RECONNECT_DELAYS[min(attempt, len(_RECONNECT_DELAYS) - 1)]
+                attempt += 1
+                await asyncio.sleep(delay)
+        finally:
+            await self._finish("process ended")
+            await self._http.close()
+
+    def _url(self, path: str) -> str:
+        return f"{self._base}{path}"
+
+    def _params(self) -> dict:
+        return {"directory": self._directory}
+
+    async def _consume_sse(self) -> None:
+        timeout = aiohttp.ClientTimeout(total=None, sock_connect=10)
+        # /global/event, not /event?directory=…: the per-instance endpoint
+        # ends its stream right after server.connected (observed on 1.14.45),
+        # so we take the global firehose and filter by directory ourselves.
+        async with self._http.get(
+            self._url("/global/event"), timeout=timeout,
+        ) as resp:
+            resp.raise_for_status()
+            # A (re)connect can postdate permission.asked events we never saw.
+            await self._sweep_permissions()
+            data_lines: list[str] = []
+            async for raw in resp.content:
+                line = raw.decode("utf-8", errors="replace").rstrip("\n").rstrip("\r")
+                if line.startswith("data:"):
+                    data_lines.append(line[5:].lstrip())
+                    continue
+                if line == "" and data_lines:
+                    payload = "\n".join(data_lines)
+                    data_lines = []
+                    try:
+                        obj = json.loads(payload)
+                    except ValueError:
+                        _LOG.warning("conversation: unparseable SSE data: %.200s", payload)
+                        self._event_queue.put_nowait(
+                            {"type": "x-optio-unparseable", "line": payload},
+                        )
+                        continue
+                    self._route_frame(obj)
+
+    # -- event routing -------------------------------------------------------
+
+    def _route_frame(self, obj: dict) -> None:
+        """Unwrap one /global/event frame: drop other directories' events,
+        route the inner ``{"id", "type", "properties"}`` payload. Bare
+        (unwrapped) frames are routed as-is for fake/forward compatibility."""
+        frame_dir = obj.get("directory")
+        if (
+            frame_dir is not None
+            and frame_dir != self._directory
+            and os.path.realpath(frame_dir) != self._directory_real
+        ):
+            return
+        payload = obj.get("payload")
+        self._route(payload if isinstance(payload, dict) else obj)
+
+    def _for_this_session(self, props: dict) -> bool:
+        sid = (
+            props.get("sessionID")
+            or (props.get("info") or {}).get("sessionID")
+            or (props.get("part") or {}).get("sessionID")
+        )
+        return sid is None or sid == self._session_id
+
+    def _route(self, obj: dict) -> None:
+        t = obj.get("type") or ""
+        props = obj.get("properties") or {}
+        if t == "permission.asked" and self._for_this_session(props):
+            self._on_permission_asked(props)
+        elif t == "message.part.updated":
+            part = props.get("part") or {}
+            if part.get("type") == "text" and self._for_this_session(props):
+                mid, pid = str(part.get("messageID")), str(part.get("id"))
+                self._part_texts.setdefault(mid, {})[pid] = part.get("text") or ""
+        elif t == "message.updated":
+            info = props.get("info") or {}
+            if (
+                info.get("role") == "assistant"
+                and (info.get("time") or {}).get("completed")
+                and self._for_this_session(props)
+            ):
+                parts = self._part_texts.pop(str(info.get("id")), {})
+                if parts:
+                    self._fire_message("\n\n".join(parts.values()))
+        elif t in ("session.status", "session.idle") and self._for_this_session(props):
+            status = props.get("status") or {}
+            if t == "session.idle" or status.get("type") == "idle":
+                self._pending = False
+            elif status.get("type") == "busy":
+                self._pending = True
+        self._event_queue.put_nowait(obj)
+
+    async def _dispatch_loop(self) -> None:
+        while True:
+            obj = await self._event_queue.get()
+            for handler in list(self._event_handlers):
+                await self._call_handler(handler, obj, "on_event")
+
+    async def _call_handler(self, handler, arg, label: str) -> None:
+        try:
+            result = handler(arg)
+            if asyncio.iscoroutine(result):
+                await result
+        except Exception:  # noqa: BLE001 — subscriber bugs never kill the driver
+            _LOG.exception("conversation: %s handler raised", label)
+
+    def _fire_message(self, text: str) -> None:
+        for handler in list(self._message_handlers):
+            asyncio.ensure_future(self._call_handler(handler, text, "on_message"))
+
+    # -- permission gate -------------------------------------------------------
+
+    def _on_permission_asked(self, props: dict) -> None:
+        rid = str(props.get("id") or "")
+        if not rid or rid in self._answered_permissions:
+            return
+        if self._permission_handler is None:
+            # Queue until a handler is registered: opencode blocks the session
+            # on the unanswered ask, which closes the publish/registration
+            # race. Documented caller contract: register promptly.
+            self._queued_permission_requests.append(props)
+            return
+        asyncio.ensure_future(self._answer_permission(props))
+
+    async def _sweep_permissions(self) -> None:
+        """Fetch pending permission requests and feed unanswered ones for our
+        session to the gate. Gap-safety: covers asks fired while the SSE
+        stream was down (opencode's /global/event has no server-side replay)."""
+        try:
+            async with self._http.get(
+                self._url("/permission"), params=self._params(),
+            ) as resp:
+                resp.raise_for_status()
+                pending = await resp.json()
+        except (aiohttp.ClientError, ConnectionError, ValueError) as exc:
+            _LOG.warning("conversation: permission sweep failed: %s", exc)
+            return
+        for props in pending:
+            if props.get("sessionID") in (None, self._session_id):
+                self._on_permission_asked(props)
+
+    async def _answer_permission(self, props: dict) -> None:
+        rid = str(props.get("id"))
+        if rid in self._answered_permissions:
+            return
+        self._answered_permissions.add(rid)
+        request = PermissionRequest(
+            tool_name=str(props.get("permission") or ""),
+            input=props.get("metadata") or {},
+            raw=props,
+        )
+        try:
+            decision = await self._permission_handler(request)
+        except Exception:  # noqa: BLE001
+            _LOG.exception("conversation: permission handler raised; denying")
+            decision = PermissionDecision(
+                behavior="deny", message="optio harness: permission handler failed",
+            )
+        # opencode reply vocabulary: allow → "once" (never "always": the optio
+        # gate decides per request); deny → "reject". updated_input has no
+        # opencode equivalent and is ignored.
+        body: dict = (
+            {"reply": "once"} if decision.behavior == "allow"
+            else {"reply": "reject", "message": decision.message or "Denied by the operator."}
+        )
+        try:
+            async with self._http.post(
+                self._url(f"/permission/{rid}/reply"),
+                params=self._params(), json=body,
+            ) as resp:
+                if resp.status >= 400:
+                    _LOG.warning(
+                        "conversation: permission reply %s → HTTP %s "
+                        "(likely already answered elsewhere)", rid, resp.status,
+                    )
+        except (aiohttp.ClientError, ConnectionError) as exc:
+            _LOG.warning("conversation: permission reply failed: %s", exc)
+        self._event_queue.put_nowait({
+            "type": "x-optio-permission-answered",
+            "request_id": rid,
+            "behavior": decision.behavior,
+        })
+
+    # -- Conversation protocol surface --------------------------------------
+
+    async def send(self, text: str) -> None:
+        if self._closed.is_set():
+            raise ConversationClosed(self._close_reason or "conversation closed")
+        self._pending = True
+        try:
+            async with self._http.post(
+                self._url(f"/session/{self._session_id}/prompt_async"),
+                params=self._params(),
+                json={"parts": [{"type": "text", "text": text}]},
+            ) as resp:
+                resp.raise_for_status()
+        except (aiohttp.ClientError, ConnectionError) as exc:
+            self._pending = False
+            raise ConversationClosed(f"send failed: {exc}") from exc
+
+    def on_event(self, handler):
+        self._event_handlers.append(handler)
+        return lambda: self._event_handlers.remove(handler)
+
+    def on_message(self, handler):
+        self._message_handlers.append(handler)
+        return lambda: self._message_handlers.remove(handler)
+
+    def on_permission_request(self, handler):
+        self._permission_handler = handler
+        queued, self._queued_permission_requests = (
+            self._queued_permission_requests, [],
+        )
+        for props in queued:
+            asyncio.ensure_future(self._answer_permission(props))
+
+        def _unsub() -> None:
+            if self._permission_handler is handler:
+                self._permission_handler = None
+        return _unsub
+
+    def is_pending(self) -> bool:
+        return self._pending
+
+    async def interrupt(self) -> None:
+        if self._closed.is_set():
+            raise ConversationClosed(self._close_reason or "conversation closed")
+        if not self._pending:
+            return
+        async with self._http.post(
+            self._url(f"/session/{self._session_id}/abort"),
+            params=self._params(), json={},
+        ) as resp:
+            resp.raise_for_status()
+
+    async def close(self) -> None:
+        self.close_requested.set()
+
+    @property
+    def closed(self) -> bool:
+        return self._closed.is_set()
+
+    # -- internals -----------------------------------------------------------
+
+    async def _finish(self, reason: str) -> None:
+        if self._closed.is_set():
+            return
+        self._closed.set()
+        self._close_reason = reason
+        self._event_queue.put_nowait({"type": "x-optio-closed", "reason": reason})
+        # Stop the dispatcher, then drain whatever it left in the queue so
+        # subscribers are guaranteed to see the final x-optio-closed event.
+        if self._dispatcher_task is not None:
+            self._dispatcher_task.cancel()
+            try:
+                await self._dispatcher_task
+            except asyncio.CancelledError:
+                pass
+            self._dispatcher_task = None
+        while not self._event_queue.empty():
+            obj = self._event_queue.get_nowait()
+            for handler in list(self._event_handlers):
+                await self._call_handler(handler, obj, "on_event")

optio_opencode/cred_watcher.py

@@ -0,0 +1,129 @@
+"""In-session credential save-back for opencode seeds.
+
+OAuth providers with rotating refresh tokens (xAI, OpenAI/Codex) make
+refresh tokens single-use: opencode's plugin loader() refreshes a token on
+use, the provider rotates the refresh token, and opencode persists the
+rotated pair to auth.json (best-effort). This watcher keeps the seed
+current by writing the changed in-session auth.json back into the existing
+seed, plus a final backstop at teardown. Provider-agnostic: opencode does
+the refreshing; the watcher only persists the file.
+
+The seed is the single source of truth for credentials; see
+docs/2026-06-11-opencode-seed-save-back-design.md.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+from typing import Callable
+
+from optio_agents import seeds
+from optio_host.host import Host
+
+from optio_opencode.seed_manifest import OPENCODE_CRED_MANIFEST, OPENCODE_SEED_SUFFIX
+
+_LOG = logging.getLogger(__name__)
+
+CRED_WATCH_INTERVAL_S = 10.0
+_CRED_RELPATH = "home/.local/share/opencode/auth.json"
+_MODEL_RELPATH = "home/.config/opencode/opencode.json"
+
+
+async def cred_fingerprint(host: Host) -> str | None:
+    """SHA-256 of the live auth.json, or None when it is missing,
+    unparseable, or carries no provider entry (i.e. nothing worth saving
+    back). The multi-provider analog of claudecode's refresh-token gate —
+    guards against corrupting a seed with a half-written/logged-out file."""
+    path = f"{host.workdir.rstrip('/')}/{_CRED_RELPATH}"
+    try:
+        raw = await host.fetch_bytes_from_host(path)
+    except FileNotFoundError:
+        return None
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return None
+    if not isinstance(data, dict) or not data:
+        return None
+    return hashlib.sha256(raw).hexdigest()
+
+
+async def capture_gate_ok(host: Host) -> bool:
+    """Stricter gate for seed CAPTURE: valid auth.json (cred_fingerprint)
+    AND a non-empty `model` in the live opencode.json. A model-less seed is
+    unusable — a consuming task gets no default and verify has nothing to
+    probe. Save-back deliberately does NOT use this gate: save-back only
+    replaces auth.json (the seed's opencode.json is untouched), and blocking
+    it over an unrelated field would drop a rotated refresh token."""
+    if await cred_fingerprint(host) is None:
+        return False
+    path = f"{host.workdir.rstrip('/')}/{_MODEL_RELPATH}"
+    try:
+        raw = await host.fetch_bytes_from_host(path)
+        cfg = json.loads(raw.decode("utf-8"))
+    except (FileNotFoundError, ValueError, UnicodeDecodeError):
+        return False
+    return isinstance(cfg, dict) and bool(cfg.get("model"))
+
+
+async def save_back_if_changed(
+    ctx,
+    host: Host,
+    *,
+    seed_id: str,
+    baseline: str | None,
+    encrypt: "Callable[[bytes], bytes] | None",
+    decrypt: "Callable[[bytes], bytes] | None",
+) -> str | None:
+    """If the live auth.json differs from `baseline` and is valid, save it
+    back into the seed and return the new fingerprint. Otherwise return
+    `baseline` unchanged. Never raises — save-back is best-effort."""
+    fp = await cred_fingerprint(host)
+    if fp is None or fp == baseline:
+        return baseline
+    try:
+        await seeds.refresh_seed(
+            ctx, host, seed_id=seed_id, manifest=OPENCODE_CRED_MANIFEST,
+            suffix=OPENCODE_SEED_SUFFIX, encrypt=encrypt, decrypt=decrypt,
+        )
+        _LOG.info("seed %s: auth.json saved back", seed_id)
+        return fp
+    except Exception:
+        _LOG.exception("seed %s: auth.json save-back failed", seed_id)
+        return baseline
+
+
+async def run_credential_watcher(
+    ctx,
+    host: Host,
+    *,
+    seed_id: str,
+    baseline: str | None,
+    encrypt: "Callable[[bytes], bytes] | None",
+    decrypt: "Callable[[bytes], bytes] | None",
+    lease_holder: str | None = None,
+) -> None:
+    """Poll every CRED_WATCH_INTERVAL_S: save back rotated auth.json, and
+    (when `lease_holder` is set) renew the seed's lease. If the lease is
+    lost, signal the session to stop (set the cancellation flag) and exit —
+    continuing would mean a token-rotation collision with the new holder.
+    Runs until cancelled. Best-effort save-back; lease-loss is decisive."""
+    current = baseline
+    while True:
+        await asyncio.sleep(CRED_WATCH_INTERVAL_S)
+        current = await save_back_if_changed(
+            ctx, host, seed_id=seed_id, baseline=current,
+            encrypt=encrypt, decrypt=decrypt,
+        )
+        if lease_holder is not None:
+            ok = await seeds.renew_lease(
+                ctx._db, prefix=ctx._prefix, suffix=OPENCODE_SEED_SUFFIX,
+                seed_id=seed_id, holder=lease_holder,
+            )
+            if not ok:
+                _LOG.warning("seed %s: lease lost; aborting session", seed_id)
+                ctx.cancellation_flag.set()
+                return

optio_opencode/host_actions.py

@@ -145,14 +145,20 @@ async def _smart_install_check(
 
 
 async def _install_opencode_from_zip(
-    hook_ctx, url: str, *, install_dir: str | None = None,
+    host: "Host",
+    download: "Callable[[str, str], Awaitable[None]]",
+    url: str,
+    *,
+    install_dir: str | None = None,
 ) -> str:
     """Download the opencode release archive from ``url`` and install it.
 
     Uniform for LocalHost and RemoteHost:
       1. mktemp -d on the host.
-      2. ``hook_ctx.download_file(url, <tmpdir>/opencode.zip)`` (spawns the
-         child download task — emits its own progress on the child ctx).
+      2. ``download(url, <tmpdir>/opencode.zip)`` (engine callers pass
+         ``hook_ctx.download_file``, which spawns the child download task —
+         emits its own progress on the child ctx; engine-less callers pass
+         ``curl_downloader(host)``).
       3. unzip on the host (archive layout: ``bin/opencode`` + sidecars).
       4. mkdir -p ``install_dir``; move binary there; chmod +x.
       5. Remove the tempdir.
@@ -162,7 +168,6 @@ async def _install_opencode_from_zip(
 
     Returns the absolute install path on the host.
     """
-    host = hook_ctx._host
     resolved_install_dir = await _resolve_install_dir(host, install_dir)
     r = await host.run_command("mktemp -d -t optio-opencode-XXXXXX")
     if r.exit_code != 0:
@@ -172,7 +177,7 @@ async def _install_opencode_from_zip(
     tmpdir = r.stdout.strip()
     zip_path = f"{tmpdir}/opencode.zip"
     try:
-        await hook_ctx.download_file(url, zip_path)
+        await download(url, zip_path)
 
         r = await host.run_command(
             f"unzip -o -q {shlex.quote(zip_path)} -d {shlex.quote(tmpdir)}"
@@ -211,20 +216,23 @@ async def _install_opencode_from_zip(
 
 
 async def ensure_opencode_installed(
-    hook_ctx,
-    install_if_missing: bool = True,
+    host: "Host",
     *,
+    download: "Callable[[str, str], Awaitable[None]]",
+    report_progress: "Callable | None" = None,
+    install_if_missing: bool = True,
     install_dir: str | None = None,
 ) -> str:
-    """Ensure opencode is available on the host behind ``hook_ctx``.
+    """Ensure opencode is available on ``host``.
 
     Uniform local + remote: runs the upstream smart-install.sh in
     ``--check`` mode via ``host.run_command``. If the host already has the
     latest opencode, returns the absolute path that ``command -v opencode``
-    resolves to. Otherwise — when ``install_if_missing`` is True — downloads
-    the release zip (as an optio child task, so progress shows up in the
-    UI), unpacks it, and installs the binary at
-    ``<install_dir>/opencode``.
+    resolves to. Otherwise — when ``install_if_missing`` is True — fetches
+    the release zip via ``download`` (engine callers pass
+    ``hook_ctx.download_file``, so progress shows up in the UI as an optio
+    child task; engine-less callers pass ``curl_downloader(host)``),
+    unpacks it, and installs the binary at ``<install_dir>/opencode``.
 
     ``install_dir`` is the absolute path of the directory that holds (or
     will hold) the ``opencode`` binary on the host. When None (default),
@@ -235,17 +243,23 @@ async def ensure_opencode_installed(
     smart-install's PATH lookup, and for the post-"ok" ``command -v``
     resolution, so all three stay in agreement.
 
+    INVARIANT: install-dir resolution (_resolve_install_dir) runs against the
+    host's REAL environment, never under _isolation_env. If the per-task
+    isolation env leaked in, XDG_CACHE_HOME would point inside the (possibly
+    throwaway) workdir: the binary would re-download per run and be deleted
+    at teardown. The shared worker cache must stay outside every workdir.
+
     Returns the absolute path of the opencode binary on the host.
 
     Raises RuntimeError when the check is unparseable, when an install is
     needed but ``install_if_missing`` is False, or when any sub-step fails.
     """
-    host = hook_ctx._host
     resolved_install_dir = await _resolve_install_dir(host, install_dir)
     # Mark the parent task indeterminate-active before any host I/O so the
     # dashboard shows it working rather than stuck at 0% while the install
     # check (and any subsequent download child task) runs.
-    hook_ctx.report_progress(None, "Checking opencode installation…")
+    if report_progress is not None:
+        report_progress(None, "Checking opencode installation…")
     kind, url = await _smart_install_check(host, install_dir=resolved_install_dir)
     if kind == "ok":
         # Resolve the on-PATH path. Login shell so ``$HOME``-relative
@@ -271,10 +285,64 @@ async def ensure_opencode_installed(
             "install_if_missing=False was requested."
         )
     assert url is not None  # _smart_install_check guarantees
-    hook_ctx.report_progress(None, "Installing opencode…")
+    if report_progress is not None:
+        report_progress(None, "Installing opencode…")
     return await _install_opencode_from_zip(
-        hook_ctx, url, install_dir=resolved_install_dir,
+        host, download, url, install_dir=resolved_install_dir,
+    )
+
+
+def curl_downloader(host: "Host") -> "Callable[[str, str], Awaitable[None]]":
+    """Context-free downloader for engine-less callers (verify): fetch a URL
+    to a host path via curl on the host itself, vs the engine's child-task
+    download_file."""
+    async def download(url: str, dest: str) -> None:
+        r = await host.run_command(
+            f"curl -fsSL {shlex.quote(url)} -o {shlex.quote(dest)}"
+        )
+        if r.exit_code != 0:
+            raise RuntimeError(
+                f"curl download failed (exit {r.exit_code}): {r.stderr.strip()[:200]}"
+            )
+    return download
+
+
+def build_host(ssh, taskdir: str) -> "Host":
+    """ssh_config + taskdir -> LocalHost/RemoteHost. Lifted from
+    session._build_host so engine-less callers (verify) share it."""
+    import os as _os
+    from optio_host.host import LocalHost, RemoteHost
+
+    if ssh is None:
+        _os.makedirs(taskdir, exist_ok=True)
+        host = LocalHost(taskdir=taskdir)
+        _os.makedirs(host.workdir, exist_ok=True)
+        return host
+    return RemoteHost(ssh_config=ssh, taskdir=taskdir)
+
+
+async def run_opencode_probe(
+    host: "Host",
+    *,
+    opencode_executable: str,
+    model: str,
+    prompt: str,
+    wrap: "list[str] | None" = None,
+    timeout_s: float = 180.0,
+) -> "tuple[str, int]":
+    """Headless one-shot `opencode run` under the per-task isolation env.
+    Returns (stdout, exit_code). `wrap` is an argv prefix seam (future
+    claustrum fs-isolation). Plain output — the caller's verdict is a
+    challenge-answer match on stdout; exit code is diagnostics only."""
+    import asyncio as _asyncio
+
+    argv = [*(wrap or []), opencode_executable, "run", "--model", model, prompt]
+    cmd = " ".join(shlex.quote(a) for a in argv)
+    result = await _asyncio.wait_for(
+        host.run_command(f"bash -lc {shlex.quote(cmd)}", env=_isolation_env(host)),
+        timeout=timeout_s,
     )
+    return (result.stdout or "", result.exit_code)
 
 
 async def opencode_version(