py-opencode-wrapper 0.1.2__py3-none-any.whl

opencode_wrapper/__init__.py

@@ -0,0 +1,38 @@
+"""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.errors import (
+    OpenCodeBinaryNotFoundError,
+    OpenCodeCancelledError,
+    OpenCodeError,
+    OpenCodeProcessError,
+    OpenCodeTimeoutError,
+)
+from opencode_wrapper.events import (
+    RunResult,
+    TokenUsage,
+    aggregate_run_result,
+    parse_event_line,
+    run_result_fuzzy_text,
+)
+
+__all__ = [
+    "AsyncOpenCodeClient",
+    "RunConfig",
+    "RunResult",
+    "TokenUsage",
+    "aggregate_run_result",
+    "build_argv",
+    "build_env",
+    "parse_event_line",
+    "run_result_fuzzy_text",
+    "resolve_binary",
+    "validate_config_for_run",
+    "validate_permission_actions",
+    "OpenCodeError",
+    "OpenCodeBinaryNotFoundError",
+    "OpenCodeProcessError",
+    "OpenCodeTimeoutError",
+    "OpenCodeCancelledError",
+]

opencode_wrapper/client.py

@@ -0,0 +1,382 @@
+"""Async client: spawn ``opencode run --format json`` and stream parsed events."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+import tempfile
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, AsyncIterator, Mapping
+
+from opencode_wrapper.config import RunConfig, validate_config_for_run
+from opencode_wrapper.errors import (
+    OpenCodeBinaryNotFoundError,
+    OpenCodeProcessError,
+    OpenCodeTimeoutError,
+)
+from opencode_wrapper.events import RunResult, aggregate_run_result, parse_event_line
+
+
+def resolve_binary(binary: str) -> str:
+    """Resolve ``binary`` to an executable path."""
+    expanded = Path(binary).expanduser()
+    if expanded.is_file():
+        return str(expanded)
+    found = shutil.which(binary)
+    if found:
+        return found
+    raise OpenCodeBinaryNotFoundError(f"OpenCode binary not found: {binary!r}")
+
+
+def build_argv(
+    binary_resolved: str,
+    prompt: str,
+    run_cfg: RunConfig,
+) -> list[str]:
+    """Build ``opencode run`` argument list."""
+    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.thinking is True:
+        cmd.append("--thinking")
+
+    if prompt:
+        cmd.append(prompt)
+    return cmd
+
+
+def build_env(run_cfg: RunConfig, base: Mapping[str, str] | None = None) -> dict[str, str]:
+    env = dict(base if base is not None else os.environ)
+    if run_cfg.extra_env:
+        env.update(dict(run_cfg.extra_env))
+    content = run_cfg.opencode_config_content_json()
+    if content is not None:
+        env["OPENCODE_CONFIG_CONTENT"] = content
+    if run_cfg.disable_autoupdate:
+        env["OPENCODE_DISABLE_AUTOUPDATE"] = "1"
+    return env
+
+
+async def _readline_unlimited(reader: asyncio.StreamReader) -> bytes:
+    """readline with no size limit, works around asyncio's default 64 KiB cap.
+
+    Uses ``readuntil()`` directly instead of ``readline()``: unlike ``readline()``,
+    ``readuntil()`` raises ``LimitOverrunError`` *without* clearing the buffer, so
+    we can drain the oversized chunk with ``readexactly()`` and keep looping.
+    """
+    chunks: list[bytes] = []
+    while True:
+        try:
+            chunk = await reader.readuntil(b"\n")
+            if chunks:
+                chunks.append(chunk)
+                return b"".join(chunks)
+            return chunk
+        except asyncio.IncompleteReadError as exc:
+            # EOF reached before newline — return whatever partial data we have
+            if chunks:
+                chunks.append(exc.partial)
+                return b"".join(chunks)
+            return exc.partial
+        except asyncio.LimitOverrunError as exc:
+            # Buffer limit hit but data is still intact; drain consumed bytes and loop
+            chunks.append(bytes(await reader.readexactly(exc.consumed)))
+
+
+async def _drain_stderr(proc: asyncio.subprocess.Process, out: list[str]) -> None:
+    if proc.stderr is None:
+        return
+    while True:
+        chunk = await _readline_unlimited(proc.stderr)
+        if not chunk:
+            break
+        out.append(chunk.decode(errors="replace"))
+
+
+async def _stdout_line_event_iter(
+    proc: asyncio.subprocess.Process,
+) -> AsyncIterator[tuple[str, dict[str, Any]]]:
+    if proc.stdout is None:
+        return
+    while True:
+        line_b = await _readline_unlimited(proc.stdout)
+        if not line_b:
+            break
+        line = line_b.decode(errors="replace")
+        yield line, parse_event_line(line)
+
+
+# Substrings that indicate opencode crashed during SQLite WAL initialisation.
+# This happens when multiple instances race to set journal_mode=WAL before
+# busy_timeout is configured (opencode bug: busy_timeout set after WAL pragma).
+_SQLITE_STARTUP_PATTERNS: tuple[str, ...] = (
+    "database is locked",
+    "sqlite_busy",
+    "sqliteerror",
+    "journal_mode",
+    "disk i/o error",
+)
+
+
+def _is_sqlite_startup_error(stderr: str) -> bool:
+    """Return True when *stderr* looks like an opencode SQLite initialisation crash."""
+    lower = stderr.lower()
+    return any(pat in lower for pat in _SQLITE_STARTUP_PATTERNS)
+
+
+class AsyncOpenCodeClient:
+    """
+    One-shot async wrapper around the OpenCode CLI.
+
+    Uses ``opencode run --format json`` with optional ``OPENCODE_CONFIG_CONTENT``.
+
+    Parameters
+    ----------
+    startup_concurrency:
+        Maximum number of opencode processes that may enter their SQLite
+        initialisation window simultaneously.  Defaults to ``1`` (serialised
+        startup) to avoid the WAL-pragma race that crashes concurrent instances.
+    startup_delay_s:
+        Seconds to hold the startup semaphore *after* the process is spawned,
+        giving SQLite time to finish ``PRAGMA journal_mode = WAL`` before the
+        next instance starts.  Defaults to ``0.3``.
+    isolate_db:
+        If ``True`` (default), each run gets a private ``XDG_DATA_HOME`` temp
+        directory so opencode stores its SQLite database in isolation.  Without
+        this, concurrent processes share ``~/.local/share/opencode/opencode.db``
+        and SQLite write locks during tool execution serialize otherwise-parallel
+        runs (observed 37–46 s delays).  Set to ``False`` only if you need runs
+        to share session history.
+    """
+
+    def __init__(
+        self,
+        binary: str = "opencode",
+        startup_concurrency: int = 1,
+        startup_delay_s: float = 0.3,
+        isolate_db: bool = True,
+    ) -> None:
+        self.binary = binary
+        self._resolved_binary: str | None = None
+        self._startup_sem = asyncio.Semaphore(startup_concurrency)
+        self._startup_delay_s = startup_delay_s
+        self._isolate_db = isolate_db
+
+    def resolved_binary(self) -> str:
+        if self._resolved_binary is None:
+            self._resolved_binary = resolve_binary(self.binary)
+        return self._resolved_binary
+
+    @asynccontextmanager
+    async def _managed_process(
+        self,
+        argv: list[str],
+        cwd: str,
+        env: dict[str, str],
+    ) -> AsyncIterator[tuple[asyncio.subprocess.Process, list[str]]]:
+        stderr_lines: 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_")
+            env = {**env, "XDG_DATA_HOME": xdg_tmpdir}
+        else:
+            xdg_tmpdir = None
+        # Serialise process startup to avoid the SQLite WAL-pragma race.
+        # The semaphore is released as soon as the startup window has elapsed,
+        # so all processes run concurrently after their individual delay.
+        async with self._startup_sem:
+            proc = await asyncio.create_subprocess_exec(
+                *argv,
+                cwd=cwd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=env,
+            )
+            if self._startup_delay_s > 0:
+                await asyncio.sleep(self._startup_delay_s)
+        stderr_task = asyncio.create_task(_drain_stderr(proc, stderr_lines))
+        try:
+            yield proc, stderr_lines
+        except asyncio.CancelledError:
+            if proc.returncode is None:
+                try:
+                    proc.kill()
+                except ProcessLookupError:
+                    pass
+            raise
+        finally:
+            # Natural completion: child usually still has returncode=None until wait().
+            await proc.wait()
+            try:
+                await stderr_task
+            except asyncio.CancelledError:
+                pass
+            if xdg_tmpdir is not None:
+                shutil.rmtree(xdg_tmpdir, ignore_errors=True)
+
+    async def async_stream(
+        self,
+        prompt: str,
+        workspace: str | Path,
+        *,
+        run_cfg: RunConfig | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """
+        Yield parsed JSON event dicts from stdout.
+
+        After the stream completes successfully, returns normally.
+        On non-zero exit, raises :class:`OpenCodeProcessError` (after all lines are yielded).
+        """
+        run_cfg = run_cfg or RunConfig()
+        validate_config_for_run(run_cfg)
+        bin_path = self.resolved_binary()
+        argv = build_argv(bin_path, prompt, run_cfg)
+        env = build_env(run_cfg)
+        cwd = str(Path(workspace).expanduser().resolve())
+
+        events_acc: list[dict[str, Any]] = []
+        raw_acc: list[str] = []
+
+        async with self._managed_process(argv, cwd, env) as (proc, stderr_lines):
+            async for line, ev in _stdout_line_event_iter(proc):
+                raw_acc.append(line)
+                events_acc.append(ev)
+                yield ev
+
+        code = proc.returncode if proc.returncode is not None else -1
+        stderr = "".join(stderr_lines)
+        if code != 0:
+            raise OpenCodeProcessError(
+                exit_code=code,
+                stderr=stderr,
+                events=events_acc,
+                raw_stdout_lines=raw_acc,
+            )
+
+    async def async_run(
+        self,
+        prompt: str,
+        workspace: str | Path,
+        *,
+        run_cfg: RunConfig | None = None,
+        timeout_s: float | None = None,
+        log_file: str | Path | None = None,
+        max_retries: int = 2,
+        retry_delay_s: float = 1.0,
+    ) -> RunResult:
+        """
+        Run to completion and return a :class:`RunResult`.
+
+        If ``log_file`` is given, each event dict is appended as a JSON line
+        during execution (flushed immediately), so partial progress survives
+        crashes.
+
+        Raises :class:`OpenCodeTimeoutError` if ``timeout_s`` elapses.
+
+        Parameters
+        ----------
+        max_retries:
+            Number of additional attempts when opencode crashes during SQLite
+            startup (WAL-pragma race).  Set to ``0`` to disable retry.
+        retry_delay_s:
+            Seconds to wait between retry attempts.
+        """
+        run_cfg = run_cfg or RunConfig()
+
+        async def _inner() -> RunResult:
+            validate_config_for_run(run_cfg)
+            bin_path = self.resolved_binary()
+            argv = build_argv(bin_path, prompt, run_cfg)
+            env = build_env(run_cfg)
+            cwd = str(Path(workspace).expanduser().resolve())
+
+            events_acc: list[dict[str, Any]] = []
+            raw_acc: list[str] = []
+
+            log_fh = open(log_file, "w") if log_file is not None else None
+            try:
+                async with self._managed_process(argv, cwd, env) as (proc, stderr_lines):
+                    async for line, ev in _stdout_line_event_iter(proc):
+                        raw_acc.append(line)
+                        events_acc.append(ev)
+                        if log_fh is not None:
+                            log_fh.write(json.dumps(ev, ensure_ascii=False) + "\n")
+                            log_fh.flush()
+            finally:
+                if log_fh is not None:
+                    log_fh.close()
+
+            code = proc.returncode if proc.returncode is not None else -1
+            stderr = "".join(stderr_lines)
+            if code != 0:
+                raise OpenCodeProcessError(
+                    exit_code=code,
+                    stderr=stderr,
+                    events=events_acc,
+                    raw_stdout_lines=raw_acc,
+                )
+            return aggregate_run_result(
+                events=events_acc,
+                raw_stdout_lines=raw_acc,
+                exit_code=code,
+                stderr=stderr,
+            )
+
+        async def _run_with_retries() -> RunResult:
+            last_exc: OpenCodeProcessError | None = None
+            for attempt in range(1 + max_retries):
+                if attempt > 0:
+                    await asyncio.sleep(retry_delay_s)
+                try:
+                    return await _inner()
+                except OpenCodeProcessError as exc:
+                    if attempt < max_retries and _is_sqlite_startup_error(exc.stderr):
+                        last_exc = exc
+                        continue
+                    raise
+            raise last_exc  # type: ignore[misc]  # unreachable; satisfies type checker
+
+        if timeout_s is not None:
+            try:
+                return await asyncio.wait_for(_run_with_retries(), timeout=timeout_s)
+            except asyncio.TimeoutError as e:
+                raise OpenCodeTimeoutError(
+                    f"OpenCode run exceeded timeout_s={timeout_s!r}"
+                ) from e
+        return await _run_with_retries()

opencode_wrapper/config.py

@@ -0,0 +1,109 @@
+"""Runtime config merge for ``OPENCODE_CONFIG_CONTENT`` and CLI flags."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+# Permission values accepted by OpenCode
+PermissionAction = str  # "allow" | "ask" | "deny"
+
+# Nested permission maps: tool name -> action or pattern -> action
+PermissionMap = dict[str, Any]
+
+
+def _deep_merge(base: dict[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for k, v in override.items():
+        if isinstance(v, Mapping) and not isinstance(v, (str, bytes, bytearray)):
+            existing = out.get(k)
+            if isinstance(existing, dict):
+                out[k] = _deep_merge(existing, dict(v))
+            else:
+                out[k] = _deep_merge({}, dict(v))
+        else:
+            out[k] = v
+    return out
+
+
+@dataclass
+class RunConfig:
+    """Per-invocation settings merged into env and CLI."""
+
+    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
+    thinking: bool | None = None
+    print_logs: bool | None = None
+    log_level: str | None = None
+    disable_autoupdate: bool = True
+    extra_env: Mapping[str, str] | None = None
+    # Injected as JSON via OPENCODE_CONFIG_CONTENT (merged with config_overrides)
+    permission: PermissionMap | None = None
+    mcp: dict[str, Any] | None = None
+    tools: dict[str, Any] | None = None
+    config_overrides: dict[str, Any] | None = None
+
+    def build_opencode_config_dict(self) -> dict[str, Any]:
+        """Build the dict serialized to ``OPENCODE_CONFIG_CONTENT``."""
+        merged: dict[str, Any] = {}
+        if self.config_overrides:
+            merged = _deep_merge(merged, self.config_overrides)
+        if self.permission is not None:
+            merged = _deep_merge(merged, {"permission": dict(self.permission)})
+        if self.mcp is not None:
+            merged = _deep_merge(merged, {"mcp": dict(self.mcp)})
+        if self.tools is not None:
+            merged = _deep_merge(merged, {"tools": dict(self.tools)})
+        return merged
+
+    def opencode_config_content_json(self) -> str | None:
+        cfg = self.build_opencode_config_dict()
+        if not cfg:
+            return None
+        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.
+
+    ``"ask"`` is rejected because the subprocess has no terminal to prompt —
+    it would block forever.
+    """
+    allowed = frozenset({"allow", "deny"})
+    if isinstance(obj, str):
+        if obj == "ask":
+            loc = f" at {_path!r}" if _path else ""
+            raise ValueError(
+                f"Permission action 'ask' is not supported in non-interactive "
+                f"subprocess mode{loc}; use 'allow' or 'deny' instead"
+            )
+        if obj not in allowed:
+            raise ValueError(
+                f"Invalid permission action {obj!r}{' at ' + repr(_path) if _path else ''}; "
+                f"expected one of {sorted(allowed)}"
+            )
+        return
+    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)
+
+
+def validate_config_for_run(cfg: RunConfig) -> None:
+    """Strict checks before spawning."""
+    if cfg.permission is not None:
+        validate_permission_actions(cfg.permission)

