py-opencode-wrapper 0.2.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

opencode_wrapper/__init__.py

@@ -1,7 +1,12 @@
 """OpenCode CLI async wrapper for Python orchestration."""
 
 from opencode_wrapper.client import AsyncOpenCodeClient, build_argv, build_env, resolve_binary
-from opencode_wrapper.config import RunConfig, validate_config_for_run, validate_permission_actions
+from opencode_wrapper.config import (
+    RunConfig,
+    split_model,
+    validate_config_for_run,
+    validate_permission_actions,
+)
 from opencode_wrapper.errors import (
     OpenCodeBinaryNotFoundError,
     OpenCodeCancelledError,
@@ -13,21 +18,28 @@ from opencode_wrapper.events import (
     RunResult,
     TokenUsage,
     aggregate_run_result,
+    aggregate_server_result,
     parse_event_line,
     run_result_fuzzy_text,
 )
+from opencode_wrapper.session import OpenCodeSession, PermissionCallback, QuestionCallback
 
 __all__ = [
     "AsyncOpenCodeClient",
+    "OpenCodeSession",
+    "PermissionCallback",
+    "QuestionCallback",
     "RunConfig",
     "RunResult",
     "TokenUsage",
     "aggregate_run_result",
+    "aggregate_server_result",
     "build_argv",
     "build_env",
     "parse_event_line",
     "run_result_fuzzy_text",
     "resolve_binary",
+    "split_model",
     "validate_config_for_run",
     "validate_permission_actions",
     "OpenCodeError",

opencode_wrapper/client.py

@@ -38,43 +38,34 @@ def build_argv(
     prompt: str,
     run_cfg: RunConfig,
 ) -> list[str]:
-    """Build ``opencode run`` argument list."""
+    """Build ``opencode run`` argument list.
+
+    ``model`` / ``agent`` are structured fields shared with server mode and map
+    to ``-m`` / ``--agent``.  Every other ``opencode run`` flag is passed through
+    ``run_cfg.cli_kwargs``: each entry expands to ``--flag`` (bool ``True``),
+    ``--flag=value`` (multi-char key) / ``-f value`` (single-char key), or a
+    repetition per element (list/tuple value).  ``False`` / ``None`` are skipped.
+    The argv list is handed to ``create_subprocess_exec`` (no shell), so values
+    are not subject to shell injection.
+    """
     cmd: list[str] = [binary_resolved, "run", "--format", "json"]
-
-    if run_cfg.print_logs:
-        cmd.append("--print-logs")
-    if run_cfg.log_level:
-        cmd.extend(["--log-level", run_cfg.log_level])
-    if run_cfg.command:
-        cmd.extend(["--command", run_cfg.command])
-    if run_cfg.continue_session:
-        cmd.append("--continue")
-    if run_cfg.session_id:
-        cmd.extend(["--session", run_cfg.session_id])
-    if run_cfg.fork:
-        cmd.append("--fork")
-    if run_cfg.share is True:
-        cmd.append("--share")
     if run_cfg.model:
         cmd.extend(["-m", run_cfg.model])
     if run_cfg.agent:
         cmd.extend(["--agent", run_cfg.agent])
-    for f in run_cfg.files:
-        cmd.extend(["-f", str(f)])
-    if run_cfg.title:
-        cmd.extend(["--title", run_cfg.title])
-    if run_cfg.attach:
-        cmd.extend(["--attach", run_cfg.attach])
-    if run_cfg.password:
-        cmd.extend(["-p", run_cfg.password])
-    if run_cfg.remote_dir:
-        cmd.extend(["--dir", run_cfg.remote_dir])
-    if run_cfg.port is not None:
-        cmd.extend(["--port", str(run_cfg.port)])
-    if run_cfg.variant:
-        cmd.extend(["--variant", run_cfg.variant])
-    if run_cfg.record_thinking is True or run_cfg.thinking is True:
-        cmd.append("--thinking")
+
+    for key, val in (run_cfg.cli_kwargs or {}).items():
+        flag = f"-{key}" if len(key) == 1 else f"--{key}"
+        vals = val if isinstance(val, (list, tuple)) else [val]
+        for v in vals:
+            if v is True:
+                cmd.append(flag)
+            elif v is False or v is None:
+                continue
+            elif len(key) == 1:
+                cmd.extend([flag, str(v)])
+            else:
+                cmd.append(f"{flag}={v}")
 
     if prompt:
         cmd.append(prompt)
@@ -313,15 +304,23 @@ class AsyncOpenCodeClient:
         cwd: str,
         env: dict[str, str],
         run_cfg: RunConfig,
+        data_home: str | None = None,
     ) -> AsyncIterator[tuple[asyncio.subprocess.Process, list[str]]]:
         stderr_lines: list[str] = []
         cleanup_tmpdirs: list[str] = []
         # Give each process its own XDG_DATA_HOME so opencode.db is isolated.
         # Without this, all concurrent processes share ~/.local/share/opencode/opencode.db
         # and SQLite write locks during tool execution serialize the runs (37–46s delays).
-        if self._isolate_db:
-            xdg_tmpdir = tempfile.mkdtemp(prefix="oc_xdg_")
-            cleanup_tmpdirs.append(xdg_tmpdir)
+        # When *data_home* is provided the caller owns a persistent dir (e.g. an
+        # OpenCodeSession reusing one DB across turns), so it is NOT added to
+        # cleanup_tmpdirs — the caller deletes it when done.
+        managed = data_home is not None
+        if self._isolate_db or managed:
+            if managed:
+                xdg_tmpdir = data_home  # type: ignore[assignment]
+            else:
+                xdg_tmpdir = tempfile.mkdtemp(prefix="oc_xdg_")
+                cleanup_tmpdirs.append(xdg_tmpdir)
             # Symlink auth.json so provider API keys (stored by `opencode auth`)
             # are visible in the isolated data dir.  Without this, providers
             # that rely on auth.json (rather than env-var keys) fail with
@@ -331,7 +330,9 @@ class AsyncOpenCodeClient:
             if real_auth.is_file():
                 iso_oc_dir = Path(xdg_tmpdir) / "opencode"
                 iso_oc_dir.mkdir(parents=True, exist_ok=True)
-                (iso_oc_dir / "auth.json").symlink_to(real_auth)
+                link = iso_oc_dir / "auth.json"
+                if not link.exists():  # reused across turns — guard re-symlink
+                    link.symlink_to(real_auth)
             env = {**env, "XDG_DATA_HOME": xdg_tmpdir}
         # When the caller has not opted into host-config inheritance (the
         # default), redirect XDG_CONFIG_HOME / OPENCODE_TEST_HOME at a sanitized
@@ -425,6 +426,7 @@ class AsyncOpenCodeClient:
         log_file: str | Path | None = None,
         max_retries: int = 2,
         retry_delay_s: float = 1.0,
+        data_home: str | None = None,
     ) -> RunResult:
         """
         Run to completion and return a :class:`RunResult`.
@@ -457,7 +459,7 @@ class AsyncOpenCodeClient:
 
             log_fh = open(log_file, "w") if log_file is not None else None
             try:
-                async with self._managed_process(argv, cwd, env, run_cfg) as (proc, stderr_lines):
+                async with self._managed_process(argv, cwd, env, run_cfg, data_home=data_home) as (proc, stderr_lines):
                     async for line, ev in _stdout_line_event_iter(proc):
                         raw_acc.append(line)
                         events_acc.append(ev)

opencode_wrapper/config.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass
-from pathlib import Path
 from typing import Any, Dict, Mapping
 
 # Permission values accepted by OpenCode
@@ -131,29 +130,17 @@ def _deep_merge(base: dict[str, Any], override: Mapping[str, Any]) -> dict[str,
 
 @dataclass
 class RunConfig:
-    """Per-invocation settings merged into env and CLI."""
+    """Per-invocation settings merged into env and CLI.
 
