py-opencode-wrapper 0.3.0__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,23 +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
+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)

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

@@ -203,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)

opencode_wrapper/session.py

@@ -1,42 +1,83 @@
-"""Stateful multi-turn conversation over a single opencode session."""
+"""Stateful multi-turn conversation over an ``opencode serve`` session.
+
+``OpenCodeSession`` is an async context manager that owns a headless
+``opencode serve`` process for the duration of the ``async with`` block.  On
+enter it spawns the server (with the same hermetic isolation run mode uses) and
+creates one opencode session pinned to the workspace directory; every
+:meth:`send` re-prompts that same session, so the model retains context natively
+across turns.  On exit the session is deleted and the server torn down.
+
+Unlike run mode, server mode can answer interactive prompts: pass an
+``on_permission`` async callback to pause on a ``permission.asked`` event and
+resume with ``"once"`` / ``"always"`` / ``"reject"``, and/or an ``on_question``
+callback to answer the ``question`` tool's ``question.asked`` event — neither is
+possible with the one-shot run-mode subprocess.
+"""
 
 from __future__ import annotations
 
-import dataclasses
-import shutil
-import tempfile
+import asyncio
+import json
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Optional
+from urllib.parse import quote
 
-from opencode_wrapper.config import RunConfig
-from opencode_wrapper.events import RunResult
+from opencode_wrapper.config import RunConfig, split_model, validate_permission_actions
+from opencode_wrapper.errors import OpenCodeProcessError, OpenCodeTimeoutError
+from opencode_wrapper.events import RunResult, aggregate_server_result
+from opencode_wrapper.server import _OpenCodeServer
 
 if TYPE_CHECKING:
     from opencode_wrapper.client import AsyncOpenCodeClient
 
-_UNSET: object = object()
+_UNSET: Any = object()
 
+# An async callback invoked on each permission request; returns the decision.
+PermissionCallback = Callable[[dict[str, Any]], Awaitable[str]]
 
-class OpenCodeSession:
-    """Multi-turn conversation backed by one persistent opencode session.
+# An async callback invoked on each ``question.asked`` request. Returns the
+# answers: a list with one entry per question, each entry a list of selected
+# option labels (multiple labels only when the question allows ``multiple``).
+# Returning ``None`` rejects the question (the model is told it was dismissed).
+QuestionCallback = Callable[[dict[str, Any]], Awaitable[Optional[list[list[str]]]]]
 
-    On ``__aenter__`` the session allocates a private ``XDG_DATA_HOME`` tmpdir.
-    Every :meth:`send` reuses it, so opencode's SQLite session DB survives across
-    turns — the first turn creates the session, later turns continue it via
-    ``--session <id>``.  The dir is a per-session island (no shared global DB, so
-    no cross-session lock contention) and is removed on ``__aexit__``.
+
+class OpenCodeSession:
+    """Multi-turn conversation backed by one ``opencode serve`` session.
 
     Parameters
     ----------
     client:
-        The :class:`AsyncOpenCodeClient` used to spawn each turn.
+        The :class:`AsyncOpenCodeClient`; used only to resolve the ``opencode``
+        binary path that the server is spawned from.
     workspace:
-        Project directory passed to every ``opencode run``.
+        Project directory the session is pinned to (``?directory=``); every
+        turn's tools resolve against it.
     run_cfg:
-        Base config applied to each turn; ``session_id`` is injected automatically
-        after the first turn.  A per-call override may be passed to :meth:`send`.
+        Base config.  ``permission`` / ``mcp`` / ``instructions`` /
+        ``config_overrides`` are baked into the server at enter (server-global).
+        ``model`` / ``agent`` / ``tools`` are sent per turn and may be overridden
+        per :meth:`send`.
     timeout_s:
