py-opencode-wrapper 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

opencode_wrapper/__init__.py

@@ -16,9 +16,11 @@ from opencode_wrapper.events import (
     parse_event_line,
     run_result_fuzzy_text,
 )
+from opencode_wrapper.session import OpenCodeSession
 
 __all__ = [
     "AsyncOpenCodeClient",
+    "OpenCodeSession",
     "RunConfig",
     "RunResult",
     "TokenUsage",

opencode_wrapper/client.py

@@ -73,7 +73,7 @@ def build_argv(
         cmd.extend(["--port", str(run_cfg.port)])
     if run_cfg.variant:
         cmd.extend(["--variant", run_cfg.variant])
-    if run_cfg.thinking is True:
+    if run_cfg.record_thinking is True or run_cfg.thinking is True:
         cmd.append("--thinking")
 
     if prompt:
@@ -313,15 +313,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 +339,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 +435,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 +468,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

@@ -147,6 +147,10 @@ class RunConfig:
     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

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

opencode_wrapper/session.py

@@ -0,0 +1,90 @@
+"""Stateful multi-turn conversation over a single opencode session."""
+
+from __future__ import annotations
+
+import dataclasses
+import shutil
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from opencode_wrapper.config import RunConfig
+from opencode_wrapper.events import RunResult
+
+if TYPE_CHECKING:
+    from opencode_wrapper.client import AsyncOpenCodeClient
+
+_UNSET: object = object()
+
+
+class OpenCodeSession:
+    """Multi-turn conversation backed by one persistent opencode session.
+
+    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__``.
+
+    Parameters
+    ----------
+    client:
+        The :class:`AsyncOpenCodeClient` used to spawn each turn.
+    workspace:
+        Project directory passed to every ``opencode run``.
+    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`.
+    timeout_s:
+        Default per-turn timeout; overridable per :meth:`send` call.
+    """
+
+    def __init__(
+        self,
+        client: "AsyncOpenCodeClient",
+        workspace: str | Path,
+        *,
+        run_cfg: RunConfig | None = None,
+        timeout_s: float | None = None,
+    ) -> None:
+        self._client = client
+        self._workspace = workspace
+        self._base_cfg = run_cfg or RunConfig()
+        self._timeout_s = timeout_s
+        self._data_home: str | None = None
+        self.session_id: str | None = None
+
+    async def __aenter__(self) -> "OpenCodeSession":
+        self._data_home = tempfile.mkdtemp(prefix="oc_session_")
+        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
+
+    async def send(
+        self,
+        prompt: str,
+        *,
+        run_cfg: RunConfig | None = None,
+        timeout_s: float | 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'"
+            )
+        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

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

@@ -1,26 +1,42 @@
 Metadata-Version: 2.4
 Name: py-opencode-wrapper
-Version: 0.2.1
+Version: 0.3.0
 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.8
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Dynamic: license-file
 
-# oc-py-harness
+# py-opencode-wrapper
 
 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+
+- Python 3.8+
 - `opencode` on `PATH` (or pass an absolute path to the binary)
 
-## Install (local tree)
+## Install
+
+From PyPI (most users):
+
+```bash
+pip install py-opencode-wrapper
+```
+
+The distribution name on PyPI is `py-opencode-wrapper`; import it as `opencode_wrapper`:
+
+```python
+from opencode_wrapper import AsyncOpenCodeClient, RunConfig
+```
+
+For local development (editable install with test deps):
 
 ```bash
 pip install -e ".[dev]"
@@ -39,7 +55,7 @@ from opencode_wrapper import AsyncOpenCodeClient, RunConfig
 async def main():
     client = AsyncOpenCodeClient("opencode")
     cfg = RunConfig(
-        model="anthropic/claude-sonnet-4-5",
+        model="opencode/big-pickle",
         agent="plan",
         permission={"bash": "deny", "edit": "deny"},
         mcp={
@@ -61,6 +77,40 @@ 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.
+
+### 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:
+
+```python
+import asyncio
+from opencode_wrapper import AsyncOpenCodeClient, OpenCodeSession, RunConfig
+
+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"
+        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.
+
 ### Stream structured JSON events
 
 ```python
@@ -75,11 +125,7 @@ async def stream_example():
 
 ```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)
+    client = AsyncOpenCodeClient()
     ws = Path("/path/to/monorepo")
     results = await asyncio.gather(*[
         client.async_run(
@@ -87,14 +133,14 @@ async def multi():
             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
 ```
 
+Safe defaults for parallel runs (startup serialisation, private SQLite DB per run, and automatic retry on SQLite-startup crashes) are enabled out of the box — most users don't need to tune them. See *Concurrency notes* below if you want to.
+
 ## Configuration injection
 
 Per-call JSON is merged and passed as `OPENCODE_CONFIG_CONTENT` (see [OpenCode config](https://opencode.ai/docs/config/)). Use `RunConfig` fields:
@@ -166,15 +212,15 @@ Default `pytest -q` runs **all** tests; use `-m "not integration"` in CI without
 
 ## Concurrency notes
 
-When running many tasks with `asyncio.gather`, three protections are enabled by default:
-
-**Startup serialisation** — `startup_concurrency=1` and `startup_delay_s=0.3` limit how many processes enter SQLite startup at once, reducing WAL-initialisation race crashes.
+The defaults already handle the common pitfalls when running many `async_run` calls in parallel — you usually don't need to touch any of these.
 
-**DB isolation** — `isolate_db=True` gives each run a private `XDG_DATA_HOME`, so concurrent runs do not contend on the same `opencode.db` during tool execution.
+- **Startup serialisation** (`startup_concurrency=1`, `startup_delay_s=0.3`) — spaces out SQLite WAL initialisation across processes to avoid a startup race in `opencode`.
+- **DB isolation** (`isolate_db=True`) — each run gets its own `XDG_DATA_HOME`, so concurrent runs don't share `opencode.db` and serialise on SQLite write locks during tool execution.
+- **Automatic retry** (`async_run(max_retries=2, retry_delay_s=1.0)`) — retries known SQLite-startup crashes with short backoff. Non-SQLite failures still fail fast.
 
-**Automatic retry** — `async_run(max_retries=2, retry_delay_s=1.0)` retries known SQLite-startup crashes with short backoff. Non-SQLite failures still fail fast.
+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.
 
-Set `startup_concurrency=0`, `isolate_db=False`, and `max_retries=0` to opt out.
+> 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.
 
 ## Notes
 

py_opencode_wrapper-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+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,,

py_opencode_wrapper-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0x0000ffff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_opencode_wrapper-0.2.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-opencode_wrapper/__init__.py,sha256=iCkMcrh7P35jHFq8gH-GKjaKqwnvmOkGCLRfgnb0moE,1013
-opencode_wrapper/client.py,sha256=Ny4pDBV6cToIOn2W7BgCFL1w12KdlVQVCInhddf_Df4,19546
-opencode_wrapper/config.py,sha256=JraBPkX95GXFoOvn181BRv_8YPvsUDXiZMN1hZWhSf0,7823
-opencode_wrapper/errors.py,sha256=zaXzzFb6ObdrNlm-PJE_7tbgvMEhoZcbeQVWNHNTkUQ,1168
-opencode_wrapper/events.py,sha256=PHz04DcB0K0JfIRxgV8GQ3psl7VjQXZ25gIrDCOgAHQ,6478
-py_opencode_wrapper-0.2.1.dist-info/METADATA,sha256=W56IyS4yoBlsSFIIrtsPx0-Ck6AoCCuhmdHiZslRgnE,6884
-py_opencode_wrapper-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-py_opencode_wrapper-0.2.1.dist-info/top_level.txt,sha256=8LETj5bPgl1YnB83iOiueuQvGryj3RzaeEQecPVS9Q8,17
-py_opencode_wrapper-0.2.1.dist-info/RECORD,,