opencode_wrapper/errors.py

@@ -0,0 +1,39 @@
+"""Exceptions raised by the OpenCode async client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class OpenCodeError(Exception):
+    """Base error for OpenCode wrapper operations."""
+
+
+class OpenCodeBinaryNotFoundError(OpenCodeError):
+    """The configured OpenCode executable path does not exist or is not a file."""
+
+
+@dataclass
+class OpenCodeProcessError(OpenCodeError):
+    """``opencode`` exited with a non-zero status or was killed."""
+
+    exit_code: int | None
+    stderr: str
+    events: list[dict[str, Any]] = field(default_factory=list)
+    raw_stdout_lines: list[str] = field(default_factory=list)
+
+    def __str__(self) -> str:
+        parts = [f"opencode exited with code {self.exit_code!r}"]
+        if self.stderr.strip():
+            tail = self.stderr.strip()[-2000:]
+            parts.append(f"stderr (tail):\n{tail}")
+        return "\n".join(parts)
+
+
+class OpenCodeTimeoutError(OpenCodeError):
+    """The OpenCode subprocess did not finish within the configured timeout."""
+
+
+class OpenCodeCancelledError(OpenCodeError):
+    """The run was cancelled (e.g. asyncio task cancellation)."""

opencode_wrapper/events.py

@@ -0,0 +1,192 @@
+"""Parse ``opencode run --format json`` stdout lines and aggregate ``RunResult``."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+
+
+def parse_event_line(line: str) -> dict[str, Any]:
+    """
+    Parse one stdout line into an event dict.
+
+    Non-JSON lines become a ``diagnostic`` event so the stream never breaks.
+    """
+    stripped = line.strip()
+    if not stripped:
+        return {"type": "diagnostic", "kind": "empty_line", "raw": line}
+    try:
+        obj = json.loads(stripped)
+        if isinstance(obj, dict):
+            return obj
+        return {"type": "diagnostic", "kind": "non_object_json", "value": obj}
+    except json.JSONDecodeError as e:
+        return {
+            "type": "diagnostic",
+            "kind": "json_decode_error",
+            "raw": stripped,
+            "error": str(e),
+        }
+
+
+def iter_parse_lines(lines: Iterator[str]) -> Iterator[dict[str, Any]]:
+    for line in lines:
+        yield parse_event_line(line)
+
+
+def _text_from_event(ev: dict[str, Any]) -> str | None:
+    t = ev.get("type")
+    if t == "text":
+        # OpenCode nested: {"type":"text","part":{"type":"text","text":"..."}}
+        part = ev.get("part")
+        if isinstance(part, dict) and isinstance(part.get("text"), str):
+            return part["text"]
+        # Flat shapes: {"type":"text","content":"..."} or {"text":"..."}
+        if "content" in ev and isinstance(ev["content"], str):
+            return ev["content"]
+        if "text" in ev and isinstance(ev["text"], str):
+            return ev["text"]
+        if "delta" in ev and isinstance(ev["delta"], str):
+            return ev["delta"]
+    if t in ("message", "assistant", "model"):
+        content = ev.get("content")
+        if isinstance(content, str):
+            return content
+    # OpenCode / provider streaming: content as list of parts
+    content = ev.get("content")
+    if isinstance(content, list):
+        parts: list[str] = []
+        for part in content:
+            if isinstance(part, dict):
+                if isinstance(part.get("text"), str):
+                    parts.append(part["text"])
+                elif isinstance(part.get("content"), str):
+                    parts.append(part["content"])
+            elif isinstance(part, str):
+                parts.append(part)
+        if parts:
+            return "".join(parts)
+    return None
+
+
+def run_result_fuzzy_text(result: "RunResult") -> str:
+    """
+    Best-effort extract human-visible model output across varying ``--format json`` shapes.
+
+    Uses :attr:`RunResult.final_text` when non-empty; otherwise scans events and raw lines.
+    """
+    if (result.final_text or "").strip():
+        return result.final_text.strip()
+    pieces: list[str] = []
+    for ev in result.events:
+        if ev.get("type") == "diagnostic":
+            continue
+        chunk = _text_from_event(ev)
+        if chunk and chunk.strip():
+            pieces.append(chunk.strip())
+            continue
+        for key in ("content", "text", "delta", "output", "message", "result", "value"):
+            val = ev.get(key)
+            if isinstance(val, str) and val.strip():
+                pieces.append(val.strip())
+        msg = ev.get("message")
+        if isinstance(msg, dict):
+            for key in ("content", "text"):
+                v = msg.get(key)
+                if isinstance(v, str) and v.strip():
+                    pieces.append(v.strip())
+    if pieces:
+        return "\n".join(pieces).strip()
+    raw = "\n".join(x.strip() for x in result.raw_stdout_lines if x.strip())
+    return raw.strip()
+
+
+def _tool_summary(ev: dict[str, Any]) -> dict[str, Any] | None:
+    t = ev.get("type")
+    if t in ("tool_use", "tool_call", "tool_result", "tool"):
+        return {k: v for k, v in ev.items() if k != "type"} | {"type": t}
+    if t == "step_finish" and "tool" in ev:
+        return {"type": "step_tool", "payload": ev.get("tool")}
+    return None
+
+
+@dataclass
+class TokenUsage:
+    """Aggregated token counts across all steps."""
+
+    total: int = 0
+    input: int = 0
+    output: int = 0
+    reasoning: int = 0
+    cache_read: int = 0
+    cache_write: int = 0
+
+
+@dataclass
+class RunResult:
+    """Aggregated outcome of a completed ``opencode run``."""
+
+    events: list[dict[str, Any]] = field(default_factory=list)
+    final_text: str = ""
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    exit_code: int | None = None
+    stderr: str = ""
+    raw_stdout_lines: list[str] = field(default_factory=list)
+    token_usage: TokenUsage = field(default_factory=TokenUsage)
+    total_cost: float = 0.0
+    turns: int = 0
+
+    def append_event(self, ev: dict[str, Any]) -> None:
+        self.events.append(ev)
+        chunk = _text_from_event(ev)
+        if chunk:
+            self.final_text += chunk
+        tool = _tool_summary(ev)
+        if tool is not None:
+            self.tool_calls.append(tool)
+        if ev.get("type") == "step_finish":
+            self._accumulate_step(ev)
+
+    def _accumulate_step(self, ev: dict[str, Any]) -> None:
+        """Extract cost/token/turn info from a ``step_finish`` event."""
+        part = ev.get("part") or ev
+        cost = part.get("cost")
+        if isinstance(cost, (int, float)):
+            self.total_cost += cost
+        tokens = part.get("tokens")
+        if isinstance(tokens, dict):
+            u = self.token_usage
+            for attr, key in (
+                ("total", "total"),
+                ("input", "input"),
+                ("output", "output"),
+                ("reasoning", "reasoning"),
+            ):
+                val = tokens.get(key)
+                if isinstance(val, (int, float)):
+                    setattr(u, attr, getattr(u, 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(u, attr, getattr(u, attr) + int(val))
+        self.turns += 1
+
+
+def aggregate_run_result(
+    *,
+    events: list[dict[str, Any]],
+    raw_stdout_lines: list[str],
+    exit_code: int | None,
+    stderr: str,
+) -> RunResult:
+    r = RunResult(
+        raw_stdout_lines=list(raw_stdout_lines),
+        exit_code=exit_code,
+        stderr=stderr,
+    )
+    for ev in events:
+        r.append_event(ev)
+    return r

py_opencode_wrapper-0.1.2.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: py-opencode-wrapper
+Version: 0.1.2
+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
+Project-URL: Issues, https://github.com/idailylife/oc_py_wrapper/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+
+# oc-py-harness
+
+Python **async** wrapper around the [OpenCode](https://opencode.ai/docs/) CLI (`opencode run --format json`). Intended as a subprocess-based executor for **multi-agent workflow** orchestration.
+
+## Requirements
+
+- Python 3.10+
+- `opencode` on `PATH` (or pass an absolute path to the binary)
+
+## Install (local tree)
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### One-shot run with aggregated result
+
+```python
+import asyncio
+from pathlib import Path
+
+from opencode_wrapper import AsyncOpenCodeClient, RunConfig
+
+async def main():
+    client = AsyncOpenCodeClient("opencode")
+    cfg = RunConfig(
+        model="anthropic/claude-sonnet-4-5",
+        agent="plan",
+        permission={"bash": "deny", "edit": "deny"},
+        mcp={
+            "demo": {
+                "type": "local",
+                "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
+                "enabled": True,
+            }
+        },
+    )
+    result = await client.async_run(
+        "Summarize the README in one sentence.",
+        Path("/path/to/repo"),
+        run_cfg=cfg,
+        timeout_s=600,
+    )
+    print(result.exit_code, result.final_text)
+
+asyncio.run(main())
+```
+
+### Stream structured JSON events
+
+```python
+async def stream_example():
+    client = AsyncOpenCodeClient()
+    cfg = RunConfig(permission={"*": "allow"})
+    async for event in client.async_stream("List top-level files.", workspace=".", run_cfg=cfg):
+        print(event)
+```
+
+### Parallel agents (`asyncio.gather`)
+
+```python
+async def multi():
+    # startup_concurrency=1 serialises SQLite initialisation to avoid a known
+    # WAL-pragma race in opencode when many instances start simultaneously.
+    # startup_delay_s controls how long each slot is held before the next
+    # process is allowed to start (default 0.3 s).
+    client = AsyncOpenCodeClient(startup_concurrency=1, startup_delay_s=0.3)
+    ws = Path("/path/to/monorepo")
+    results = await asyncio.gather(*[
+        client.async_run(
+            f"Explain services/{svc}.",
+            ws / "services" / svc,
+            run_cfg=RunConfig(agent="explore"),
+            timeout_s=600,
+            # max_retries=2 (default): retry automatically if opencode crashes
+            # during SQLite startup before giving up.
+        )
+        for svc in ["api", "worker", "gateway"]
+    ])
+    return results
+```
+
+## Configuration injection
+
+Per-call JSON is merged and passed as `OPENCODE_CONFIG_CONTENT` (see [OpenCode config](https://opencode.ai/docs/config/)). Use `RunConfig` fields:
+
+| Field | Purpose |
+|--------|---------|
+| `permission` | `permission` map (`allow` / `ask` / `deny`, patterns) |
+| `mcp` | MCP server definitions |
+| `tools` | Enable/disable tools (including MCP globs) |
+| `config_overrides` | Any extra top-level config keys to deep-merge |
+
+Optional env tuning: `disable_autoupdate=True` sets `OPENCODE_DISABLE_AUTOUPDATE=1`.
+
+## 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.
+
+## Tests
+
+Unit tests (no real OpenCode / no API calls):
+
+```bash
+pytest -q -m "not integration"
+```
+
+Integration tests (real `opencode run`, needs working provider auth — **slow**, may incur API usage):
+
+```bash
+pytest -m integration -q tests/test_integration_opencode.py
+```
+
+**Multi-agent weather workflow** (10 parallel city lookups + 1 summary — **11 API calls**, not run by default):
+
+```bash
+OPENCODE_MULTI_AGENT_WEATHER=1 pytest -m integration -v tests/test_integration_multi_agent_weather.py
+```
+
+Optional: `OPENCODE_WEATHER_SEQUENTIAL=1` runs the 10 city calls one-by-one (easier on rate limits).  
+Per-stage timeouts: `OPENCODE_WEATHER_PER_CITY_TIMEOUT_S`, `OPENCODE_WEATHER_SUMMARY_TIMEOUT_S` (default: same as `OPENCODE_INTEGRATION_TIMEOUT_S`).
+
+| Env | Meaning |
+|-----|--------|
+| `OPENCODE_BINARY` | Absolute path to `opencode` if not on `PATH` |
+| `OPENCODE_INTEGRATION=0` | Skip integration tests |
+| `OPENCODE_INTEGRATION_TIMEOUT_S` | Per-test timeout seconds (default `300`) |
+| `OPENCODE_MULTI_AGENT_WEATHER=1` | Enable 11-call weather integration test |
+| `OPENCODE_ENABLE_EXA` | Passed through / defaulted to `1` in that test for web search tools |
+
+Default `pytest -q` runs **all** tests; use `-m "not integration"` in CI without OpenCode.
+
+## Concurrency notes
+
+When running many tasks with `asyncio.gather`, two mitigations are active by default:
+
+**Startup serialisation** — `AsyncOpenCodeClient` accepts `startup_concurrency` (default `1`) and `startup_delay_s` (default `0.3`). Only one process at a time enters its SQLite initialisation window; all processes run concurrently afterwards. This avoids a known opencode bug where `PRAGMA journal_mode = WAL` races against `PRAGMA busy_timeout` during concurrent startup, causing immediate crashes.
+
+**Automatic retry** — `async_run` accepts `max_retries` (default `2`) and `retry_delay_s` (default `1.0`). If opencode exits non-zero and stderr contains SQLite lock indicators, the call is retried with a short backoff. Non-SQLite failures are raised immediately.
+
+Set `startup_concurrency=0` (unlimited) and `max_retries=0` to opt out of both behaviours.
+
+## Notes
+
+- Event shapes from `--format json` may change between OpenCode versions; unknown fields are preserved in each parsed dict.
+- For fully non-interactive automation, prefer explicit `permission` (`allow`/`deny`) over relying on interactive `ask` prompts.

py_opencode_wrapper-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+opencode_wrapper/__init__.py,sha256=iCkMcrh7P35jHFq8gH-GKjaKqwnvmOkGCLRfgnb0moE,1013
+opencode_wrapper/client.py,sha256=YY7K8R6AcNWrOw595KazcLf1Q--CJgHvt6IJNT9cvOQ,13846
+opencode_wrapper/config.py,sha256=5vOlqc0YvPeFjmY9IH4DZYhhU3nKVp54Nt2KSeQaQUQ,3872
+opencode_wrapper/errors.py,sha256=zaXzzFb6ObdrNlm-PJE_7tbgvMEhoZcbeQVWNHNTkUQ,1168
+opencode_wrapper/events.py,sha256=PHz04DcB0K0JfIRxgV8GQ3psl7VjQXZ25gIrDCOgAHQ,6478
+py_opencode_wrapper-0.1.2.dist-info/METADATA,sha256=oT5MX1VOFtda9apHKONfEe_scVz3Z0PdBiNhPVMGyNg,6012
+py_opencode_wrapper-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+py_opencode_wrapper-0.1.2.dist-info/top_level.txt,sha256=8LETj5bPgl1YnB83iOiueuQvGryj3RzaeEQecPVS9Q8,17
+py_opencode_wrapper-0.1.2.dist-info/RECORD,,

py_opencode_wrapper-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_opencode_wrapper-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+opencode_wrapper