-        Default per-turn timeout; overridable per :meth:`send` call.
+        Default per-turn timeout; overridable per :meth:`send`.
+    on_permission:
+        Async callback ``(permission_props) -> "once" | "always" | "reject"``.
+        When ``None`` (the default), any ``permission.asked`` is auto-rejected so
+        a turn never blocks waiting for input.
+    on_question:
+        Async callback ``(question_props) -> answers | None`` for the ``question``
+        tool's ``question.asked`` event. ``answers`` is a list with one entry per
+        question, each a list of selected option labels; ``None`` rejects the
+        question. When ``None`` (the default), any ``question.asked`` is
+        auto-rejected so a turn never blocks. The ``question`` tool is enabled by
+        default in ``opencode serve`` (it is gated on ``OPENCODE_CLIENT``, whose
+        default ``"cli"`` enables it).
+    log_file:
+        Session-level event log.  When given, every event from every turn is
+        appended to this file as a JSON line (flushed immediately), so partial
+        progress survives crashes.  These are the same event dicts that land in
+        each turn's ``result.events``.  The file is truncated once at
+        ``__aenter__`` and accumulates across all turns until ``__aexit__``.
     """
 
     def __init__(
@@ -46,22 +87,64 @@ class OpenCodeSession:
         *,
         run_cfg: RunConfig | None = None,
         timeout_s: float | None = None,
+        on_permission: Optional[PermissionCallback] = None,
+        on_question: Optional[QuestionCallback] = None,
+        log_file: str | Path | None = None,
     ) -> None:
         self._client = client
-        self._workspace = workspace
+        self._workspace = str(Path(workspace).expanduser().resolve())
         self._base_cfg = run_cfg or RunConfig()
         self._timeout_s = timeout_s
-        self._data_home: str | None = None
+        self._on_permission = on_permission
+        self._on_question = on_question
+        self._log_file = log_file
+        self._log_fh = None
+        self._server: _OpenCodeServer | None = None
         self.session_id: str | None = None
 
     async def __aenter__(self) -> "OpenCodeSession":
-        self._data_home = tempfile.mkdtemp(prefix="oc_session_")
+        if self._base_cfg.permission is not None:
+            # In server mode "ask" is answerable via on_permission.
+            validate_permission_actions(self._base_cfg.permission, allow_ask=True)
+        bin_path = self._client.resolved_binary()
+        self._server = _OpenCodeServer(bin_path, self._base_cfg, self._workspace)
+        await self._server.start()
+        session = await self._server.post(f"/session?directory={self._dir_q()}", {})
+        self.session_id = session["id"]
+        if self._log_file is not None:
+            self._log_fh = open(self._log_file, "w")
         return self
 
     async def __aexit__(self, *exc: object) -> None:
-        if self._data_home is not None:
-            shutil.rmtree(self._data_home, ignore_errors=True)
-            self._data_home = None
+        try:
+            if self._server is not None:
+                if self.session_id:
+                    try:
+                        await self._server.delete(f"/session/{self.session_id}")
+                    except Exception:
+                        pass
+                await self._server.aclose()
+                self._server = None
+                self.session_id = None
+        finally:
+            if self._log_fh is not None:
+                self._log_fh.close()
+                self._log_fh = None
+
+    def _dir_q(self) -> str:
+        return quote(self._workspace, safe="")
+
+    def _build_prompt_body(self, prompt: str, cfg: RunConfig) -> dict[str, Any]:
+        # cfg.cli_kwargs is run-mode only (it expands to `opencode run` CLI
+        # flags) and is intentionally ignored here — server mode has no CLI.
+        body: dict[str, Any] = {"parts": [{"type": "text", "text": prompt}]}
+        if cfg.model:
+            body["model"] = split_model(cfg.model)
+        if cfg.agent:
+            body["agent"] = cfg.agent
+        if cfg.tools:
+            body["tools"] = {k: bool(v) for k, v in cfg.tools.items()}
+        return body
 
     async def send(
         self,
@@ -69,22 +152,107 @@ class OpenCodeSession:
         *,
         run_cfg: RunConfig | None = None,
         timeout_s: float | object = _UNSET,
+        on_permission: Optional[PermissionCallback] | object = _UNSET,
+        on_question: Optional[QuestionCallback] | object = _UNSET,
     ) -> RunResult:
-        """Run one turn and return its :class:`RunResult`, continuing the session."""
-        if self._data_home is None:
-            raise RuntimeError(
-                "OpenCodeSession.send() must be called inside 'async with'"
-            )
+        """Run one turn on the persistent session and return its :class:`RunResult`.
+
+        Per-call ``run_cfg`` only affects prompt-body knobs (``model`` / ``agent``
+        / ``tools``); ``permission`` / ``mcp`` / ``instructions`` are fixed at
+        ``__aenter__``.  ``on_permission`` and ``on_question`` may be overridden
+        per call.
+        """
+        if self._server is None or self.session_id is None:
+            raise RuntimeError("OpenCodeSession.send() must be called inside 'async with'")
         cfg = run_cfg or self._base_cfg
-        if self.session_id:
-            cfg = dataclasses.replace(cfg, session_id=self.session_id)
-        result = await self._client.async_run(
-            prompt,
-            self._workspace,
-            run_cfg=cfg,
-            timeout_s=self._timeout_s if timeout_s is _UNSET else timeout_s,  # type: ignore[arg-type]
-            data_home=self._data_home,
-        )
-        if self.session_id is None and result.session_id:
-            self.session_id = result.session_id
-        return result
+        on_perm = self._on_permission if on_permission is _UNSET else on_permission  # type: ignore[assignment]
+        on_q = self._on_question if on_question is _UNSET else on_question  # type: ignore[assignment]
+        eff_timeout = self._timeout_s if timeout_s is _UNSET else timeout_s  # type: ignore[assignment]
+
+        coro = self._run_turn(prompt, cfg, on_perm, on_q)  # type: ignore[arg-type]
+        if eff_timeout is not None:
+            try:
+                return await asyncio.wait_for(coro, timeout=eff_timeout)  # type: ignore[arg-type]
+            except asyncio.TimeoutError as e:
+                raise OpenCodeTimeoutError(
+                    f"OpenCode session turn exceeded timeout_s={eff_timeout!r}"
+                ) from e
+        return await coro
+
+    async def _run_turn(
+        self,
+        prompt: str,
+        cfg: RunConfig,
+        on_perm: Optional[PermissionCallback],
+        on_question: Optional[QuestionCallback] = None,
+    ) -> RunResult:
+        assert self._server is not None and self.session_id is not None
+        sid = self.session_id
+        server = self._server
+        queue = server.subscribe(sid)
+        events: list[dict[str, Any]] = []
+        try:
+            body = self._build_prompt_body(prompt, cfg)
+            await server.post(f"/session/{sid}/prompt_async?directory={self._dir_q()}", body)
+
+            while True:
+                ev = await queue.get()
+                events.append(ev)
+                if self._log_fh is not None:
+                    self._log_fh.write(json.dumps(ev, ensure_ascii=False) + "\n")
+                    self._log_fh.flush()
+                etype = ev.get("type")
+                props = ev.get("properties", {}) if isinstance(ev.get("properties"), dict) else {}
+
+                if etype == "_sse_error":
+                    raise OpenCodeProcessError(
+                        exit_code=-1,
+                        stderr=str(ev.get("error", "")) + "\n" + server.stderr_tail,
+                        events=events,
+                        raw_stdout_lines=[],
+                    )
+                if etype in ("permission.asked", "permission.updated", "permission.ask"):
+                    pid = props.get("id")
+                    decision = await on_perm(props) if on_perm is not None else "reject"
+                    if pid:
+                        await server.post(
+                            f"/session/{sid}/permissions/{pid}", {"response": decision}
+                        )
+                    continue
+                if etype == "question.asked":
+                    qid = props.get("id")
+                    answers = await on_question(props) if on_question is not None else None
+                    if qid:
+                        if answers is None:
+                            await server.post(f"/question/{qid}/reject?directory={self._dir_q()}")
+                        else:
+                            await server.post(
+                                f"/question/{qid}/reply?directory={self._dir_q()}",
+                                {"answers": answers},
+                            )
+                    continue
+                if etype == "session.error":
+                    raise OpenCodeProcessError(
+                        exit_code=-1,
+                        stderr=f"session.error: {props!r}\n{server.stderr_tail}",
+                        events=events,
+                        raw_stdout_lines=[],
+                    )
+                if etype == "session.idle":
+                    break
+                if etype == "session.status":
+                    status = props.get("status")
+                    if isinstance(status, dict) and status.get("type") == "idle":
+                        break
+
+            try:
+                final_messages = await server.get(f"/session/{sid}/message?directory={self._dir_q()}")
+            except Exception:
+                final_messages = None
+            if not isinstance(final_messages, list):
+                final_messages = None
+            return aggregate_server_result(
+                events=events, session_id=sid, final_messages=final_messages
+            )
+        finally:
+            server.unsubscribe(sid)

{py_opencode_wrapper-0.3.0.dist-info → py_opencode_wrapper-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-opencode-wrapper
-Version: 0.3.0
+Version: 0.3.1
 Summary: Async Python wrapper for OpenCode CLI (opencode run --format json)
 Project-URL: Homepage, https://github.com/idailylife/oc_py_wrapper
 Project-URL: Repository, https://github.com/idailylife/oc_py_wrapper
@@ -77,17 +77,21 @@ async def main():
 asyncio.run(main())
 ```
 
-Set `RunConfig(record_thinking=True)` when you want OpenCode reasoning/thinking
-parts included in `result.events` and `log_file` JSON lines. This only maps to
-OpenCode's display/output flag `--thinking`; it does not change model reasoning
-effort. Use `variant` separately if you intentionally want a provider-specific
-reasoning effort.
+Set `RunConfig(cli_kwargs={"thinking": True})` when you want OpenCode
+reasoning/thinking parts included in `result.events` and `log_file` JSON lines in
+**run mode**. This maps to OpenCode's display/output flag `--thinking`; it does
+not change model reasoning effort. In **server/session mode** there is no
+`--thinking` equivalent — reasoning parts are produced per the model's reasoning
+config and streamed onto the SSE bus unconditionally, so they already land in
+`result.events` / `log_file` with no opt-in.
 
 ### Multi-turn conversation (`OpenCodeSession`)
 
-For a stateful, multi-turn chat over a single opencode session, use
-`OpenCodeSession` as an async context manager. Each `send()` continues the same
-session, so the model retains context across turns:
+For a stateful, multi-turn chat, use `OpenCodeSession` as an async context
+manager. Unlike the one-shot `async_run`/`async_stream` (which spawn
+`opencode run` per call), a session owns a headless `opencode serve` process for
+the duration of the `async with` block and re-prompts one server-side session, so
+the model retains context **natively** across turns:
 
 ```python
 import asyncio
@@ -97,19 +101,65 @@ async def chat():
     client = AsyncOpenCodeClient()
     async with OpenCodeSession(client, ".", run_cfg=RunConfig(model="opencode/big-pickle")) as s:
         r1 = await s.send("My name is Bob.")
-        r2 = await s.send("What is my name?")   # auto-continues → "Bob"
+        r2 = await s.send("What is my name?")   # continues natively → "Bob"
         print(s.session_id, r2.final_text)
 
 asyncio.run(chat())
 ```
 
-On enter, the session allocates a private, persistent `XDG_DATA_HOME` tmpdir that
-every turn reuses, so opencode's SQLite session DB survives across turns. The
-first `send()` creates the session (its id is captured on `RunResult.session_id`);
-later turns continue it via `--session <id>`. Each session is an isolated island —
-no shared global DB, so no cross-session lock contention — and the tmpdir is
-removed when the `async with` block exits. `send()` accepts per-turn `run_cfg` and
-`timeout_s` overrides.
+On enter, the session spawns `opencode serve` (with the same hermetic isolation
+run mode uses) and creates one session pinned to the workspace; on exit the
+session is deleted and the server torn down. `send()` accepts per-turn `run_cfg`
+and `timeout_s` overrides, but only **prompt-body knobs** (`model` / `agent` /
+`tools`) vary per turn — `permission` / `mcp` / `instructions` are fixed at enter
+(they are server-global).
+
+#### Human-in-the-loop permissions
+
+Because the server can pause on a permission request, sessions support an
+`on_permission` async callback that run mode cannot. Set `permission={"bash":
+"ask"}` and answer each prompt with `"once"` / `"always"` / `"reject"`:
+
+```python
+async def approve(props):    # props: {"id", "sessionID", "permission", ...}
+    return "once"
+
+async with OpenCodeSession(client, ".", run_cfg=RunConfig(permission={"bash": "ask"}),
+                           on_permission=approve) as s:
+    r = await s.send("Run `echo hi` and tell me the output.")
+```
+
+When `on_permission` is `None` (the default), any `permission.asked` is
+auto-rejected so a turn never blocks. File attachments are run-mode only — pass
+`RunConfig(cli_kwargs={"f": ["a.txt", "b.png"]})` to `async_run`. Server-mode
+sessions ignore `cli_kwargs`, so embed file content in the prompt instead.
+
+#### Answering the model's questions
+
+opencode's built-in `question` tool lets the model ask the user multiple-choice
+questions mid-run (gather preferences, clarify, offer choices). Pass an
+`on_question` async callback to answer it. The callback receives the question
+props (`{"id", "sessionID", "questions": [{"question", "header", "options":
+[{"label", "description"}], "multiple"?, "custom"?}], ...}`) and returns a list
+with one entry per question — each a list of selected option labels. Returning
+`None` rejects (dismisses) the question.
+
+```python
+async def answer(props):
+    out = []
+    for q in props["questions"]:
+        out.append([q["options"][0]["label"]])   # pick the first option
+    return out
+
+async with OpenCodeSession(client, ".", run_cfg=RunConfig(model="opencode/big-pickle"),
+                           on_question=answer) as s:
+    r = await s.send("Ask me which database to use, then scaffold it.")
+```
+
+When `on_question` is `None` (the default), any `question.asked` is auto-rejected
+so a turn never blocks. The `question` tool is enabled by default under
+`opencode serve`; set `RunConfig(extra_env={"OPENCODE_ENABLE_QUESTION_TOOL": "1"})`
+to force-enable it regardless of the server's client identity.
 
 ### Stream structured JSON events
 
@@ -175,7 +225,23 @@ host OpenCode config as-is. For reproducible runs, pass `model`, `permission`,
 
 ## CLI arguments
 
-`RunConfig` maps to flags such as `--agent`, `-m`, `-f`, `--attach`, `--title`, etc. Prompt text is appended as the final `opencode run` message argument.
+In run mode, `model` and `agent` map to `-m` and `--agent`. Every other
+`opencode run` flag is passed through `RunConfig.cli_kwargs`, a raw dict expanded
+by `build_argv`:
+
+- bool `True` → `--flag` (e.g. `{"fork": True}` → `--fork`)
+- a value → `--flag=value` (e.g. `{"title": "demo"}` → `--title=demo`)
+- a single-char key → `-k value` (e.g. `{"f": "a.txt"}` → `-f a.txt`)
+- a list/tuple → repeated (e.g. `{"f": ["a.txt", "b.txt"]}` → `-f a.txt -f b.txt`)
+- `False` / `None` → skipped
+
+```python
+RunConfig(model="anthropic/claude", cli_kwargs={"fork": True, "title": "demo", "f": ["a.txt"]})
+# -> opencode run --format json -m anthropic/claude --fork --title=demo -f a.txt <prompt>
+```
+
+Prompt text is appended as the final `opencode run` message argument.
+`cli_kwargs` is ignored by `OpenCodeSession` (server mode has no CLI surface).
 
 ## Tests
 
@@ -220,7 +286,7 @@ The defaults already handle the common pitfalls when running many `async_run` ca
 
 To opt out: pass `startup_delay_s=0` (and a large `startup_concurrency`) to drop the startup pacing, `isolate_db=False` to share session history across runs, and `max_retries=0` to disable retries.
 
-> For **multi-turn conversations** you don't need `isolate_db=False`. Use [`OpenCodeSession`](#multi-turn-conversation-opencodesession) instead — it keeps one session's DB alive across turns in a private dir, so context is preserved without sharing the global DB.
+> These notes apply to `async_run` / `async_stream` (run mode). For **multi-turn conversations** use [`OpenCodeSession`](#multi-turn-conversation-opencodesession) instead — it runs `opencode serve` and re-prompts one server-side session, so context is preserved natively with no shared-DB contention.
 
 ## Notes
 

py_opencode_wrapper-0.3.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+opencode_wrapper/__init__.py,sha256=JPLA98Oj2WZxGl_KyWozRFs0Q-uG2C6x4ccqy2NnBWo,1290
+opencode_wrapper/client.py,sha256=8WbFcodbZ_TA3cglmz9JmUwtvrUIECzzPhysQ49VJBs,20082
+opencode_wrapper/config.py,sha256=js3QBe7ZRhCSXC4PVvXpVOrS9UNqn6eYwg7psijZIlg,9320
+opencode_wrapper/errors.py,sha256=zaXzzFb6ObdrNlm-PJE_7tbgvMEhoZcbeQVWNHNTkUQ,1168
+opencode_wrapper/events.py,sha256=09JwXeK5Qr4lSSDW7CSluc8SsrGIoPIJNCrH-MXyk2U,11892
+opencode_wrapper/server.py,sha256=4suv2eOZ95SVD9aa8tKcGjghAFK5isp5o82lnmb81mI,10247
+opencode_wrapper/session.py,sha256=0GDobxQZZgnUCpZUJmjNnVMUJ-nw9c11Z8eJZhA5hPE,11658
+py_opencode_wrapper-0.3.1.dist-info/licenses/LICENSE,sha256=W9SvvGfo_x1O5jNp-vV1NzRrMGB5C6sjHnQDnGm73qg,1067
+py_opencode_wrapper-0.3.1.dist-info/METADATA,sha256=7BQF7uwAz1ZMWmpXFwhWshkWJS2bEVp_roZs_NdcECA,12112
+py_opencode_wrapper-0.3.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+py_opencode_wrapper-0.3.1.dist-info/top_level.txt,sha256=8LETj5bPgl1YnB83iOiueuQvGryj3RzaeEQecPVS9Q8,17
+py_opencode_wrapper-0.3.1.dist-info/RECORD,,

py_opencode_wrapper-0.3.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-opencode_wrapper/__init__.py,sha256=zX72bGTjtcDDm-lL3JZHj-IiVAHjsFO7uldQ6Up7w3U,1089
-opencode_wrapper/client.py,sha256=T-L9Ubz1FtIfueix9fbg_G7cTs4tWhvLd6xKP58JHrk,20180
-opencode_wrapper/config.py,sha256=TGQ85vd06qQPbP02G6YG9re-rESpYHfhAJ8PaAUqHRg,8076
-opencode_wrapper/errors.py,sha256=zaXzzFb6ObdrNlm-PJE_7tbgvMEhoZcbeQVWNHNTkUQ,1168
-opencode_wrapper/events.py,sha256=x6KcHXB8vLHB5mesMkGxx5QxiaPQOfI-ponwAufcnlg,6896
-opencode_wrapper/session.py,sha256=_weqUbbs2ul5568b086JEBqK7Ni2ehwc6p6-nQFuz1g,3096
-py_opencode_wrapper-0.3.0.dist-info/licenses/LICENSE,sha256=W9SvvGfo_x1O5jNp-vV1NzRrMGB5C6sjHnQDnGm73qg,1067
-py_opencode_wrapper-0.3.0.dist-info/METADATA,sha256=AQoxbJpt1ghHtsxmjXhsQwD3VX7v9hext_uy5dLflDQ,9001
-py_opencode_wrapper-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-py_opencode_wrapper-0.3.0.dist-info/top_level.txt,sha256=8LETj5bPgl1YnB83iOiueuQvGryj3RzaeEQecPVS9Q8,17
-py_opencode_wrapper-0.3.0.dist-info/RECORD,,