+    Most fields are honored by both modes (run mode via CLI/env, server/session
+    mode via the prompt body/env).  ``cli_kwargs`` is the exception: it is a
+    raw passthrough of ``opencode run`` CLI flags and is **ignored by server/
+    session mode**, which has no CLI surface.
+    """
+
+    # --- honored by both modes ---
     agent: str | None = None
     model: str | None = None
-    files: tuple[str | Path, ...] = ()
-    title: str | None = None
-    command: str | None = None
-    continue_session: bool = False
-    session_id: str | None = None
-    fork: bool = False
-    share: bool | None = None
-    attach: str | None = None
-    password: str | None = None
-    remote_dir: str | None = None
-    port: int | None = None
-    variant: str | None = None
-    # Include OpenCode reasoning/thinking parts in the JSON event stream.
-    # This maps to `opencode run --thinking`; it does not set model reasoning effort.
-    record_thinking: bool | None = None
-    # Backward-compatible alias for record_thinking.
-    thinking: bool | None = None
-    print_logs: bool | None = None
-    log_level: str | None = None
     disable_autoupdate: bool = True
     inherit_user_config: bool = False
     extra_env: Mapping[str, str] | None = None
@@ -163,6 +150,16 @@ class RunConfig:
     tools: dict[str, Any] | None = None
     instructions: list[str] | None = None
     config_overrides: dict[str, Any] | None = None
+    # --- run mode only: passed through verbatim to `opencode run` as CLI flags;
+    # server/session mode ignores this entirely.
+    # e.g. {"title": "x", "continue": True, "session": "ses_1", "fork": True,
+    #       "thinking": True, "f": ["a.txt"]}
+    # build_argv expands each entry: bool True -> "--flag", a value -> "--flag=value"
+    # (long) or "-f value" (single-char), a list -> repeated, False/None -> skipped.
+    # Note: server mode has no --thinking equivalent; reasoning parts are produced
+    # per the model's reasoning config and published to the SSE bus unconditionally,
+    # so they already land in result.events / log_file with no opt-in.
+    cli_kwargs: dict[str, Any] | None = None
 
     def build_opencode_config_dict(self) -> dict[str, Any]:
         """Build the dict serialized to ``OPENCODE_CONFIG_CONTENT``."""
@@ -186,15 +183,32 @@ class RunConfig:
         return json.dumps(cfg, ensure_ascii=False)
 
 
-def validate_permission_actions(obj: Any, *, _path: str = "") -> None:
-    """Ensure string leaves are non-interactive OpenCode permission actions.
+def split_model(model: str) -> dict[str, str]:
+    """Split a ``"providerID/modelID"`` string into the server prompt-body shape.
+
+    opencode's server API wants ``{"providerID": ..., "modelID": ...}`` whereas
+    ``opencode run -m`` takes the ``provider/model`` string.  Only the first ``/``
+    separates provider from model (model ids may themselves contain ``/``).  A
+    string with no ``/`` is treated as a bare model id with an empty provider,
+    letting the server fall back to its default provider resolution.
+    """
+    provider, sep, rest = model.partition("/")
+    if not sep:
+        return {"providerID": "", "modelID": model}
+    return {"providerID": provider, "modelID": rest}
+
+
+def validate_permission_actions(obj: Any, *, _path: str = "", allow_ask: bool = False) -> None:
+    """Ensure string leaves are valid OpenCode permission actions.
 
-    ``"ask"`` is rejected because the subprocess has no terminal to prompt —
-    it would block forever.
+    ``"ask"`` is rejected by default because the run-mode subprocess has no
+    terminal to prompt — it would block forever.  The server/session path passes
+    ``allow_ask=True`` because there a ``permission.asked`` event is answerable via
+    the ``on_permission`` callback.
     """
