Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
new file mode 100644
index 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, stderr
diff --git a/packages/core/src/repowise/core/providers/llm/claude_cli.py b/packages/core/src/repowise/core/providers/llm/claude_cli.py
index 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 asyncio
import contextlib
import json
-import os
-import re
-import shutil
import tempfile
+from collections.abc import Iterator
from pathlib import Path
from typing import Any
import 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_MODEL
def _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 = True
def __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 it
def supported_reasoning_modes(self) -> tuple[ReasoningMode, ...]:
return _SUPPORTED_REASONING_MODES
def 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 = None
with 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_tokens
stop_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 response
diff --git a/packages/core/src/repowise/core/providers/llm/codex_cli.py b/packages/core/src/repowise/core/providers/llm/codex_cli.py
index 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 contextlib
import json
-import shutil
import subprocess
from dataclasses import dataclass
from functools import lru_cache
-from pathlib import Path
from 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 RateLimiter
from 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 it
def 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"] = True
return 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.py
index 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_CO
from __future__ import annotations
-import asyncio
-import contextlib
import json
import os
import re
-import shutil
import subprocess
import uuid
-from collections.abc import Iterator
-from functools import lru_cache
-from pathlib import Path
+from functools import lru_cache, partial
from 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 RateLimiter
from 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 it
def 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.py
new file mode 100644
index 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