Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
refactor(providers): share one base for agent CLI providers (#3167)
Raghav Chamadiya73915c2d7055
diff --git a/packages/core/src/repowise/core/providers/llm/agent_cli.py b/packages/core/src/repowise/core/providers/llm/agent_cli.pynew file mode 100644index 000000000..f656c9df7--- /dev/null+++ b/packages/core/src/repowise/core/providers/llm/agent_cli.py@@ -0,0 +1,306 @@+"""Shared base for LLM providers that drive a coding agent's CLI.++``claude_cli``, ``codex_cli`` and ``opencode`` generate pages by running the+user's already-authenticated agent CLI in a one-shot, non-interactive mode, so+no API key is involved. What they share lives here: finding the executable,+spawning it without a shell, sending the prompt on stdin (prompts are too large+for argv), the timeout and kill, killing the child when the caller cancels,+closing the subprocess transport before the loop shuts down, a per-event-loop+semaphore sized by ``resolve_concurrency``, the error tail, model label+handling and cost booking.++A subclass supplies its flags (``build_command``), how to read the CLI's output+(``parse_output``) and, where the CLI has them, model options and reasoning+modes. Anything that differs between the CLIs stays in the subclass.++Security: ``asyncio.create_subprocess_exec`` (no shell), and model names reach+argv, so they are validated against a safe character set unless a subclass+opts out.++Subscription seats are rate limited per account and each call is a full CLI+process: serializing turns a 100-page wiki into an hour or more, and too much+fan-out trips the account limit. The default of 4 comes from+``_concurrency.DEFAULT_CONCURRENCY``; the per-provider env var is a true+override, not a clamp, because only the operator knows their plan's ceiling.+"""++from __future__ import annotations++import asyncio+import contextlib+import json+import re+import shutil+from abc import abstractmethod+from collections.abc import Iterator+from contextlib import AbstractContextManager+from pathlib import Path+from typing import Any, ClassVar++import structlog++from repowise.core.providers.llm._concurrency import resolve_concurrency+from repowise.core.providers.llm.base import (+ BaseProvider,+ CacheHint,+ GeneratedResponse,+ ProviderError,+ record_generation_cost,+)+from repowise.core.rate_limiter import RateLimiter+from repowise.core.reasoning import ReasoningMode++log = structlog.get_logger(__name__)++# A process spawn plus a full agent turn on a prompt that can carry a lot of+# file context. Generous, because too low is not a slow page but no page.+EXEC_TIMEOUT_SECONDS = 600++_MODEL_NAME_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._/\-]*$")+++def tail(text: str, max_chars: int = 2_000) -> str:+ text = text.strip()+ if len(text) <= max_chars:+ return text+ return text[-max_chars:]+++def iter_jsonl(stdout: str) -> Iterator[Any]:+ """Decoded JSON lines, skipping blank and undecodable ones."""+ for raw_line in stdout.splitlines():+ line = raw_line.strip()+ if not line:+ continue+ try:+ yield json.loads(line)+ except json.JSONDecodeError:+ continue+++def validate_model_name(provider: str, model: str) -> None:+ if not _MODEL_NAME_RE.match(model):+ raise ProviderError(+ provider,+ f"Invalid model name {model!r}. Model names may only contain "+ "alphanumeric characters, dots, hyphens, underscores, and forward slashes.",+ )+++def normalize_model(model: str | None, provider: str, default: str | None) -> str | None:+ """Return the native model slug, or *default* when *model* names none.++ Accepts the persisted ``<provider>/<slug>`` label as well as a bare slug,+ so a value read back out of config.yaml round-trips.+ """+ prefix = f"{provider}/"+ if not model or model in (provider, f"{prefix}default"):+ return default+ return model.removeprefix(prefix) or default+++def model_label(native: str | None, provider: str) -> str:+ """Persisted attribution label: prefixed so cost estimation prices it at zero."""+ return f"{provider}/{native}" if native else f"{provider}/default"+++async def close_subprocess_transport(proc: asyncio.subprocess.Process) -> None:+ """Close asyncio's subprocess transport before the event loop shuts down."""+ transport = getattr(proc, "_transport", None)+ close = getattr(transport, "close", None)+ if not callable(close):+ return+ with contextlib.suppress(Exception):+ close()+ await asyncio.sleep(0)+++async def _kill(proc: asyncio.subprocess.Process) -> None:+ with contextlib.suppress(ProcessLookupError):+ proc.kill()+ with contextlib.suppress(ProcessLookupError):+ await proc.wait()+++class AgentCliProvider(BaseProvider):+ """Base for providers backed by a local agent CLI. See the module docstring."""++ provider_name: ClassVar[str] # type: ignore[misc]+ executable_name: ClassVar[str]+ # How errors name the invocation, e.g. ``codex exec``.+ command_label: ClassVar[str]+ concurrency_env: ClassVar[str]+ not_found_message: ClassVar[str]+ # Raised when the executable vanishes between lookup and spawn.+ spawn_not_found_message: ClassVar[str | None] = None+ # None: the CLI's own config picks the model.+ default_model: ClassVar[str | None] = None+ validates_model_name: ClassVar[bool] = True+ # Only claude_cli books llm_costs rows today; the others never have.+ records_cost: ClassVar[bool] = False+ error_tail_chars: ClassVar[int] = 2_000++ # A process spawn plus a full agent turn: the floor is tens of seconds, so+ # an interactive caller must budget in minutes or it cancels every call+ # (#1119). Stays under the exec timeout so the caller gives up first and+ # the error names the real cause.+ interactive_timeout_s: float = 180.0++ def __init__(+ self,+ model: str | None = None,+ repo_path: str | Path | None = None,+ rate_limiter: RateLimiter | None = None,+ ) -> None:+ executable = self.resolve_executable()+ if not executable:+ raise ProviderError(self.provider_name, self.not_found_message)+ self._executable = executable+ self._model = normalize_model(model, self.provider_name, self.default_model)+ if self._model is not None and self.validates_model_name:+ validate_model_name(self.provider_name, self._model)+ # Where the CLI is pointed (``--cd`` / ``--dir``); claude_cli ignores it.+ self._repo_path = (+ Path(repo_path).resolve() if repo_path is not None else Path.cwd().resolve()+ )+ self._rate_limiter = rate_limiter+ self._semaphore: asyncio.Semaphore | None = None+ self._semaphore_loop: asyncio.AbstractEventLoop | None = None++ @property+ def model_name(self) -> str:+ return model_label(self._model, self.provider_name)++ def resolve_executable(self) -> str | None:+ return shutil.which(self.executable_name)++ # -- subclass hooks -------------------------------------------------------++ @abstractmethod+ def build_command(self, system_prompt: str, reasoning: ReasoningMode) -> list[str]:+ """Return argv for one generation; the prompt goes on stdin."""++ @abstractmethod+ def parse_output(self, stdout: str, stderr: str) -> GeneratedResponse:+ """Build the response from a successful run's stdout."""++ def build_stdin(self, system_prompt: str, user_prompt: str) -> str:+ return user_prompt++ def working_dir(self) -> AbstractContextManager[str | None]:+ return contextlib.nullcontext()++ def subprocess_env(self) -> dict[str, str] | None:+ return None++ def exec_timeout_seconds(self) -> float:+ return EXEC_TIMEOUT_SECONDS++ def exit_error(self, returncode: int | None, stdout: str, stderr: str) -> ProviderError:+ return ProviderError(+ self.provider_name,+ self.error_message(stderr, stdout, returncode),+ status_code=returncode,+ )++ def stdout_error(self, stdout: str) -> str | None:+ """An error message the CLI reports in structured stdout, if any."""+ return None++ # -- shared machinery -----------------------------------------------------++ def error_message(self, stderr: str, stdout: str, returncode: int | None) -> str:+ for candidate in (tail(stderr, self.error_tail_chars), tail(stdout, self.error_tail_chars)):+ # Structured stdout can carry request details; never echo it raw.+ if candidate and not candidate.lstrip().startswith(("{", "[")):+ return candidate+ return self.stdout_error(stdout) or f"{self.command_label} exited with {returncode}"++ def _get_semaphore(self) -> asyncio.Semaphore:+ loop = asyncio.get_running_loop()+ if self._semaphore_loop is not loop:+ self._semaphore = asyncio.Semaphore(+ resolve_concurrency(self.concurrency_env, self.provider_name)+ )+ self._semaphore_loop = loop+ return self._semaphore # type: ignore[return-value]++ async def generate(+ self,+ system_prompt: str,+ user_prompt: str,+ max_tokens: int = 4096,+ temperature: float = 0.3,+ request_id: str | None = None,+ reasoning: ReasoningMode = "auto",+ cache_hints: tuple[CacheHint, ...] = (),+ ) -> GeneratedResponse:+ # temperature and max_tokens have no CLI equivalent; the base contract+ # says clip rather than raise, so they are dropped.+ if self._rate_limiter:+ await self._rate_limiter.acquire(estimated_tokens=max_tokens)++ # Off the loop: building can load a model catalog by subprocess.+ cmd = await asyncio.to_thread(self.build_command, system_prompt, reasoning)+ prompt = self.build_stdin(system_prompt, user_prompt)+ log.debug(+ f"{self.provider_name}.generate.start", model=self.model_name, request_id=request_id+ )++ async with self._get_semaphore():+ with self.working_dir() as cwd:+ returncode, stdout, stderr = await self._run(cmd, prompt, cwd)++ if returncode != 0:+ raise self.exit_error(returncode, stdout, stderr)++ response = self.parse_output(stdout, stderr)+ log.debug(+ f"{self.provider_name}.generate.done",+ input_tokens=response.input_tokens,+ output_tokens=response.output_tokens,+ cached_tokens=response.cached_tokens,+ request_id=request_id,+ )+ if self.records_cost:+ await record_generation_cost(+ getattr(self, "_cost_tracker", None), model=self.model_name, result=response+ )+ return response++ async def _run(+ self, cmd: list[str], prompt: str, cwd: str | None+ ) -> tuple[int | None, str, str]:+ try:+ proc = await asyncio.create_subprocess_exec(+ *cmd,+ stdin=asyncio.subprocess.PIPE,+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,+ cwd=cwd,+ env=self.subprocess_env(),+ )+ except FileNotFoundError as exc:+ message = self.spawn_not_found_message or self.not_found_message+ raise ProviderError(self.provider_name, message) from exc++ timeout = self.exec_timeout_seconds()+ try:+ stdout_bytes, stderr_bytes = await asyncio.wait_for(+ proc.communicate(prompt.encode("utf-8")), timeout=timeout+ )+ except asyncio.CancelledError:+ # The interactive caller gives up first; the CLI must not outlive it.+ await _kill(proc)+ raise+ except TimeoutError as exc:+ await _kill(proc)+ raise ProviderError(+ self.provider_name, f"{self.command_label} timed out after {timeout} seconds."+ ) from exc+ finally:+ await close_subprocess_transport(proc)++ stdout = stdout_bytes.decode("utf-8", errors="replace") if stdout_bytes else ""+ stderr = stderr_bytes.decode("utf-8", errors="replace") if stderr_bytes else ""+ return proc.returncode, stdout, stderrdiff --git a/packages/core/src/repowise/core/providers/llm/claude_cli.py b/packages/core/src/repowise/core/providers/llm/claude_cli.pyindex d113d194a..fb310c689 100644--- a/packages/core/src/repowise/core/providers/llm/claude_cli.py+++ b/packages/core/src/repowise/core/providers/llm/claude_cli.py@@ -3,12 +3,7 @@Delegates generation to the authenticated local Claude Code CLI via ``claude -p``(headless / print mode). Intended for users whose Claude subscription (Pro, Max,Team or Enterprise seat) is already configured by ``claude login``; it needs no-ANTHROPIC_API_KEY.--Security: uses ``asyncio.create_subprocess_exec`` (no shell), validates model-names against a safe character set, disables the CLI's tool catalog, and runs-the subprocess in a temporary scratch directory resolved with-``Path.resolve()``.+ANTHROPIC_API_KEY. Shared subprocess handling lives in ``agent_cli``.Two deliberate differences from the other agent-CLI providers:@@ -26,21 +21,23 @@ Two deliberate differences from the other agent-CLI providers:from __future__ import annotations-import asyncioimport contextlibimport json-import os-import re-import shutilimport tempfile+from collections.abc import Iteratorfrom pathlib import Pathfrom typing import Anyimport structlog+from repowise.core.providers.llm.agent_cli import (+ EXEC_TIMEOUT_SECONDS,+ AgentCliProvider,+ model_label,+ normalize_model,+ tail,+)from repowise.core.providers.llm.base import (- BaseProvider,- CacheHint,GeneratedResponse,ProviderError,ProviderModelOption,@@ -54,13 +51,7 @@ log = structlog.get_logger(__name__)# Matches the anthropic provider's default, whose docstring calls haiku "ample# for doc pages". Overridable with --model / REPOWISE_MODEL._DEFAULT_MODEL = "claude-haiku-5-5"-_LABEL_PREFIX = "claude_cli/"--_MODEL_NAME_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._/\-]*$")--# A process spawn plus a full CLI turn on a prompt that can carry a lot of file-# context. Generous, because too low is not a slow page but no page.-_EXEC_TIMEOUT_SECONDS = 600+_EXEC_TIMEOUT_SECONDS = EXEC_TIMEOUT_SECONDS# This is a one-shot text generation: the prompt already carries the context.# Claude Code can still try a denied tool and spend the single turn before it@@ -80,100 +71,17 @@ _SUPPORTED_REASONING_MODES: tuple[ReasoningMode, ...] = ("max",)-# Subscription seats are rate limited per account and each call is a full CLI-# process. Serializing turns a 68-page wiki into an hour; too much concurrency-# trips the account limit and fails the run. 4 matches the ceiling init applies-# to the other CLI-backed providers.-#-# The env override is a true override, not a clamp: it can raise the fan-out-# above 4 as well as lower it. Deliberate -- a Max seat can take more than a Pro-# one, and only the operator knows which they have -- but it does mean 4 is a-# default rather than an enforced cap.-_DEFAULT_CONCURRENCY = 4-_CONCURRENCY_ENV = "REPOWISE_CLAUDE_CLI_CONCURRENCY"--_NOT_FOUND_MESSAGE = (- "Claude Code CLI not found. Install it from https://claude.com/claude-code, "- "then run 'claude login'."-)---async def _close_subprocess_transport(proc: asyncio.subprocess.Process) -> None:- """Close asyncio's subprocess transport before the event loop shuts down."""-- transport = getattr(proc, "_transport", None)- close = getattr(transport, "close", None)- if not callable(close):- return- with contextlib.suppress(Exception):- close()- await asyncio.sleep(0)---def _resolve_claude_executable() -> str | None:- return shutil.which("claude")---def _validate_model_name(model: str) -> None:- if not _MODEL_NAME_RE.match(model):- raise ProviderError(- "claude_cli",- f"Invalid model name {model!r}. Model names may only contain "- "alphanumeric characters, dots, hyphens, underscores, and forward slashes.",- )-def _normalize_model(model: str | None) -> str:- """Return the native Claude model slug for *model*.-- Accepts the persisted ``claude_cli/<slug>`` label as well as a bare slug, so- a value read back out of config.yaml round-trips.- """- if not model:- return _DEFAULT_MODEL- if model in (_LABEL_PREFIX.rstrip("/"), f"{_LABEL_PREFIX}default"):- return _DEFAULT_MODEL- if model.startswith(_LABEL_PREFIX):- return model.removeprefix(_LABEL_PREFIX) or _DEFAULT_MODEL- return model+ return normalize_model(model, "claude_cli", _DEFAULT_MODEL) or _DEFAULT_MODELdef _model_label(native_model: str) -> str:- """Return the persisted attribution label for a Claude CLI model.-- Prefixed so cost estimation prices it at zero (a subscription, not API- spend) and so a page records which path produced it.- """- return f"{_LABEL_PREFIX}{native_model}"---def _resolve_concurrency() -> int:- raw = os.environ.get(_CONCURRENCY_ENV, "").strip()- if not raw:- return _DEFAULT_CONCURRENCY- try:- value = int(raw)- except ValueError:- log.warning("claude_cli.concurrency.invalid", value=raw, using=_DEFAULT_CONCURRENCY)- return _DEFAULT_CONCURRENCY- return max(1, value)+ return model_label(native_model, "claude_cli")-def _tail(text: str, max_chars: int = 2_000) -> str:- text = text.strip()- if len(text) <= max_chars:- return text- return text[-max_chars:]---def _error_message(stderr: str, stdout: str, returncode: int) -> str:- for candidate in (_tail(stderr), _tail(stdout)):- if not candidate:- continue- if candidate.lstrip().startswith(("{", "[")):- continue- return candidate- return f"claude -p exited with {returncode}"+def _is_failure(payload: dict[str, Any]) -> bool:+ return bool(payload.get("is_error")) or payload.get("subtype") != "success"def _payload_failure(payload: dict[str, Any]) -> tuple[str, int | None]:@@ -185,7 +93,7 @@ def _payload_failure(payload: dict[str, Any]) -> tuple[str, int | None]:detail = raw_status or payload.get("subtype") or "unknown error"result_text = payload.get("result")if isinstance(result_text, str) and result_text.strip():- detail = f"{detail}: {_tail(result_text, max_chars=500)}"+ detail = f"{detail}: {tail(result_text, max_chars=500)}"return f"claude -p reported failure ({detail}).", status_code@@ -215,11 +123,11 @@ def _parse_result(stdout: str) -> dict[str, Any]:raise ProviderError("claude_cli",- f"could not parse claude -p JSON output: {_tail(text, max_chars=500)}",+ f"could not parse claude -p JSON output: {tail(text, max_chars=500)}",)-class ClaudeCliProvider(BaseProvider):+class ClaudeCliProvider(AgentCliProvider):"""LLM provider backed by ``claude -p`` (Claude Code headless mode).Args:@@ -230,12 +138,18 @@ class ClaudeCliProvider(BaseProvider):bounds its own subprocess fan-out."""- # A process spawn plus a full CLI turn: the floor is tens of seconds even for- # a short prompt, so an interactive caller must budget in minutes or it- # cancels every call it makes (#1119). Stays under _EXEC_TIMEOUT_SECONDS so- # the caller gives up before the subprocess does and the error names the real- # cause.- interactive_timeout_s: float = 180.0+ provider_name = "claude_cli"+ executable_name = "claude"+ command_label = "claude -p"+ concurrency_env = "REPOWISE_CLAUDE_CLI_CONCURRENCY"+ not_found_message = (+ "Claude Code CLI not found. Install it from https://claude.com/claude-code, "+ "then run 'claude login'."+ )+ default_model = _DEFAULT_MODEL+ # Booked under the prefixed label, which prices a seat at $0.00 while+ # ``repowise costs`` still shows the run's token volume (#2267).+ records_cost = Truedef __init__(self,@@ -243,92 +157,57 @@ class ClaudeCliProvider(BaseProvider):rate_limiter: RateLimiter | None = None,**_ignored: Any,) -> None:- claude_cmd = _resolve_claude_executable()- if not claude_cmd:- raise ProviderError("claude_cli", _NOT_FOUND_MESSAGE)- self._claude_cmd = claude_cmd- self._model = _normalize_model(model)- _validate_model_name(self._model)- self._rate_limiter = rate_limiter- self._semaphore: asyncio.Semaphore | None = None- self._semaphore_loop: asyncio.AbstractEventLoop | None = None-- @property- def provider_name(self) -> str:- return "claude_cli"-- @property- def model_name(self) -> str:- return _model_label(self._model)+ # Swallows api_key/base_url a config overlay may pass; claude_cli uses neither.+ super().__init__(model, rate_limiter=rate_limiter)++ def exec_timeout_seconds(self) -> float:+ return _EXEC_TIMEOUT_SECONDS # a module global, so tests can patch itdef supported_reasoning_modes(self) -> tuple[ReasoningMode, ...]:return _SUPPORTED_REASONING_MODESdef available_model_options(self) -> tuple[ProviderModelOption, ...]:- # The CLI has no machine-readable model catalog to query, so this is a- # curated list rather than discovery.- return (- ProviderModelOption(- model=_model_label("claude-haiku-5-5"),- label="claude-haiku-5-5",- reasoning_modes=_SUPPORTED_REASONING_MODES,- recommended=True,- source="fallback",- notes="fastest; ample for doc pages",- ),- ProviderModelOption(- model=_model_label("claude-sonnet-4-6"),- label="claude-sonnet-4-6",- reasoning_modes=_SUPPORTED_REASONING_MODES,- source="fallback",- notes="better prose, slower",- ),+ # The CLI has no machine-readable model catalog, so this is curated.+ return tuple(ProviderModelOption(- model=_model_label("claude-opus-4-6"),- label="claude-opus-4-6",+ model=_model_label(slug),+ label=slug,reasoning_modes=_SUPPORTED_REASONING_MODES,+ recommended=recommended,source="fallback",- notes="highest quality; heaviest on subscription limits",- ),+ notes=notes,+ )+ for slug, recommended, notes in (+ ("claude-haiku-5-5", True, "fastest; ample for doc pages"),+ ("claude-sonnet-4-6", False, "better prose, slower"),+ ("claude-opus-4-6", False, "highest quality; heaviest on subscription limits"),+ ))- def _get_semaphore(self) -> asyncio.Semaphore:- loop = asyncio.get_running_loop()- if self._semaphore_loop is not loop:- self._semaphore = asyncio.Semaphore(_resolve_concurrency())- self._semaphore_loop = loop- return self._semaphore # type: ignore[return-value]-- def _build_command(- self,- system_prompt: str,- *,- reasoning: ReasoningMode = "auto",- ) -> list[str]:+ def build_command(self, system_prompt: str, reasoning: ReasoningMode) -> list[str]:+ prompt = system_prompt.strip()+ prompt = (+ f"{prompt}\n\n{_TOOLLESS_SYSTEM_INSTRUCTION}"+ if prompt+ else _TOOLLESS_SYSTEM_INSTRUCTION+ )+ # --system-prompt replaces Claude Code's agent preamble rather than+ # appending to it: repowise's prompt is the whole instruction set.cmd = [- self._claude_cmd,+ self._executable,"-p","--output-format","json","--model",- self._model,+ str(self._model),"--max-turns","1","--strict-mcp-config","--tools","",+ "--system-prompt",+ prompt,]- prompt = system_prompt.strip()- prompt = (- f"{prompt}\n\n{_TOOLLESS_SYSTEM_INSTRUCTION}"- if prompt- else _TOOLLESS_SYSTEM_INSTRUCTION- )- # --system-prompt replaces Claude Code's agent preamble rather than- # appending to it: repowise's prompt is the whole instruction set, and- # the coding-agent framing only competes with it.- cmd.extend(["--system-prompt", prompt])-mode = normalize_reasoning(reasoning)if mode in _SUPPORTED_REASONING_MODES[1:]:cmd.extend(["--effort", mode])@@ -337,88 +216,26 @@ class ClaudeCliProvider(BaseProvider):log.warning("claude_cli.reasoning.unsupported", requested=mode, using="auto")return cmd- async def generate(- self,- system_prompt: str,- user_prompt: str,- max_tokens: int = 4096,- temperature: float = 0.3,- request_id: str | None = None,- reasoning: ReasoningMode = "auto",- cache_hints: tuple[CacheHint, ...] = (),- ) -> GeneratedResponse:- # temperature and max_tokens have no CLI equivalent. The base-class- # contract says to clip rather than raise, so they are accepted and- # dropped.- if self._rate_limiter:- await self._rate_limiter.acquire(estimated_tokens=max_tokens)-- cmd = self._build_command(system_prompt, reasoning=reasoning)-- log.debug("claude_cli.generate.start", model=self.model_name, request_id=request_id)-- async with self._get_semaphore():- # One directory per call avoids both CLAUDE.md discovery and state- # leaking between concurrent pages. TemporaryDirectory removes it- # after success, failure, timeout, or cancellation.- with tempfile.TemporaryDirectory(prefix="repowise-claude-cli-") as scratch_dir:- cwd = str(Path(scratch_dir).resolve())- try:- proc = await asyncio.create_subprocess_exec(- *cmd,- stdin=asyncio.subprocess.PIPE,- stdout=asyncio.subprocess.PIPE,- stderr=asyncio.subprocess.PIPE,- cwd=cwd,- )- except FileNotFoundError as exc:- raise ProviderError("claude_cli", _NOT_FOUND_MESSAGE) from exc-- try:- stdout_bytes, stderr_bytes = await asyncio.wait_for(- proc.communicate(user_prompt.encode("utf-8")),- timeout=_EXEC_TIMEOUT_SECONDS,- )- except asyncio.CancelledError:- with contextlib.suppress(ProcessLookupError):- proc.kill()- with contextlib.suppress(ProcessLookupError):- await proc.wait()- raise- except TimeoutError as exc:- with contextlib.suppress(ProcessLookupError):- proc.kill()- with contextlib.suppress(ProcessLookupError):- await proc.wait()- raise ProviderError(- "claude_cli",- f"claude -p timed out after {_EXEC_TIMEOUT_SECONDS} seconds.",- ) from exc- finally:- await _close_subprocess_transport(proc)-- stdout = stdout_bytes.decode("utf-8", errors="replace") if stdout_bytes else ""- stderr = stderr_bytes.decode("utf-8", errors="replace") if stderr_bytes else ""+ @contextlib.contextmanager+ def working_dir(self) -> Iterator[str]:+ # One directory per call avoids both CLAUDE.md discovery and state+ # leaking between concurrent pages; it is removed however the call ends.+ with tempfile.TemporaryDirectory(prefix="repowise-claude-cli-") as scratch_dir:+ yield str(Path(scratch_dir).resolve())+ def exit_error(self, returncode: int | None, stdout: str, stderr: str) -> ProviderError:+ # API failures arrive as JSON on stdout, often with stderr empty.payload: dict[str, Any] | None = Nonewith contextlib.suppress(ProviderError):payload = _parse_result(stdout)+ if payload is not None and _is_failure(payload):+ message, status_code = _payload_failure(payload)+ return ProviderError("claude_cli", message, status_code=status_code)+ return ProviderError("claude_cli", self.error_message(stderr, stdout, returncode))- if proc.returncode != 0:- if payload is not None and (- payload.get("is_error") or payload.get("subtype") != "success"- ):- message, status_code = _payload_failure(payload)- raise ProviderError("claude_cli", message, status_code=status_code)- raise ProviderError(- "claude_cli",- _error_message(stderr, stdout, proc.returncode),- )-- if payload is None:- payload = _parse_result(stdout)-- if payload.get("is_error") or payload.get("subtype") != "success":+ def parse_output(self, stdout: str, stderr: str) -> GeneratedResponse:+ payload = _parse_result(stdout)+ if _is_failure(payload):message, status_code = _payload_failure(payload)raise ProviderError("claude_cli", message, status_code=status_code)@@ -428,35 +245,19 @@ class ClaudeCliProvider(BaseProvider):raw_usage = payload.get("usage")usage = raw_usage if isinstance(raw_usage, dict) else {}- # Claude Code reports only the *uncached remainder* of the prompt as- # ``input_tokens``. A page prompt is large and its stable prefix is- # cached, so the bulk of it arrives as a cache write (the first page of- # a type) or a cache read (every later page of that type). Persisting- # this field alone recorded ``input_tokens=2`` against a ~20k-token- # page, which is what made ``repowise status`` sum to zero for a whole- # wiki of claude_cli pages (#2267).+ # Claude Code reports only the uncached remainder as ``input_tokens``;+ # a page's stable prefix arrives as a cache write or a cache read. The+ # three are disjoint, so their sum is the prompt total the rest of the+ # codebase means by ``input_tokens`` (#2267). ``cached_tokens`` stays+ # the read half.uncached_input_tokens = int(usage.get("input_tokens", 0) or 0)output_tokens = int(usage.get("output_tokens", 0) or 0)- # The read half is the "served from cache" number repowise reports.cached_tokens = int(usage.get("cache_read_input_tokens", 0) or 0)cache_creation_tokens = int(usage.get("cache_creation_input_tokens", 0) or 0)- # The three are disjoint (a prompt token is sent uncached, read from the- # cache, or written to it), so their sum is the prompt total the rest of- # the codebase means by ``input_tokens``. ``cached_tokens`` stays the- # read half, separately, exactly as the provider docs describe.input_tokens = uncached_input_tokens + cached_tokens + cache_creation_tokensstop_reason, provider_stop_reason = normalize_stop_reason(payload.get("stop_reason"))- log.debug(- "claude_cli.generate.done",- input_tokens=input_tokens,- uncached_input_tokens=uncached_input_tokens,- output_tokens=output_tokens,- cached_tokens=cached_tokens,- request_id=request_id,- )-usage_payload = {**usage,"source": "claude_cli",@@ -464,16 +265,15 @@ class ClaudeCliProvider(BaseProvider):"input_tokens": input_tokens,"uncached_input_tokens": uncached_input_tokens,"cache_creation_input_tokens": cache_creation_tokens,- # Recorded for auditing only. Cost is priced at zero in the cost- # table: this is subscription usage, not API spend.+ # Auditing only: the cost table prices subscription usage at zero."reported_cost_usd": payload.get("total_cost_usd"),"num_turns": payload.get("num_turns"),- "stderr": _tail(stderr, max_chars=1_000) if stderr.strip() else "",+ "stderr": tail(stderr, 1_000),}if not usage:usage_payload["estimated"] = True- response = GeneratedResponse(+ return GeneratedResponse(content=content,input_tokens=input_tokens,output_tokens=output_tokens,@@ -482,27 +282,3 @@ class ClaudeCliProvider(BaseProvider):stop_reason=stop_reason,provider_stop_reason=provider_stop_reason,)-- tracker = getattr(self, "_cost_tracker", None)- if tracker is not None:- # Booked under the prefixed label so the ledger prices the call at- # $0.00 (``claude_cli/`` is a zero-cost prefix: a seat is not API- # spend) while ``repowise costs`` still shows the run's token- # volume. Without this the provider wrote no ``llm_costs`` row at- # all and ``repowise costs`` reported "No cost records found" for a- # whole claude_cli wiki (#2267).- #- # Awaited inline rather than fired off as a detached task: a- # fire-and-forget write can still be in flight when the event loop- # is torn down after generation. ``record()`` swallows its own- # persistence errors, so generation is unaffected either way.- with contextlib.suppress(Exception):- await tracker.record(- model=self.model_name,- input_tokens=input_tokens,- output_tokens=output_tokens,- operation=tracker.operation,- file_path=None,- )-- return responsediff --git a/packages/core/src/repowise/core/providers/llm/codex_cli.py b/packages/core/src/repowise/core/providers/llm/codex_cli.pyindex 4a2dd1999..59380ebee 100644--- a/packages/core/src/repowise/core/providers/llm/codex_cli.py+++ b/packages/core/src/repowise/core/providers/llm/codex_cli.py@@ -7,59 +7,34 @@ configured by ``codex login`` and does not require an OpenAI API key.from __future__ import annotations-import asyncio-import contextlibimport json-import shutilimport subprocessfrom dataclasses import dataclassfrom functools import lru_cache-from pathlib import Pathfrom typing import Any-import structlog-from repowise.core.providers.llm._concurrency import resolve_concurrency+from repowise.core.providers.llm.agent_cli import (+ EXEC_TIMEOUT_SECONDS,+ AgentCliProvider,+ iter_jsonl,+ model_label,+ normalize_model,+ tail,+)from repowise.core.providers.llm.base import (- BaseProvider,- CacheHint,GeneratedResponse,ProviderError,ProviderModelOption,)-from repowise.core.rate_limiter import RateLimiterfrom repowise.core.reasoning import REASONING_MODES, ReasoningMode, normalize_reasoning-log = structlog.get_logger(__name__)-_DEFAULT_MODEL_LABEL = "codex_cli/default"-_EXEC_TIMEOUT_SECONDS = 600+_EXEC_TIMEOUT_SECONDS = EXEC_TIMEOUT_SECONDS_CATALOG_TIMEOUT_SECONDS = 5--# Subscription seats are rate limited per account and each call is a full CLI-# process. Serializing turns a 104-page generate into about 95 minutes; too-# much concurrency trips the account limit and fails the run. 4 matches the-# ceiling init applies to the other CLI-backed providers.-#-# The env override is a true override, not a clamp: it can raise the fan-out-# above 4 as well as lower it. Deliberate -- a higher-tier plan can take more-# than a lower one, and only the operator knows which they have -- but it does-# mean 4 is a default rather than an enforced cap._CONCURRENCY_ENV = "REPOWISE_CODEX_CLI_CONCURRENCY"-async def _close_subprocess_transport(proc: asyncio.subprocess.Process) -> None:- """Close asyncio's subprocess transport before the event loop shuts down."""-- transport = getattr(proc, "_transport", None)- close = getattr(transport, "close", None)- if not callable(close):- return- with contextlib.suppress(Exception):- close()- await asyncio.sleep(0)--@dataclass(frozen=True)class CodexModelReasoning:"""Small reasoning-capability slice extracted from the Codex model catalog."""@@ -69,28 +44,13 @@ class CodexModelReasoning:supported_efforts: tuple[str, ...]-def _resolve_codex_executable() -> str | None:- """Return the executable path used to launch Codex, or None if unavailable."""-- return shutil.which("codex")--def _normalize_model(model: str | None) -> str | None:"""Return the native Codex model slug, or None to use CLI config."""- if not model:- return None- if model == _DEFAULT_MODEL_LABEL:- return None- if model.startswith("codex_cli/"):- suffix = model.removeprefix("codex_cli/")- return suffix or None- return model+ return normalize_model(model, "codex_cli", None)def _model_label(model: str | None) -> str:- """Return the persisted attribution label for a Codex CLI model."""- native = _normalize_model(model)- return f"codex_cli/{native}" if native else _DEFAULT_MODEL_LABEL+ return model_label(_normalize_model(model), "codex_cli")def _resolve_concurrency() -> int:@@ -317,15 +277,7 @@ def _parse_jsonl(stdout: str) -> tuple[str, dict[str, Any]]:content_parts: list[str] = []usage: dict[str, Any] = {}- for raw_line in stdout.splitlines():- line = raw_line.strip()- if not line:- continue- try:- event = json.loads(line)- except json.JSONDecodeError:- continue-+ for event in iter_jsonl(stdout):if event.get("type") == "item.completed":item = event.get("item") or {}if item.get("type") == "agent_message":@@ -340,24 +292,7 @@ def _parse_jsonl(stdout: str) -> tuple[str, dict[str, Any]]:return "\n".join(content_parts), usage-def _tail(text: str, max_chars: int = 2_000) -> str:- text = text.strip()- if len(text) <= max_chars:- return text- return text[-max_chars:]---def _error_message(stderr: str, stdout: str, returncode: int) -> str:- for candidate in (_tail(stderr), _tail(stdout)):- if not candidate:- continue- if candidate.lstrip().startswith(("{", "[")):- continue- return candidate- return f"codex exec exited with {returncode}"---class CodexCliProvider(BaseProvider):+class CodexCliProvider(AgentCliProvider):"""LLM provider backed by ``codex exec``.Args:@@ -369,58 +304,26 @@ class CodexCliProvider(BaseProvider):bounds its own subprocess fan-out."""- # A process spawn plus a full Codex agent turn. The floor is tens of- # seconds even for a short prompt, so an interactive caller has to budget- # in minutes or it cancels every call it ever makes (#1119). Stays under- # _EXEC_TIMEOUT_SECONDS so the caller gives up before the subprocess does- # and the error names the real cause.- interactive_timeout_s: float = 180.0-- def __init__(- self,- model: str | None = None,- repo_path: str | Path | None = None,- rate_limiter: RateLimiter | None = None,- ) -> None:- codex_cmd = _resolve_codex_executable()- if not codex_cmd:- raise ProviderError(- "codex_cli",- "Codex CLI not found. Install it with: npm install -g @openai/codex",- )- self._codex_cmd = codex_cmd- self._model = _normalize_model(model)- self._repo_path = (- Path(repo_path).resolve() if repo_path is not None else Path.cwd().resolve()- )- self._rate_limiter = rate_limiter- self._subprocess_semaphore: asyncio.Semaphore | None = None- self._semaphore_loop: asyncio.AbstractEventLoop | None = None-- @property- def provider_name(self) -> str:- return "codex_cli"+ provider_name = "codex_cli"+ executable_name = "codex"+ command_label = "codex exec"+ concurrency_env = _CONCURRENCY_ENV+ not_found_message = "Codex CLI not found. Install it with: npm install -g @openai/codex"+ # No validation: the codex catalog decides, and an unlisted slug is passed through.+ validates_model_name = False- @property- def model_name(self) -> str:- return _model_label(self._model)+ def exec_timeout_seconds(self) -> float:+ return _EXEC_TIMEOUT_SECONDS # a module global, so tests can patch itdef supported_reasoning_modes(self) -> tuple[ReasoningMode, ...]:- return _codex_supported_reasoning_modes(self._codex_cmd, self.model_name)+ return _codex_supported_reasoning_modes(self._executable, self.model_name)def available_model_options(self) -> tuple[ProviderModelOption, ...]:- return _codex_model_options(self._codex_cmd)-- def _get_semaphore(self) -> asyncio.Semaphore:- loop = asyncio.get_running_loop()- if self._semaphore_loop is not loop:- self._subprocess_semaphore = asyncio.Semaphore(_resolve_concurrency())- self._semaphore_loop = loop- return self._subprocess_semaphore # type: ignore[return-value]+ return _codex_model_options(self._executable)- def _build_command(self, *, reasoning: ReasoningMode = "auto") -> list[str]:+ def build_command(self, system_prompt: str, reasoning: ReasoningMode) -> list[str]:cmd = [- self._codex_cmd,+ self._executable,"exec","--ephemeral","--sandbox",@@ -428,9 +331,10 @@ class CodexCliProvider(BaseProvider):"--json","--cd",str(self._repo_path),+ "--config",+ "project_doc_max_bytes=0",]- cmd.extend(["--config", "project_doc_max_bytes=0"])- reasoning_config = _codex_reasoning_config(self._codex_cmd, self.model_name, reasoning)+ reasoning_config = _codex_reasoning_config(self._executable, self.model_name, reasoning)if reasoning_config:cmd.extend(["--config", reasoning_config])if self._model:@@ -438,71 +342,10 @@ class CodexCliProvider(BaseProvider):cmd.append("-")return cmd- async def generate(- self,- system_prompt: str,- user_prompt: str,- max_tokens: int = 4096,- temperature: float = 0.3,- request_id: str | None = None,- reasoning: ReasoningMode = "auto",- cache_hints: tuple[CacheHint, ...] = (),- ) -> GeneratedResponse:- if self._rate_limiter:- await self._rate_limiter.acquire(estimated_tokens=max_tokens)-- # _build_command may shell out to `codex debug models` (cached) to validate- # the reasoning effort; run it off the event loop so a cold catalog load- # can't stall every concurrent generation coroutine.- cmd = await asyncio.to_thread(self._build_command, reasoning=reasoning)- prompt = _combine_prompt(system_prompt, user_prompt)- log.debug(- "codex_cli.generate.start",- model=self.model_name,- repo_path=str(self._repo_path),- request_id=request_id,- )-- async with self._get_semaphore():- try:- proc = await asyncio.create_subprocess_exec(- *cmd,- stdin=asyncio.subprocess.PIPE,- stdout=asyncio.subprocess.PIPE,- stderr=asyncio.subprocess.PIPE,- )- except FileNotFoundError as exc:- raise ProviderError(- "codex_cli",- "Codex CLI not found. Install it with: npm install -g @openai/codex",- ) from exc-- try:- stdout_bytes, stderr_bytes = await asyncio.wait_for(- proc.communicate(prompt.encode("utf-8")),- timeout=_EXEC_TIMEOUT_SECONDS,- )- except TimeoutError as exc:- proc.kill()- with contextlib.suppress(ProcessLookupError):- await proc.wait()- raise ProviderError(- "codex_cli",- f"codex exec timed out after {_EXEC_TIMEOUT_SECONDS} seconds.",- ) from exc- finally:- await _close_subprocess_transport(proc)-- stdout = stdout_bytes.decode("utf-8", errors="replace") if stdout_bytes else ""- stderr = stderr_bytes.decode("utf-8", errors="replace") if stderr_bytes else ""-- if proc.returncode != 0:- raise ProviderError(- "codex_cli",- _error_message(stderr, stdout, proc.returncode),- status_code=proc.returncode,- )+ def build_stdin(self, system_prompt: str, user_prompt: str) -> str:+ return _combine_prompt(system_prompt, user_prompt)+ def parse_output(self, stdout: str, stderr: str) -> GeneratedResponse:content, usage = _parse_jsonl(stdout)if not content:raise ProviderError(@@ -510,31 +353,19 @@ class CodexCliProvider(BaseProvider):"codex exec completed but no agent_message was found in JSONL output.",)- usage_missing = not usage- input_tokens = int(usage.get("input_tokens", 0) or 0)- output_tokens = int(usage.get("output_tokens", 0) or 0)- cached_tokens = int(usage.get("cached_input_tokens", 0) or 0)-- log.debug(- "codex_cli.generate.done",- input_tokens=input_tokens,- output_tokens=output_tokens,- cached_tokens=cached_tokens,- request_id=request_id,- )usage_payload = {**usage,"source": "codex_exec","model": self.model_name,- "stderr": _tail(stderr, max_chars=1_000) if stderr.strip() else "",+ "stderr": tail(stderr, 1_000),}- if usage_missing:+ if not usage:usage_payload["estimated"] = Truereturn GeneratedResponse(content=content,- input_tokens=input_tokens,- output_tokens=output_tokens,- cached_tokens=cached_tokens,+ input_tokens=int(usage.get("input_tokens", 0) or 0),+ output_tokens=int(usage.get("output_tokens", 0) or 0),+ cached_tokens=int(usage.get("cached_input_tokens", 0) or 0),usage=usage_payload,)diff --git a/packages/core/src/repowise/core/providers/llm/opencode.py b/packages/core/src/repowise/core/providers/llm/opencode.pyindex 8c571d5c1..1b3bfe31f 100644--- a/packages/core/src/repowise/core/providers/llm/opencode.py+++ b/packages/core/src/repowise/core/providers/llm/opencode.py@@ -12,42 +12,33 @@ subprocess, and enforces a read-only permission profile via ``OPENCODE_CONFIG_COfrom __future__ import annotations-import asyncio-import contextlibimport jsonimport osimport re-import shutilimport subprocessimport uuid-from collections.abc import Iterator-from functools import lru_cache-from pathlib import Path+from functools import lru_cache, partialfrom typing import Any-import structlog--from repowise.core.providers.llm._concurrency import resolve_concurrency+from repowise.core.providers.llm.agent_cli import (+ EXEC_TIMEOUT_SECONDS,+ AgentCliProvider,+ iter_jsonl,+ model_label,+ normalize_model,+ tail,+ validate_model_name,+)from repowise.core.providers.llm.base import (- BaseProvider,- CacheHint,GeneratedResponse,ProviderError,ProviderModelOption,)-from repowise.core.rate_limiter import RateLimiterfrom repowise.core.reasoning import ReasoningMode-log = structlog.get_logger(__name__)--_CONCURRENCY_ENV = "REPOWISE_OPENCODE_CONCURRENCY"-_DEFAULT_MODEL_LABEL = "opencode/default"-_EXEC_TIMEOUT_SECONDS = 600+_EXEC_TIMEOUT_SECONDS = EXEC_TIMEOUT_SECONDS_CATALOG_TIMEOUT_SECONDS = 10-_MAX_STDERR_CHARS = 1_000--_MODEL_NAME_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._/\-]*$")_OPENCODE_READONLY_CONFIG = json.dumps({@@ -67,33 +58,11 @@ _OPENCODE_READONLY_CONFIG = json.dumps()-def _resolve_opencode_executable() -> str | None:- return shutil.which("opencode")---def _validate_model_name(model: str) -> None:- if not _MODEL_NAME_RE.match(model):- raise ProviderError(- "opencode",- f"Invalid model name {model!r}. Model names may only contain "- "alphanumeric characters, dots, hyphens, underscores, and forward slashes.",- )---def _normalize_model(model: str | None) -> str | None:- if not model:- return None- if model == _DEFAULT_MODEL_LABEL:- return None- if model.startswith("opencode/"):- suffix = model.removeprefix("opencode/")- return suffix or None- return model+_validate_model_name = partial(validate_model_name, "opencode")-def _model_label(model: str | None) -> str:- native = _normalize_model(model)- return f"opencode/{native}" if native else _DEFAULT_MODEL_LABEL+def _model_label(model: str) -> str:+ return model_label(normalize_model(model, "opencode", None), "opencode")def _combine_prompt(system_prompt: str, user_prompt: str) -> str:@@ -110,7 +79,7 @@ def _parse_jsonl(stdout: str) -> tuple[str, dict[str, Any]]:content_parts: list[str] = []usage: dict[str, Any] = {}- for event in _iter_jsonl_events(stdout):+ for event in iter_jsonl(stdout):event_type = event.get("type")part = event.get("part") or {}if event_type == "text":@@ -125,18 +94,6 @@ def _parse_jsonl(stdout: str) -> tuple[str, dict[str, Any]]:return "\n".join(content_parts), usage-def _iter_jsonl_events(stdout: str) -> Iterator[Any]:- """Decoded JSON lines, skipping blank and undecodable ones."""- for raw_line in stdout.splitlines():- line = raw_line.strip()- if not line:- continue- try:- yield json.loads(line)- except json.JSONDecodeError:- continue--def _add_token_counts(usage: dict[str, Any], tokens: dict[str, Any]) -> None:"""Sum one step's token counts into *usage*, one level of nesting deep.@@ -156,28 +113,6 @@ def _add_token_counts(usage: dict[str, Any], tokens: dict[str, Any]) -> None:usage[key] = usage.get(key, 0) + int(value)-def _tail(text: str, max_chars: int = _MAX_STDERR_CHARS) -> str:- text = text.strip()- if len(text) <= max_chars:- return text- return text[-max_chars:]---def _error_message(stderr: str, stdout: str, returncode: int) -> str:- for candidate in (_tail(stderr), _tail(stdout)):- if not candidate:- continue- if candidate.lstrip().startswith(("{", "[")):- continue- return candidate-- msg = _error_event_message(stdout)- if msg:- return msg-- return f"opencode run exited with {returncode}"--def _error_event_message(stdout: str) -> str | None:"""Message of the first ``error`` event in *stdout*.@@ -277,7 +212,7 @@ def _opencode_model_options(return tuple(options)-class OpenCodeProvider(BaseProvider):+class OpenCodeProvider(AgentCliProvider):"""LLM provider backed by ``opencode run``.Uses the local opencode CLI for generation. Does not require an API key —@@ -288,74 +223,40 @@ class OpenCodeProvider(BaseProvider):(e.g. ``deepseek/deepseek-v4-pro``). If omitted or``opencode/default``, opencode uses its configured default.repo_path: Working directory passed to opencode via ``--dir``.- rate_limiter: Serializes subprocess calls by default.+ rate_limiter: Accepted for interface consistency; the provider also+ bounds its own subprocess fan-out."""- # `opencode run` spawns a process and drives a whole agent turn, and the- # model behind it is whatever the user configured, local ones included.- # Minutes, not seconds. Stays under _EXEC_TIMEOUT_SECONDS so the caller- # gives up before the subprocess does and the error names the real cause.- interactive_timeout_s: float = 180.0-- def __init__(- self,- model: str | None = None,- repo_path: str | Path | None = None,- rate_limiter: RateLimiter | None = None,- ) -> None:- opencode_cmd = _resolve_opencode_executable()- if not opencode_cmd:- raise ProviderError(- "opencode",- "OpenCode CLI is not installed.\n\n"- "Installation:\n"- " curl -fsSL https://opencode.ai/install | bash\n\n"- "After installing, run 'opencode' once to set up your model provider "- "and authenticate. No API keys are managed by repowise — opencode "- "handles all authentication.\n\n"- "To choose a model:\n"- " opencode models # list available models\n"- " repowise init --provider opencode --model opencode/deepseek/deepseek-v4-pro\n\n"- "More info: https://opencode.ai",- )- self._opencode_cmd = opencode_cmd- native = _normalize_model(model)- if native is not None:- _validate_model_name(native)- self._model = native- self._repo_path = (- Path(repo_path).resolve() if repo_path is not None else Path.cwd().resolve()- )- self._rate_limiter = rate_limiter- self._subprocess_semaphore: asyncio.Semaphore | None = None- self._semaphore_loop: asyncio.AbstractEventLoop | None = None-- @property- def provider_name(self) -> str:- return "opencode"-- @property- def model_name(self) -> str:- return _model_label(self._model)+ provider_name = "opencode"+ executable_name = "opencode"+ command_label = "opencode run"+ concurrency_env = "REPOWISE_OPENCODE_CONCURRENCY"+ not_found_message = (+ "OpenCode CLI is not installed.\n\n"+ "Installation:\n"+ " curl -fsSL https://opencode.ai/install | bash\n\n"+ "After installing, run 'opencode' once to set up your model provider "+ "and authenticate. No API keys are managed by repowise — opencode "+ "handles all authentication.\n\n"+ "To choose a model:\n"+ " opencode models # list available models\n"+ " repowise init --provider opencode --model opencode/deepseek/deepseek-v4-pro\n\n"+ "More info: https://opencode.ai"+ )+ spawn_not_found_message = (+ "OpenCode CLI not found. Install it with: curl -fsSL https://opencode.ai/install | bash"+ )+ error_tail_chars = 1_000- def supported_reasoning_modes(self) -> tuple[ReasoningMode, ...]:- return ("auto",)+ def exec_timeout_seconds(self) -> float:+ return _EXEC_TIMEOUT_SECONDS # a module global, so tests can patch itdef available_model_options(self) -> tuple[ProviderModelOption, ...]:- return _opencode_model_options(self._opencode_cmd)-- def _get_semaphore(self) -> asyncio.Semaphore:- loop = asyncio.get_running_loop()- if self._semaphore_loop is not loop:- self._subprocess_semaphore = asyncio.Semaphore(- resolve_concurrency(_CONCURRENCY_ENV, "opencode")- )- self._semaphore_loop = loop- return self._subprocess_semaphore # type: ignore[return-value]+ return _opencode_model_options(self._executable)- def _build_command(self) -> list[str]:+ def build_command(self, system_prompt: str, reasoning: ReasoningMode) -> list[str]:cmd = [- self._opencode_cmd,+ self._executable,"run","--format","json",@@ -368,90 +269,20 @@ class OpenCodeProvider(BaseProvider):cmd.extend(["--model", self._model])return cmd- async def generate(- self,- system_prompt: str,- user_prompt: str,- max_tokens: int = 4096,- temperature: float = 0.3,- request_id: str | None = None,- reasoning: ReasoningMode = "auto",- cache_hints: tuple[CacheHint, ...] = (),- ) -> GeneratedResponse:- if self._rate_limiter:- await self._rate_limiter.acquire(estimated_tokens=max_tokens)-- cmd = self._build_command()- prompt = _combine_prompt(system_prompt, user_prompt)- log.debug(- "opencode.generate.start",- model=self.model_name,- repo_path=str(self._repo_path),- request_id=request_id,- )+ def build_stdin(self, system_prompt: str, user_prompt: str) -> str:+ return _combine_prompt(system_prompt, user_prompt)- returncode, stdout, stderr = await self._run(cmd, prompt)- if returncode != 0:- raise ProviderError(- "opencode",- _error_message(stderr, stdout, returncode),- status_code=returncode,- )+ def subprocess_env(self) -> dict[str, str]:+ return {+ **os.environ,+ "OPENCODE_CONFIG_CONTENT": _OPENCODE_READONLY_CONFIG,+ "OPENCODE_DISABLE_PROJECT_CONFIG": "true",+ }- response = self._response_from_output(stdout, stderr)- log.debug(- "opencode.generate.done",- input_tokens=response.input_tokens,- output_tokens=response.output_tokens,- cached_tokens=response.cached_tokens,- request_id=request_id,- )- return response-- async def _run(self, cmd: list[str], prompt: str) -> tuple[int, str, str]:- """Run ``opencode run`` with *prompt* on stdin; returns (code, stdout, stderr)."""- async with self._get_semaphore():- try:- proc = await asyncio.create_subprocess_exec(- *cmd,- stdin=asyncio.subprocess.PIPE,- stdout=asyncio.subprocess.PIPE,- stderr=asyncio.subprocess.PIPE,- env={- **os.environ,- "OPENCODE_CONFIG_CONTENT": _OPENCODE_READONLY_CONFIG,- "OPENCODE_DISABLE_PROJECT_CONFIG": "true",- },- )- except FileNotFoundError as exc:- raise ProviderError(- "opencode",- "OpenCode CLI not found. Install it with: "- "curl -fsSL https://opencode.ai/install | bash",- ) from exc-- try:- stdout_bytes, stderr_bytes = await asyncio.wait_for(- proc.communicate(prompt.encode("utf-8")),- timeout=_EXEC_TIMEOUT_SECONDS,- )- except TimeoutError as exc:- proc.kill()- with contextlib.suppress(ProcessLookupError):- await proc.wait()- raise ProviderError(- "opencode",- f"opencode run timed out after {_EXEC_TIMEOUT_SECONDS} seconds.",- ) from exc- finally:- await _close_subprocess_transport(proc)-- stdout = stdout_bytes.decode("utf-8", errors="replace") if stdout_bytes else ""- stderr = stderr_bytes.decode("utf-8", errors="replace") if stderr_bytes else ""- return proc.returncode, stdout, stderr-- def _response_from_output(self, stdout: str, stderr: str) -> GeneratedResponse:- """Build the response from a successful run's JSONL event stream."""+ def stdout_error(self, stdout: str) -> str | None:+ return _error_event_message(stdout)++ def parse_output(self, stdout: str, stderr: str) -> GeneratedResponse:content, usage = _parse_jsonl(stdout)if not content:raise ProviderError(@@ -463,7 +294,7 @@ class OpenCodeProvider(BaseProvider):**usage,"source": "opencode_run","model": self.model_name,- "stderr": _tail(stderr) if stderr.strip() else "",+ "stderr": tail(stderr, 1_000),}if not usage:usage_payload["estimated"] = True@@ -475,12 +306,3 @@ class OpenCodeProvider(BaseProvider):cached_tokens=int((usage.get("cache") or {}).get("read", 0) or 0),usage=usage_payload,)--async def _close_subprocess_transport(proc: asyncio.subprocess.Process) -> None:- transport = getattr(proc, "_transport", None)- close = getattr(transport, "close", None)- if not callable(close):- return- with contextlib.suppress(Exception):- close()- await asyncio.sleep(0)diff --git a/tests/unit/test_providers/test_agent_cli_contract.py b/tests/unit/test_providers/test_agent_cli_contract.pynew file mode 100644index 000000000..cf538a84a--- /dev/null+++ b/tests/unit/test_providers/test_agent_cli_contract.py@@ -0,0 +1,323 @@+"""Contract every ``AgentCliProvider`` subclass must meet.++A new agent backend joins by adding one ``Backend`` entry to ``BACKENDS``.+The subprocess is faked; no real CLI runs.+"""++from __future__ import annotations++import asyncio+import json+from collections.abc import Callable+from dataclasses import dataclass+from pathlib import Path+from typing import Any+from unittest.mock import AsyncMock, MagicMock++import pytest++from repowise.core.providers.llm.agent_cli import AgentCliProvider+from repowise.core.providers.llm.base import GeneratedResponse, ProviderError+from repowise.core.providers.llm.claude_cli import ClaudeCliProvider+from repowise.core.providers.llm.codex_cli import CodexCliProvider+from repowise.core.providers.llm.opencode import OpenCodeProvider+from repowise.core.providers.llm.registry import _BUILTIN_PROVIDERS+++@dataclass(frozen=True)+class Backend:+ cls: type[AgentCliProvider]+ model: str # a native slug the CLI receives after ``--model``+ # CLI output whose answer is the argument, with usage that parses to ``tokens``.+ success_stdout: Callable[[str], str]+ tokens: tuple[int, int, int] # parsed (input, output, cached)+ books_cost: bool+ # Flag that points the CLI at the repo; None means a per-call scratch cwd.+ repo_flag: str | None+ env: dict[str, str] | None # entries the subprocess env must carry+++def _jsonl(*events: dict[str, Any]) -> str:+ return "".join(json.dumps(event) + "\n" for event in events)+++def _claude_stdout(text: str) -> str:+ usage = {+ "input_tokens": 100,+ "output_tokens": 40,+ "cache_read_input_tokens": 30,+ "cache_creation_input_tokens": 10,+ }+ return _jsonl({"subtype": "success", "is_error": False, "result": text, "usage": usage})+++def _codex_stdout(text: str) -> str:+ return _jsonl(+ {"type": "item.completed", "item": {"type": "agent_message", "text": text}},+ {+ "type": "turn.completed",+ "usage": {"input_tokens": 120, "cached_input_tokens": 30, "output_tokens": 40},+ },+ )+++def _opencode_stdout(text: str) -> str:+ return _jsonl(+ {"type": "text", "part": {"text": text}},+ {+ "type": "step_finish",+ "part": {"tokens": {"input": 80, "output": 10, "cache": {"read": 20, "write": 0}}},+ },+ )+++BACKENDS = [+ Backend(+ ClaudeCliProvider,+ "claude-sonnet-4-6",+ _claude_stdout,+ # Prompt total: uncached + cache read + cache write.+ tokens=(140, 40, 30),+ books_cost=True,+ repo_flag=None,+ env=None,+ ),+ Backend(+ CodexCliProvider,+ "gpt-5.5",+ _codex_stdout,+ tokens=(120, 40, 30),+ books_cost=False,+ repo_flag="--cd",+ env=None,+ ),+ Backend(+ OpenCodeProvider,+ "deepseek/deepseek-v4-pro",+ _opencode_stdout,+ tokens=(80, 10, 20),+ books_cost=False,+ repo_flag="--dir",+ env={"OPENCODE_DISABLE_PROJECT_CONFIG": "true"},+ ),+]+++class FakeProcess:+ def __init__(+ self,+ *,+ returncode: int = 0,+ stdout: str = "",+ stderr: str = "",+ on_communicate: Any | None = None,+ ) -> None:+ self.returncode = returncode+ self._stdout = stdout+ self._stderr = stderr+ self._on_communicate = on_communicate+ self._transport = FakeTransport()+ self.stdin_input: bytes | None = None+ self.killed = False++ async def communicate(self, input: bytes | None = None) -> tuple[bytes, bytes]:+ self.stdin_input = input+ if self._on_communicate is not None:+ await self._on_communicate()+ return self._stdout.encode("utf-8"), self._stderr.encode("utf-8")++ def kill(self) -> None:+ self.killed = True++ async def wait(self) -> int:+ return self.returncode+++class FakeTransport:+ def __init__(self) -> None:+ self.closed = False++ def close(self) -> None:+ self.closed = True++[email protected](params=BACKENDS, ids=lambda b: b.cls.provider_name)+def backend(request, monkeypatch, tmp_path) -> Backend:+ exe = str(tmp_path / "bin" / request.param.cls.executable_name)+ monkeypatch.setattr(+ "shutil.which", lambda cmd: exe if cmd == request.param.cls.executable_name else None+ )+ return request.param+++def _make(backend: Backend, tmp_path) -> AgentCliProvider:+ # Every agent CLI provider is built with these kwargs by the registry.+ return backend.cls(model=backend.model, repo_path=tmp_path)+++def _fake_exec(monkeypatch, proc_factory: Callable[[], FakeProcess]) -> list[dict[str, Any]]:+ calls: list[dict[str, Any]] = []++ async def fake_exec(*args: str, **kwargs: Any) -> FakeProcess:+ proc = proc_factory()+ calls.append({"args": list(args), "kwargs": kwargs, "proc": proc})+ return proc++ monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)+ return calls+++def test_names_are_consistent(backend, tmp_path):+ provider = _make(backend, tmp_path)+ name = provider.provider_name+ assert _BUILTIN_PROVIDERS[name][1] == backend.cls.__name__+ assert provider.model_name == f"{name}/{backend.model}"+ # A persisted label round-trips instead of gaining a second prefix.+ assert backend.cls(model=provider.model_name, repo_path=tmp_path).model_name == (+ provider.model_name+ )+++def test_missing_executable_raises(backend, monkeypatch, tmp_path):+ monkeypatch.setattr("shutil.which", lambda _cmd: None)+ with pytest.raises(ProviderError) as caught:+ _make(backend, tmp_path)+ assert caught.value.provider == backend.cls.provider_name+++async def test_command_stdin_and_output(backend, monkeypatch, tmp_path):+ calls = _fake_exec(monkeypatch, lambda: FakeProcess(stdout=backend.success_stdout("answer")))++ result = await _make(backend, tmp_path).generate("system rules", "user context")++ assert isinstance(result, GeneratedResponse)+ assert result.content == "answer"+ assert (result.input_tokens, result.output_tokens, result.cached_tokens) == backend.tokens+ args = calls[0]["args"]+ assert args[0].endswith(backend.cls.executable_name)+ assert args[args.index("--model") + 1] == backend.model+ # Prompts are large, so they travel on stdin, never argv.+ assert calls[0]["kwargs"]["stdin"] == asyncio.subprocess.PIPE+ assert b"user context" in calls[0]["proc"].stdin_input+ assert not any("user context" in a for a in args)+ assert calls[0]["proc"]._transport.closed+++async def test_runs_against_the_repo_or_a_scratch_dir(backend, monkeypatch, tmp_path):+ calls = _fake_exec(monkeypatch, lambda: FakeProcess(stdout=backend.success_stdout("ok")))++ await _make(backend, tmp_path).generate("sys", "user")++ args, cwd = calls[0]["args"], calls[0]["kwargs"]["cwd"]+ if backend.repo_flag is None:+ # A neutral per-call directory, removed afterwards.+ assert cwd is not None and Path(cwd) != tmp_path.resolve()+ assert not Path(cwd).exists()+ else:+ assert args[args.index(backend.repo_flag) + 1] == str(tmp_path.resolve())+ assert cwd is None+++async def test_subprocess_env(backend, monkeypatch, tmp_path):+ calls = _fake_exec(monkeypatch, lambda: FakeProcess(stdout=backend.success_stdout("ok")))++ await _make(backend, tmp_path).generate("sys", "user")++ env = calls[0]["kwargs"]["env"]+ if backend.env is None:+ assert env is None # inherits the parent environment unchanged+ else:+ assert backend.env.items() <= env.items()+ if backend.cls is OpenCodeProvider:+ permissions = json.loads(env["OPENCODE_CONFIG_CONTENT"])["permission"]+ assert permissions["edit"] == permissions["bash"] == "deny"+++async def test_cost_booking(backend, monkeypatch, tmp_path):+ _fake_exec(monkeypatch, lambda: FakeProcess(stdout=backend.success_stdout("ok")))+ tracker = MagicMock(operation="doc_generation")+ tracker.record = AsyncMock(return_value=0.0)+ provider = _make(backend, tmp_path)+ provider._cost_tracker = tracker++ await provider.generate("sys", "user")++ if backend.books_cost:+ tracker.record.assert_awaited_once_with(+ model=provider.model_name,+ input_tokens=backend.tokens[0],+ output_tokens=backend.tokens[1],+ operation="doc_generation",+ file_path=None,+ )+ else:+ tracker.record.assert_not_awaited()+++async def test_nonzero_exit_raises_with_stderr_tail(backend, monkeypatch, tmp_path):+ stderr = "x" * 5_000 + " not logged in"+ _fake_exec(monkeypatch, lambda: FakeProcess(returncode=1, stderr=stderr))++ with pytest.raises(ProviderError) as caught:+ await _make(backend, tmp_path).generate("sys", "user")++ message = str(caught.value)+ assert caught.value.provider == backend.cls.provider_name+ assert message.endswith("not logged in")+ assert len(message) < len(stderr)+++async def test_timeout_kills_the_process(backend, monkeypatch, tmp_path):+ monkeypatch.setattr(backend.cls, "exec_timeout_seconds", lambda _self: 0.01)++ async def hang() -> None:+ await asyncio.sleep(1)++ calls = _fake_exec(monkeypatch, lambda: FakeProcess(on_communicate=hang))++ with pytest.raises(ProviderError, match="timed out"):+ await _make(backend, tmp_path).generate("sys", "user")++ assert calls[0]["proc"].killed+ assert calls[0]["proc"]._transport.closed+++async def test_cancellation_kills_the_process(backend, monkeypatch, tmp_path):+ started = asyncio.Event()++ async def block() -> None:+ started.set()+ await asyncio.Event().wait()++ calls = _fake_exec(monkeypatch, lambda: FakeProcess(on_communicate=block))++ task = asyncio.create_task(_make(backend, tmp_path).generate("sys", "user"))+ await started.wait()+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await task++ assert calls[0]["proc"].killed+++async def test_semaphore_bounds_concurrency(backend, monkeypatch, tmp_path):+ monkeypatch.setenv(backend.cls.concurrency_env, "2")+ active = 0+ max_active = 0++ async def track() -> None:+ nonlocal active, max_active+ active += 1+ max_active = max(max_active, active)+ await asyncio.sleep(0.01)+ active -= 1++ _fake_exec(+ monkeypatch,+ lambda: FakeProcess(stdout=backend.success_stdout("ok"), on_communicate=track),+ )+ provider = _make(backend, tmp_path)++ await asyncio.gather(*[provider.generate("sys", f"user {i}") for i in range(5)])++ assert max_active == 2