py-opencode-wrapper 0.1.3__tar.gz → 0.1.5__tar.gz

{py_opencode_wrapper-0.1.3 → py_opencode_wrapper-0.1.5}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: py-opencode-wrapper
-Version: 0.1.3
+Version: 0.1.5
 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
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
@@ -101,12 +101,13 @@ Per-call JSON is merged and passed as `OPENCODE_CONFIG_CONTENT` (see [OpenCode c
 
 | Field | Purpose |
 |--------|---------|
-| `permission` | `permission` map (`allow` / `ask` / `deny`, patterns) |
+| `permission` | `permission` map (`allow` / `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`.
+Note: `ask` is intentionally rejected in subprocess mode (no interactive terminal); use `allow` or `deny`.
 
 ## CLI arguments
 
@@ -147,13 +148,15 @@ Default `pytest -q` runs **all** tests; use `-m "not integration"` in CI without
 
 ## Concurrency notes
 
-When running many tasks with `asyncio.gather`, two mitigations are active by default:
+When running many tasks with `asyncio.gather`, three protections are enabled 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.
+**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.
 
-**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.
+**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.
 
-Set `startup_concurrency=0` (unlimited) and `max_retries=0` to opt out of both behaviours.
+**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.
+
+Set `startup_concurrency=0`, `isolate_db=False`, and `max_retries=0` to opt out.
 
 ## Notes
 

{py_opencode_wrapper-0.1.3 → py_opencode_wrapper-0.1.5}/README.md

@@ -88,12 +88,13 @@ Per-call JSON is merged and passed as `OPENCODE_CONFIG_CONTENT` (see [OpenCode c
 
 | Field | Purpose |
 |--------|---------|
-| `permission` | `permission` map (`allow` / `ask` / `deny`, patterns) |
+| `permission` | `permission` map (`allow` / `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`.
+Note: `ask` is intentionally rejected in subprocess mode (no interactive terminal); use `allow` or `deny`.
 
 ## CLI arguments
 
@@ -134,13 +135,15 @@ Default `pytest -q` runs **all** tests; use `-m "not integration"` in CI without
 
 ## Concurrency notes
 
-When running many tasks with `asyncio.gather`, two mitigations are active by default:
+When running many tasks with `asyncio.gather`, three protections are enabled 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.
+**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.
 
-**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.
+**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.
 
-Set `startup_concurrency=0` (unlimited) and `max_retries=0` to opt out of both behaviours.
+**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.
+
+Set `startup_concurrency=0`, `isolate_db=False`, and `max_retries=0` to opt out.
 
 ## Notes
 

{py_opencode_wrapper-0.1.3 → py_opencode_wrapper-0.1.5}/opencode_wrapper/config.py

@@ -5,13 +5,13 @@ from __future__ import annotations
 import json
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Mapping
+from typing import Any, Dict, Mapping
 
 # Permission values accepted by OpenCode
 PermissionAction = str  # "allow" | "ask" | "deny"
 
 # Nested permission maps: tool name -> action or pattern -> action
-PermissionMap = dict[str, Any]
+PermissionMap = Dict[str, Any]
 
 
 def _deep_merge(base: dict[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
@@ -55,6 +55,7 @@ class RunConfig:
     permission: PermissionMap | None = None
     mcp: dict[str, Any] | None = None
     tools: dict[str, Any] | None = None
+    instructions: list[str] | None = None
     config_overrides: dict[str, Any] | None = None
 
     def build_opencode_config_dict(self) -> dict[str, Any]:
@@ -68,6 +69,8 @@ class RunConfig:
             merged = _deep_merge(merged, {"mcp": dict(self.mcp)})
         if self.tools is not None:
             merged = _deep_merge(merged, {"tools": dict(self.tools)})
+        if self.instructions is not None:
+            merged = _deep_merge(merged, {"instructions": list(self.instructions)})
         return merged
 
     def opencode_config_content_json(self) -> str | None:

{py_opencode_wrapper-0.1.3 → py_opencode_wrapper-0.1.5}/py_opencode_wrapper.egg-info/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: py-opencode-wrapper
-Version: 0.1.3
+Version: 0.1.5
 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
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
@@ -101,12 +101,13 @@ Per-call JSON is merged and passed as `OPENCODE_CONFIG_CONTENT` (see [OpenCode c
 
 | Field | Purpose |
 |--------|---------|
-| `permission` | `permission` map (`allow` / `ask` / `deny`, patterns) |
+| `permission` | `permission` map (`allow` / `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`.
+Note: `ask` is intentionally rejected in subprocess mode (no interactive terminal); use `allow` or `deny`.
 
 ## CLI arguments
 
@@ -147,13 +148,15 @@ Default `pytest -q` runs **all** tests; use `-m "not integration"` in CI without
 
 ## Concurrency notes
 
-When running many tasks with `asyncio.gather`, two mitigations are active by default:
+When running many tasks with `asyncio.gather`, three protections are enabled 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.
+**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.
 
-**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.
+**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.
 
-Set `startup_concurrency=0` (unlimited) and `max_retries=0` to opt out of both behaviours.
+**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.
+
+Set `startup_concurrency=0`, `isolate_db=False`, and `max_retries=0` to opt out.
 
 ## Notes
 

{py_opencode_wrapper-0.1.3 → py_opencode_wrapper-0.1.5}/py_opencode_wrapper.egg-info/SOURCES.txt

@@ -11,9 +11,11 @@ py_opencode_wrapper.egg-info/dependency_links.txt
 py_opencode_wrapper.egg-info/requires.txt
 py_opencode_wrapper.egg-info/top_level.txt
 tests/test_client_async.py
+tests/test_config_instructions.py
 tests/test_config_permission.py
 tests/test_event_parser.py
 tests/test_integration_external_directory.py
+tests/test_integration_instructions.py
 tests/test_integration_multi_agent_weather.py
 tests/test_integration_opencode.py
 tests/test_integration_parallel.py

{py_opencode_wrapper-0.1.3 → py_opencode_wrapper-0.1.5}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "py-opencode-wrapper"
-version = "0.1.3"
+version = "0.1.5"
 description = "Async Python wrapper for OpenCode CLI (opencode run --format json)"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.8"
 dependencies = []
 
 [project.optional-dependencies]

py_opencode_wrapper-0.1.5/tests/test_config_instructions.py

@@ -0,0 +1,83 @@
+"""Tests for ``RunConfig.instructions`` field."""
+
+from __future__ import annotations
+
+import json
+
+from opencode_wrapper.client import build_env
+from opencode_wrapper.config import RunConfig
+
+
+def test_instructions_single_file() -> None:
+    cfg = RunConfig(instructions=["AGENT.md"])
+    d = cfg.build_opencode_config_dict()
+    assert d["instructions"] == ["AGENT.md"]
+
+
+def test_instructions_multiple_files() -> None:
+    cfg = RunConfig(instructions=["CONTRIBUTING.md", "docs/guidelines.md"])
+    d = cfg.build_opencode_config_dict()
+    assert d["instructions"] == ["CONTRIBUTING.md", "docs/guidelines.md"]
+
+
+def test_instructions_glob_pattern() -> None:
+    cfg = RunConfig(instructions=[".cursor/rules/*.md"])
+    d = cfg.build_opencode_config_dict()
+    assert d["instructions"] == [".cursor/rules/*.md"]
+
+
+def test_instructions_none_omits_key() -> None:
+    cfg = RunConfig(instructions=None)
+    d = cfg.build_opencode_config_dict()
+    assert "instructions" not in d
+
+
+def test_instructions_empty_list() -> None:
+    cfg = RunConfig(instructions=[])
+    d = cfg.build_opencode_config_dict()
+    assert d["instructions"] == []
+
+
+def test_instructions_in_opencode_config_content_json() -> None:
+    cfg = RunConfig(instructions=["AGENT.md", "docs/*.md"])
+    env = build_env(cfg, base={})
+    payload = json.loads(env["OPENCODE_CONFIG_CONTENT"])
+    assert payload["instructions"] == ["AGENT.md", "docs/*.md"]
+
+
+def test_instructions_deep_merges_with_config_overrides() -> None:
+    """instructions field wins over config_overrides when both set."""
+    cfg = RunConfig(
+        config_overrides={"instructions": ["old.md"]},
+        instructions=["new.md"],
+    )
+    d = cfg.build_opencode_config_dict()
+    # instructions applied after config_overrides, so it overwrites
+    assert d["instructions"] == ["new.md"]
+
+
+def test_instructions_config_overrides_used_when_no_instructions_field() -> None:
+    cfg = RunConfig(config_overrides={"instructions": ["via_overrides.md"]})
+    d = cfg.build_opencode_config_dict()
+    assert d["instructions"] == ["via_overrides.md"]
+
+
+def test_instructions_combined_with_permission_and_mcp() -> None:
+    cfg = RunConfig(
+        permission={"bash": "allow"},
+        mcp={"my-server": {"type": "local", "command": ["npx", "my-mcp"]}},
+        instructions=["AGENT.md"],
+    )
+    d = cfg.build_opencode_config_dict()
+    assert d["instructions"] == ["AGENT.md"]
+    assert d["permission"]["bash"] == "allow"
+    assert d["mcp"]["my-server"]["type"] == "local"
+
+
+def test_instructions_not_mutated() -> None:
+    """build_opencode_config_dict returns a copy; original list is not mutated."""
+    original = ["AGENT.md"]
+    cfg = RunConfig(instructions=original)
+    d = cfg.build_opencode_config_dict()
+    d["instructions"].append("extra.md")
+    assert cfg.instructions == ["AGENT.md"]

py_opencode_wrapper-0.1.5/tests/test_integration_instructions.py

@@ -0,0 +1,166 @@
+"""Integration test: verify ``RunConfig.instructions`` is actually loaded by opencode.
+
+Two complementary strategies:
+
+Strategy A — "probe keyword":
+  The instruction defines a magic keyword → fixed reply mapping.
+  Send the keyword; assert the exact reply appears.
+  Send the keyword WITHOUT the instruction; assert the reply is absent.
+  This is the most reliable approach: the response is deterministic and the
+  keyword is meaningless without the instruction, so false positives are impossible.
+
+Strategy B — "canary prefix" (kept as a cross-check):
+  The instruction mandates a unique token at the start of every response.
+  Ask the model directly what the token is; assert it appears.
+
+Requires: real ``opencode`` on PATH + configured provider.
+Run::
+
+    pytest -m integration -q tests/test_integration_instructions.py
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from opencode_wrapper import AsyncOpenCodeClient, RunConfig
+
+PROBE_KEYWORD = "__probe_instruction__"
+PROBE_REPLY = "MAKE AGENTS GREAT AGAIN!"
+
+# Unique enough that the model won't emit it by accident.
+CANARY = "XCANARY_INST_77Z"
+
+
+@pytest.fixture
+def probe_instruction_file(integration_workspace: Path) -> Path:
+    """Write the probe instruction file inside the workspace so the model can read it."""
+    f = integration_workspace / "probe_instructions.md"
+    f.write_text(
+        f'When the user inputs exactly "{PROBE_KEYWORD}", '
+        f'reply with exactly "{PROBE_REPLY}" and nothing else.\n',
+        encoding="utf-8",
+    )
+    return f
+
+
+@pytest.fixture
+def canary_instruction_file(integration_workspace: Path) -> Path:
+    """Write the canary instruction file inside the workspace so the model can read it."""
+    f = integration_workspace / "canary_instructions.md"
+    f.write_text(
+        f"Always begin every response with the exact token: {CANARY}\n",
+        encoding="utf-8",
+    )
+    return f
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_probe_keyword_triggers_defined_reply(
+    opencode_path: str,
+    integration_workspace: Path,
+    probe_instruction_file: Path,
+) -> None:
+    """Magic keyword defined in the instruction file produces the exact expected reply."""
+    client = AsyncOpenCodeClient(binary=opencode_path)
+    timeout = float(os.environ.get("OPENCODE_INTEGRATION_TIMEOUT_S", "300"))
+
+    result = await client.async_run(
+        PROBE_KEYWORD,
+        integration_workspace,
+        run_cfg=RunConfig(
+            disable_autoupdate=True,
+            instructions=[str(probe_instruction_file)],
+        ),
+        timeout_s=timeout,
+    )
+
+    assert result.exit_code == 0
+    blob = (result.final_text or "") + "\n".join(str(e) for e in result.events)
+    assert PROBE_REPLY in blob, (
+        f"Expected reply {PROBE_REPLY!r} not found — instruction file may not have been loaded.\n"
+        f"final_text={result.final_text!r}\nstderr={result.stderr!r}"
+    )
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_probe_keyword_no_reply_without_instruction(
+    opencode_path: str,
+    integration_workspace: Path,
+) -> None:
+    """Same keyword WITHOUT the instruction does not produce the probe reply."""
+    client = AsyncOpenCodeClient(binary=opencode_path)
+    timeout = float(os.environ.get("OPENCODE_INTEGRATION_TIMEOUT_S", "300"))
+
+    result = await client.async_run(
+        PROBE_KEYWORD,
+        integration_workspace,
+        run_cfg=RunConfig(agent="plan", disable_autoupdate=True),
+        timeout_s=timeout,
+    )
+
+    assert result.exit_code == 0
+    blob = (result.final_text or "") + "\n".join(str(e) for e in result.events)
+    assert PROBE_REPLY not in blob, (
+        f"Probe reply appeared without instruction — false positive.\n"
+        f"final_text={result.final_text!r}"
+    )
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_canary_instruction_file_is_loaded(
+    opencode_path: str,
+    integration_workspace: Path,
+    canary_instruction_file: Path,
+) -> None:
+    """Model response contains canary token when instruction file is provided."""
+    client = AsyncOpenCodeClient(binary=opencode_path)
+    timeout = float(os.environ.get("OPENCODE_INTEGRATION_TIMEOUT_S", "300"))
+
+    result = await client.async_run(
+        "Your instructions define a mandatory response prefix token. Output that token and nothing else.",
+        integration_workspace,
+        run_cfg=RunConfig(
+            disable_autoupdate=True,
+            instructions=[str(canary_instruction_file)],
+        ),
+        timeout_s=timeout,
+    )
+
+    assert result.exit_code == 0
+    blob = (result.final_text or "") + "\n".join(str(e) for e in result.events)
+    assert CANARY in blob, (
+        f"Canary token {CANARY!r} not found — instruction file may not have been loaded.\n"
+        f"final_text={result.final_text!r}\nstderr={result.stderr!r}"
+    )
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_canary_instruction_absent_without_field(
+    opencode_path: str,
+    integration_workspace: Path,
+) -> None:
+    """Same prompt without instruction file does NOT produce the canary token."""
+    client = AsyncOpenCodeClient(binary=opencode_path)
+    timeout = float(os.environ.get("OPENCODE_INTEGRATION_TIMEOUT_S", "300"))
+
+    result = await client.async_run(
+        "Your instructions define a mandatory response prefix token. Output that token and nothing else.",
+        integration_workspace,
+        run_cfg=RunConfig(agent="plan", disable_autoupdate=True),
+        timeout_s=timeout,
+    )
+
+    assert result.exit_code == 0
+    blob = (result.final_text or "") + "\n".join(str(e) for e in result.events)
+    assert CANARY not in blob, (
+        f"Canary token appeared without instruction — something is wrong.\n"
+        f"final_text={result.final_text!r}"
+    )