-    allowed = frozenset({"allow", "deny"})
+    allowed = frozenset({"allow", "deny", "ask"} if allow_ask else {"allow", "deny"})
     if isinstance(obj, str):
-        if obj == "ask":
+        if obj == "ask" and not allow_ask:
             loc = f" at {_path!r}" if _path else ""
             raise ValueError(
                 f"Permission action 'ask' is not supported in non-interactive "
@@ -209,7 +223,7 @@ def validate_permission_actions(obj: Any, *, _path: str = "") -> None:
     if isinstance(obj, dict):
         for k, v in obj.items():
             child_path = f"{_path}.{k}" if _path else k
-            validate_permission_actions(v, _path=child_path)
+            validate_permission_actions(v, _path=child_path, allow_ask=allow_ask)
 
 
 def validate_config_for_run(cfg: RunConfig) -> None:

opencode_wrapper/events.py

@@ -70,6 +70,16 @@ def _text_from_event(ev: dict[str, Any]) -> str | None:
     return None
 
 
+def _session_id_from_event(ev: dict[str, Any]) -> str | None:
+    sid = ev.get("sessionID")
+    if isinstance(sid, str):
+        return sid
+    part = ev.get("part")
+    if isinstance(part, dict) and isinstance(part.get("sessionID"), str):
+        return part["sessionID"]
+    return None
+
+
 def run_result_fuzzy_text(result: "RunResult") -> str:
     """
     Best-effort extract human-visible model output across varying ``--format json`` shapes.
@@ -136,9 +146,12 @@ class RunResult:
     token_usage: TokenUsage = field(default_factory=TokenUsage)
     total_cost: float = 0.0
     turns: int = 0
+    session_id: str | None = None
 
     def append_event(self, ev: dict[str, Any]) -> None:
         self.events.append(ev)
+        if self.session_id is None:
+            self.session_id = _session_id_from_event(ev)
         chunk = _text_from_event(ev)
         if chunk:
             self.final_text += chunk
@@ -190,3 +203,121 @@ def aggregate_run_result(
     for ev in events:
         r.append_event(ev)
     return r
+
+
+# ---------------------------------------------------------------------------
+# Server-mode (opencode serve / SSE) aggregation
+#
+# Server event shapes differ from `opencode run --format json`:
+#   {"type": "message.part.updated",
+#    "properties": {"sessionID": "...", "part": {"type": "text"|"tool"|"reasoning",
+#                                                 "text": "...", "id": "prt_...", ...}}}
+#   {"type": "message.updated", "properties": {"info": {"role": "assistant",
+#                                                       "tokens": {...}, "cost": ...}}}
+# Run-mode parsing above is intentionally left untouched.
+# ---------------------------------------------------------------------------
+
+
+def _server_assistant_text_from_messages(messages: list[dict[str, Any]]) -> str:
+    """Extract the last assistant message's concatenated text parts.
+
+    ``GET /session/{id}/message`` returns ``[{info:{role,...}, parts:[...]}, ...]``.
+    The authoritative final answer is the text parts of the final assistant turn.
+    """
+    last = ""
+    for m in messages:
+        info = m.get("info") if isinstance(m, dict) else None
+        if not isinstance(info, dict) or info.get("role") != "assistant":
+            continue
+        parts = m.get("parts")
+        if not isinstance(parts, list):
+            continue
+        texts = [
+            p["text"]
+            for p in parts
+            if isinstance(p, dict) and p.get("type") == "text" and isinstance(p.get("text"), str)
+        ]
+        joined = "".join(texts).strip()
+        if joined:
+            last = joined
+    return last
+
+
+def _accumulate_token_usage(usage: TokenUsage, tokens: Any, cost_acc: list[float], info: dict) -> None:
+    cost = info.get("cost")
+    if isinstance(cost, (int, float)):
+        cost_acc[0] += float(cost)
+    if isinstance(tokens, dict):
+        for attr, key in (("total", "total"), ("input", "input"), ("output", "output"), ("reasoning", "reasoning")):
+            val = tokens.get(key)
+            if isinstance(val, (int, float)):
+                setattr(usage, attr, getattr(usage, attr) + int(val))
+        cache = tokens.get("cache")
+        if isinstance(cache, dict):
+            for attr, key in (("cache_read", "read"), ("cache_write", "write")):
+                val = cache.get(key)
+                if isinstance(val, (int, float)):
+                    setattr(usage, attr, getattr(usage, attr) + int(val))
+
+
+def aggregate_server_result(
+    *,
+    events: list[dict[str, Any]],
+    session_id: str | None,
+    final_messages: list[dict[str, Any]] | None = None,
+    exit_code: int | None = 0,
+    stderr: str = "",
+) -> RunResult:
+    """Build a :class:`RunResult` from a server-mode turn's SSE events.
+
+    ``events`` are the raw SSE event dicts collected during the turn.  When
+    ``final_messages`` (the ``GET /session/{id}/message`` payload) is supplied it
+    is treated as the authoritative source for final text and token/cost totals;
+    otherwise those are reconstructed from the streamed events.
+    """
+    r = RunResult(events=list(events), exit_code=exit_code, stderr=stderr, session_id=session_id)
+
+    # tool_calls + streamed text snapshots keyed by part id (parts are replaced,
+    # not appended, as they stream — keep the latest snapshot per id).
+    text_by_part: dict[str, str] = {}
+    text_order: list[str] = []
+    cost_acc = [0.0]
+    seen_assistant_msgs: set[str] = set()
+
+    for ev in events:
+        etype = ev.get("type")
+        props = ev.get("properties", {}) if isinstance(ev.get("properties"), dict) else {}
+        if etype in ("message.part.updated", "message.part.delta"):
+            part = props.get("part")
+            if not isinstance(part, dict):
+                continue
+            ptype = part.get("type")
+            pid = part.get("id") or ""
+            if ptype == "text" and isinstance(part.get("text"), str):
+                if pid not in text_by_part:
+                    text_order.append(pid)
+                text_by_part[pid] = part["text"]
+            elif ptype == "tool":
+                r.tool_calls.append({
+                    "type": "tool",
+                    "tool": part.get("tool"),
+                    "callID": part.get("callID"),
+                    "state": part.get("state"),
+                    "id": pid,
+                })
+        elif etype == "message.updated":
+            info = props.get("info")
+            if isinstance(info, dict) and info.get("role") == "assistant":
+                mid = info.get("id") or ""
+                if mid not in seen_assistant_msgs:
+                    seen_assistant_msgs.add(mid)
+                    r.turns += 1
+                _accumulate_token_usage(r.token_usage, info.get("tokens"), cost_acc, info)
+
+    r.total_cost = cost_acc[0]
+
+    if final_messages is not None:
+        r.final_text = _server_assistant_text_from_messages(final_messages)
+    if not r.final_text:
+        r.final_text = "".join(text_by_part[pid] for pid in text_order).strip()
+    return r

opencode_wrapper/server.py

@@ -0,0 +1,255 @@
+"""Headless ``opencode serve`` lifecycle + a stdlib HTTP/SSE client.
+
+Backs :class:`opencode_wrapper.session.OpenCodeSession`.  One
+:class:`_OpenCodeServer` owns a single ``opencode serve`` subprocess for the
+lifetime of an ``async with`` session block: it spawns the server with the same
+hermetic env run mode uses, subscribes to the ``/event`` SSE bus, and exposes
+unary POST/GET/DELETE helpers.  Stdlib-only (``urllib`` + ``asyncio`` +
+``threading``) — preserves the wrapper's zero-runtime-deps invariant.
+
+The SSE bus is consumed in a daemon thread via ``urllib`` (which decodes chunked
+transfer-encoding transparently) and events are dispatched onto per-session
+``asyncio.Queue``s, so one server can fan events out to many sessions.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+import socket
+import tempfile
+import threading
+import urllib.error
+import urllib.request
+from collections import deque
+from pathlib import Path
+from typing import Any
+
+from opencode_wrapper.client import build_env, _isolate_user_config
+from opencode_wrapper.config import RunConfig
+from opencode_wrapper.errors import OpenCodeProcessError
+
+
+def _free_port() -> int:
+    """Pick an ephemeral free TCP port on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _event_session_id(ev: dict[str, Any]) -> str | None:
+    """Best-effort extract the sessionID a server SSE event belongs to."""
+    props = ev.get("properties")
+    if not isinstance(props, dict):
+        return None
+    sid = props.get("sessionID")
+    if isinstance(sid, str):
+        return sid
+    for key in ("part", "info"):
+        nested = props.get(key)
+        if isinstance(nested, dict) and isinstance(nested.get("sessionID"), str):
+            return nested["sessionID"]
+    return None
+
+
+class _OpenCodeServer:
+    """Owns one ``opencode serve`` process and its ``/event`` SSE subscription."""
+
+    def __init__(
+        self,
+        binary_resolved: str,
+        run_cfg: RunConfig,
+        workspace: str,
+    ) -> None:
+        self._binary = binary_resolved
+        self._run_cfg = run_cfg
+        self._workspace = workspace
+        self._port = _free_port()
+        self.base = f"http://127.0.0.1:{self._port}"
+
+        self._proc: asyncio.subprocess.Process | None = None
+        self._cleanup_dirs: list[str] = []
+        self._stderr_tail: deque[str] = deque(maxlen=200)
+
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._queues: dict[str, asyncio.Queue[dict[str, Any]]] = {}
+        self._sse_thread: threading.Thread | None = None
+        self._sse_resp: Any = None
+        self._sse_stop = threading.Event()
+        self._sse_connected = threading.Event()
+        self._tasks: list[asyncio.Task[Any]] = []
+
+    # -- env -----------------------------------------------------------------
+    def _build_server_env(self) -> dict[str, str]:
+        """Compose the child env: hermetic config + private SQLite data dir.
+
+        Reuses run mode's :func:`build_env` (OPENCODE_CONFIG_CONTENT, autoupdate,
+        PWD) and :func:`_isolate_user_config` (sanitized XDG_CONFIG_HOME) so the
+        session server is isolated exactly like an ``opencode run`` subprocess.
+        A private ``XDG_DATA_HOME`` tmpdir keeps the session's SQLite DB off the
+        host's global ``opencode.db`` and is removed on :meth:`aclose`.
+        """
+        env = build_env(self._run_cfg, cwd=self._workspace)
+        if not self._run_cfg.inherit_user_config:
+            cfg_tmp = tempfile.mkdtemp(prefix="oc_srv_cfg_")
+            self._cleanup_dirs.append(cfg_tmp)
+            env = _isolate_user_config(dict(env), Path(cfg_tmp))
+
+        data_tmp = tempfile.mkdtemp(prefix="oc_srv_data_")
+        self._cleanup_dirs.append(data_tmp)
+        real_xdg = env.get("XDG_DATA_HOME", str(Path.home() / ".local" / "share"))
+        real_auth = Path(real_xdg) / "opencode" / "auth.json"
+        if real_auth.is_file():
+            iso_oc = Path(data_tmp) / "opencode"
+            iso_oc.mkdir(parents=True, exist_ok=True)
+            link = iso_oc / "auth.json"
+            if not link.exists():
+                link.symlink_to(real_auth)
+        env["XDG_DATA_HOME"] = data_tmp
+        return env
+
+    # -- lifecycle -----------------------------------------------------------
+    async def start(self, *, health_timeout_s: float = 15.0) -> None:
+        self._loop = asyncio.get_running_loop()
+        env = self._build_server_env()
+        self._proc = await asyncio.create_subprocess_exec(
+            self._binary, "serve", "--port", str(self._port), "--hostname", "127.0.0.1",
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=self._workspace,
+            env=env,
+        )
+        self._tasks.append(asyncio.create_task(self._drain_stderr()))
+
+        deadline = self._loop.time() + health_timeout_s
+        while True:
+            if self._proc.returncode is not None:
+                raise OpenCodeProcessError(
+                    exit_code=self._proc.returncode,
+                    stderr="".join(self._stderr_tail),
+                    events=[],
+                    raw_stdout_lines=[],
+                )
+            try:
+                await asyncio.to_thread(self._get_sync, "/session")
+                break
+            except (urllib.error.URLError, ConnectionError, OSError):
+                if self._loop.time() >= deadline:
+                    await self.aclose()
+                    raise OpenCodeProcessError(
+                        exit_code=-1,
+                        stderr="opencode serve did not become healthy in "
+                        f"{health_timeout_s}s\n" + "".join(self._stderr_tail),
+                        events=[],
+                        raw_stdout_lines=[],
+                    )
+                await asyncio.sleep(0.1)
+
+        # Connect the SSE bus before any prompt is sent so no events are missed.
+        self._sse_thread = threading.Thread(target=self._run_sse, daemon=True)
+        self._sse_thread.start()
+        await asyncio.to_thread(self._sse_connected.wait, 5.0)
+
+    async def _drain_stderr(self) -> None:
+        assert self._proc is not None and self._proc.stderr is not None
+        while True:
+            line = await self._proc.stderr.readline()
+            if not line:
+                break
+            self._stderr_tail.append(line.decode(errors="replace"))
+
+    async def aclose(self) -> None:
+        self._sse_stop.set()
+        if self._sse_resp is not None:
+            try:
+                self._sse_resp.close()
+            except Exception:
+                pass
+        for t in self._tasks:
+            t.cancel()
+        if self._proc is not None and self._proc.returncode is None:
+            try:
+                self._proc.terminate()
+                await asyncio.wait_for(self._proc.wait(), timeout=5)
+            except asyncio.TimeoutError:
+                self._proc.kill()
+            except ProcessLookupError:
+                pass
+        for d in self._cleanup_dirs:
+            shutil.rmtree(d, ignore_errors=True)
+
+    @property
+    def stderr_tail(self) -> str:
+        return "".join(self._stderr_tail)
+
+    # -- SSE -----------------------------------------------------------------
+    def _run_sse(self) -> None:
+        try:
+            resp = urllib.request.urlopen(self.base + "/event", timeout=None)
+            self._sse_resp = resp
+            assert self._loop is not None
+            self._loop.call_soon_threadsafe(self._sse_connected.set)
+            for raw in resp:
+                if self._sse_stop.is_set():
+                    break
+                line = raw.decode(errors="replace").rstrip("\r\n")
+                if not line.startswith("data:"):
+                    continue
+                payload = line[len("data:"):].strip()
+                if not payload:
+                    continue
+                try:
+                    ev = json.loads(payload)
+                except json.JSONDecodeError:
+                    continue
+                self._loop.call_soon_threadsafe(self._dispatch, ev)
+        except Exception as exc:  # noqa: BLE001 - surface to consumers as an event
+            if self._loop is not None and not self._sse_stop.is_set():
+                self._loop.call_soon_threadsafe(
+                    self._dispatch, {"type": "_sse_error", "error": repr(exc)}
+                )
+        finally:
+            self._sse_connected.set()
+
+    def _dispatch(self, ev: dict[str, Any]) -> None:
+        if ev.get("type") == "_sse_error":
+            for q in self._queues.values():
+                q.put_nowait(ev)
+            return
+        sid = _event_session_id(ev)
+        if sid is not None and sid in self._queues:
+            self._queues[sid].put_nowait(ev)
+
+    def subscribe(self, session_id: str) -> "asyncio.Queue[dict[str, Any]]":
+        q: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self._queues[session_id] = q
+        return q
+
+    def unsubscribe(self, session_id: str) -> None:
+        self._queues.pop(session_id, None)
+
+    # -- HTTP (stdlib, run in a thread) --------------------------------------
+    def _request_sync(self, method: str, path: str, body: dict[str, Any] | None) -> Any:
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(
+            self.base + path,
+            data=data,
+            headers={"Content-Type": "application/json"} if data is not None else {},
+            method=method,
+        )
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            raw = resp.read()
+        return json.loads(raw) if raw else None
+
+    def _get_sync(self, path: str) -> Any:
+        return self._request_sync("GET", path, None)
+
+    async def post(self, path: str, body: dict[str, Any] | None = None) -> Any:
+        return await asyncio.to_thread(self._request_sync, "POST", path, body)
+
+    async def get(self, path: str) -> Any:
+        return await asyncio.to_thread(self._request_sync, "GET", path, None)
+
+    async def delete(self, path: str) -> Any:
+        return await asyncio.to_thread(self._request_sync, "DELETE", path, None)