lictor 0.1.0__py3-none-any.whl

lictor/__init__.py

@@ -0,0 +1,8 @@
+"""Lictor: implementa escenarios Gherkin con un agente y los verifica de forma determinista."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("lictor")
+except PackageNotFoundError:  # a source tree that was never installed
+    __version__ = "0+desconocida"

lictor/adapters/agents/claude_cli.py

@@ -0,0 +1,394 @@
+"""Claude CLI adapter executing claude -p non-interactively."""
+
+import json
+import os
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any, Literal
+
+from lictor.application.ports import CommandRunner
+from lictor.domain.model import (
+    AgentResult,
+    AgentStatus,
+    AgentTask,
+    CostKind,
+    Health,
+    PermissionDenial,
+    Tokens,
+)
+from lictor.domain.rules import model_responded
+
+AuthKind = Literal["subscription", "api_key"]
+_HTTP_UNAUTHORIZED = 401
+_HTTP_TOO_MANY_REQUESTS = 429
+_AUTH_CHECK_TIMEOUT_S = 10
+_VERSION_TIMEOUT_S = 10
+_DEFAULT_BASE_TOOLS = ("Read", "Edit", "Write", "Glob", "Grep")
+_DEFAULT_DISALLOWED_TOOLS = (
+    "Bash(git:*)",
+    "Read(.lictor/**)",
+    "Edit(.lictor/**)",
+    "Write(.lictor/**)",
+)
+# Automatic memory is on even with no setting sources: it would let one call configure the next.
+_SETTINGS = json.dumps({"autoMemoryEnabled": False})
+_NO_AUTO_MEMORY = "CLAUDE_CODE_DISABLE_AUTO_MEMORY"
+# Where the CLI keeps its configuration and OAuth session: dropping it would log the agent out.
+_KEPT_CLAUDE_VARIABLES = frozenset({"CLAUDE_CONFIG_DIR"})
+# What the caller's virtual environment says, which is Lictor's and not the project's.
+_CALLER_VENV_VARIABLES = ("VIRTUAL_ENV", "VIRTUAL_ENV_PROMPT")
+
+
+@dataclass(frozen=True)
+class _Stream:
+    """What a call's stream of events says, read once."""
+
+    events: tuple[dict[str, Any], ...]
+    result: dict[str, Any] | None
+    rate_limit_status: str | None
+    cli_version: str
+
+
+class ClaudeCLI:
+    """Executes Claude Code CLI commands non-interactively through a command runner."""
+
+    def __init__(
+        self,
+        runner: CommandRunner,
+        auth: AuthKind = "subscription",
+        cli_binary: str = "claude",
+    ) -> None:
+        self.runner = runner
+        self.auth: AuthKind = auth
+        self.cli_binary: str = cli_binary
+
+    def health(self) -> Health:
+        """Verify CLI availability and authentication configuration."""
+        res = self.runner.run(
+            [self.cli_binary, "--version"], cwd=Path.cwd(), timeout_s=_VERSION_TIMEOUT_S
+        )
+        if not res.started:
+            return Health(
+                ok=False,
+                cli_version="",
+                auth_status="none",
+                message=f"No se pudo ejecutar el CLI '{self.cli_binary}': {res.stderr.strip()}",
+            )
+        if res.timed_out or res.returncode != 0:
+            return Health(
+                ok=False,
+                cli_version="",
+                auth_status="error",
+                message=f"El CLI devolvió el código {res.returncode}: {res.stderr.strip()}",
+            )
+        version_str = res.stdout.strip()
+
+        if self.auth == "subscription":
+            return self._subscription_health(version_str)
+
+        return Health(ok=True, cli_version=version_str, auth_status="api_key")
+
+    def _subscription_health(self, version: str) -> Health:
+        if os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN"):
+            return Health(
+                ok=False,
+                cli_version=version,
+                auth_status="api_key_override",
+                message=(
+                    "ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN present while auth is 'subscription'"
+                ),
+            )
+        logged_in = self._logged_in()
+        if logged_in is None:
+            return Health(
+                ok=False,
+                cli_version=version,
+                auth_status="error",
+                message="No se pudo comprobar la sesión del CLI",
+            )
+        if not logged_in:
+            return Health(
+                ok=False,
+                cli_version=version,
+                auth_status="none",
+                message="El CLI no tiene sesión iniciada",
+            )
+        return Health(ok=True, cli_version=version, auth_status="subscription")
+
+    def _logged_in(self) -> bool | None:
+        """Ask the CLI for its session, which costs no model call; None if it can't tell."""
+        res = self.runner.run(
+            [self.cli_binary, "auth", "status", "--json"],
+            cwd=Path.cwd(),
+            timeout_s=_AUTH_CHECK_TIMEOUT_S,
+            env=self._prepare_env(),
+        )
+        try:
+            data = json.loads(res.stdout)
+        except json.JSONDecodeError:
+            return None
+        logged_in = data.get("loggedIn") if isinstance(data, dict) else None
+        return logged_in if isinstance(logged_in, bool) else None
+
+    def _build_command(self, task: AgentTask) -> list[str]:
+        tools: list[str] = list(_DEFAULT_BASE_TOOLS)
+        for tool in task.allowed_tools:
+            if tool not in tools:
+                tools.append(tool)
+        # `--tools` takes names, not rules: `Bash(cmd:*)` makes Bash available, the rule limits it.
+        available = list(dict.fromkeys(tool.split("(", 1)[0] for tool in tools))
+
+        return [
+            self.cli_binary,
+            "-p",
+            task.prompt,
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--model",
+            task.model,
+            "--max-turns",
+            str(task.max_turns),
+            # Only the listed tools exist for the agent: no web, subagents, schedules or messages.
+            "--tools",
+            ",".join(available),
+            # `acceptEdits` also lets through shell commands it takes for edits, such as `touch`;
+            # `dontAsk` refuses whatever no rule allows.
+            "--permission-mode",
+            "dontAsk",
+            "--allowedTools",
+            *tools,
+            "--disallowedTools",
+            *_DEFAULT_DISALLOWED_TOOLS,
+            # No user, project or local settings: their hooks, permissions and CLAUDE.md would
+            # make the run depend on the machine, and the agent can write the project's ones.
+            "--setting-sources",
+            "",
+            "--settings",
+            _SETTINGS,
+            "--strict-mcp-config",
+            "--no-session-persistence",
+        ]
+
+    def _prepare_env(self) -> dict[str, str]:
+        """The caller's environment, without what belongs to the caller's own session.
+
+        Launched from a Claude Code session, the agent would inherit its variables
+        (`CLAUDECODE`, the session id, the effort...), and from Lictor's own virtual environment
+        the variables that name it.
+        """
+        env = {
+            name: value
+            for name, value in os.environ.items()
+            if not (name.startswith("CLAUDE") and name not in _KEPT_CLAUDE_VARIABLES)
+            and name not in _CALLER_VENV_VARIABLES
+        }
+        env[_NO_AUTO_MEMORY] = "1"
+        if self.auth == "subscription":
+            env.pop("ANTHROPIC_API_KEY", None)
+            env.pop("ANTHROPIC_AUTH_TOKEN", None)
+        env["DISABLE_AUTOUPDATER"] = "1"
+        return env
+
+    def _extract_spec_conflict(self, text: str) -> str | None:
+        last_conflict: str | None = None
+        for line in text.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("LICTOR: SPEC_CONFLICT"):
+                reason = stripped[len("LICTOR: SPEC_CONFLICT") :].strip()
+                last_conflict = reason if reason else "SPEC_CONFLICT"
+        return last_conflict
+
+    def _is_auth_failure(self, data: dict[str, Any]) -> bool:
+        if data.get("api_error_status") == _HTTP_UNAUTHORIZED:
+            return True
+        return data.get("terminal_reason") == "api_error" and self._logged_in() is False
+
+    def _determine_status(
+        self,
+        data: dict[str, Any],
+        rate_limit_status: str | None,
+        exit_code: int,
+    ) -> AgentStatus:
+        subtype = str(data.get("subtype", ""))
+        is_error = bool(data.get("is_error", False))
+        failed = is_error or exit_code != 0 or subtype == "error_during_execution"
+
+        if subtype == "error_max_turns":
+            return "max_turns"
+        if subtype == "rate_limited":
+            return "rate_limited"
+        if failed and data.get("api_error_status") == _HTTP_TOO_MANY_REQUESTS:
+            return "rate_limited"
+        if failed and rate_limit_status == "rejected":
+            return "rate_limited"
+        if is_error and self._is_auth_failure(data):
+            return "auth"
+        return "error" if failed else "ok"
+
+    def _cost_kind(self) -> CostKind:
+        return "notional_subscription" if self.auth == "subscription" else "estimated"
+
+    def _read_stream(self, stdout: str) -> _Stream:
+        """Read the events of the stream, skipping what isn't one."""
+        events: list[dict[str, Any]] = []
+        result: dict[str, Any] | None = None
+        rate_limit_status: str | None = None
+        cli_version = ""
+        for line in stdout.splitlines():
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(event, dict):
+                continue
+            events.append(event)
+            kind = event.get("type")
+            if kind == "result":
+                result = event
+            elif kind == "rate_limit_event":
+                info = event.get("rate_limit_info")
+                if isinstance(info, dict) and isinstance(info.get("status"), str):
+                    rate_limit_status = info["status"]
+            elif kind == "system" and event.get("subtype") == "init":
+                cli_version = str(event.get("claude_code_version") or "")
+        return _Stream(tuple(events), result, rate_limit_status, cli_version)
+
+    def _read_denials(self, data: dict[str, Any]) -> tuple[PermissionDenial, ...]:
+        denials = data.get("permission_denials")
+        if not isinstance(denials, list):
+            return ()
+        parsed: list[PermissionDenial] = []
+        for denial in denials:
+            if not isinstance(denial, dict):
+                parsed.append(PermissionDenial(tool="", target=str(denial)))
+                continue
+            tool_input = denial.get("tool_input")
+            fields = tool_input if isinstance(tool_input, dict) else {}
+            target = fields.get("command") or fields.get("file_path") or ""
+            parsed.append(
+                PermissionDenial(tool=str(denial.get("tool_name", "")), target=str(target))
+            )
+        return tuple(parsed)
+
+    def _parse_agent_data(
+        self,
+        data: dict[str, Any],
+        rate_limit_status: str | None,
+        exit_code: int,
+        duration_ms: int,
+        raw_path: Path,
+    ) -> AgentResult:
+        # error_max_turns has no `result`, only an `errors` list.
+        errors = data.get("errors")
+        fallback = "; ".join(str(e) for e in errors) if isinstance(errors, list) else ""
+        result_text = str(data.get("result") or fallback)
+
+        status = self._determine_status(data, rate_limit_status, exit_code)
+        spec_conflict = self._extract_spec_conflict(result_text)
+
+        usage = data.get("usage") or {}
+        tokens = Tokens(
+            input=int(usage.get("input_tokens", 0)),
+            output=int(usage.get("output_tokens", 0)),
+            cache_read=int(usage.get("cache_read_input_tokens", 0)),
+            cache_write=int(usage.get("cache_creation_input_tokens", 0)),
+        )
+
+        cost_usd = float(data["total_cost_usd"]) if data.get("total_cost_usd") is not None else None
+        reported_duration = data.get("duration_ms")
+        effective_duration = (
+            int(reported_duration) if reported_duration is not None else duration_ms
+        )
+
+        session_id = data.get("session_id")
+        return AgentResult(
+            status=status,
+            spec_conflict=spec_conflict,
+            text=result_text,
+            session_id=str(session_id) if session_id is not None else None,
+            num_turns=int(data.get("num_turns", 0)),
+            duration_ms=effective_duration,
+            tokens=tokens,
+            cost_usd=cost_usd,
+            cost_kind=self._cost_kind(),
+            raw_path=raw_path,
+            permission_denials=self._read_denials(data),
+            exit_code=exit_code,
+        )
+
+    def _save_stderr(self, raw_path: Path, stderr: str) -> Path | None:
+        """Keep stderr beside the raw stdout, which each call already has for itself."""
+        if not stderr:
+            return None
+        stderr_path = raw_path.with_suffix(".stderr.log")
+        stderr_path.write_text(stderr, encoding="utf-8", errors="replace")
+        return stderr_path
+
+    def run(self, task: AgentTask) -> AgentResult:
+        """Run claude -p for the given task and map the output to AgentResult."""
+        out = self.runner.run(
+            self._build_command(task),
+            cwd=task.cwd,
+            timeout_s=task.timeout_s,
+            env=self._prepare_env(),
+        )
+
+        task.raw_path.parent.mkdir(parents=True, exist_ok=True)
+        # Whatever the call left, even cut short by the timeout, is the evidence of what it did.
+        task.raw_path.write_text(out.stdout, encoding="utf-8")
+        stderr_path = self._save_stderr(task.raw_path, out.stderr)
+        stream = self._read_stream(out.stdout)
+        common: dict[str, Any] = {
+            "duration_ms": out.duration_ms,
+            "cost_kind": self._cost_kind(),
+            "raw_path": task.raw_path,
+            "stderr_path": stderr_path,
+            "cli_version": stream.cli_version,
+        }
+        if out.timed_out:
+            return self._timed_out(task, stream, common)
+
+        exit_code = out.returncode
+        if stream.result is None:
+            return AgentResult(
+                status="rate_limited" if stream.rate_limit_status == "rejected" else "error",
+                text=(
+                    f"El CLI no emitió el evento result (código de salida {exit_code}). "
+                    f"Stderr: {out.stderr}\nStdout: {out.stdout}"
+                ),
+                exit_code=exit_code,
+                **common,
+            )
+
+        return replace(
+            self._parse_agent_data(
+                data=stream.result,
+                rate_limit_status=stream.rate_limit_status,
+                exit_code=exit_code,
+                duration_ms=out.duration_ms,
+                raw_path=task.raw_path,
+            ),
+            stderr_path=stderr_path,
+            cli_version=stream.cli_version,
+        )
+
+    @staticmethod
+    def _timed_out(task: AgentTask, stream: _Stream, common: dict[str, Any]) -> AgentResult:
+        """A model that wrote something ran out of time; one that never answered is the backend.
+
+        A backend that rejected the call for its rate limit before answering is that limit.
+        """
+        if model_responded(stream.events):
+            return AgentResult(
+                status="timeout", text=f"Sin tiempo tras {task.timeout_s} s", **common
+            )
+        if stream.rate_limit_status == "rejected":
+            return AgentResult(
+                status="rate_limited",
+                text=f"Límite de uso alcanzado; el modelo no respondió en {task.timeout_s} s",
+                **common,
+            )
+        return AgentResult(
+            status="error", text=f"El modelo no respondió en {task.timeout_s} s", **common
+        )

lictor/adapters/agents/fake.py

@@ -0,0 +1,166 @@
+"""Deterministic FakeExecutor adapter for testing without LLM quota."""
+
+import json
+import re
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Literal
+
+from lictor.domain.model import (
+    AgentResult,
+    AgentRole,
+    AgentStatus,
+    AgentTask,
+    Health,
+    Tokens,
+)
+
+FAKE_CLI_VERSION = "fake-1.0.0"
+
+FakeMode = Literal["good", "fail", "cheat", "conflict", "rate_limit", "crash"]
+FakeEffect = Callable[[AgentTask, str | None, int], AgentStatus | None]
+_SCENARIO_TAG_RE = re.compile(r"([A-Z][A-Z0-9]*-[0-9]+)")
+
+
+class FakeExecutor:
+    """Deterministic agent test double simulating LLM runs with configured scripts and modes."""
+
+    def __init__(
+        self,
+        mode: FakeMode = "good",
+        *,
+        scenario_modes: dict[str, FakeMode] | None = None,
+        fixtures_dir: Path | None = None,
+        files_to_write: dict[str, dict[str, str]] | None = None,
+        crash_on_role: AgentRole | None = None,
+        crash_on_scenario: str | None = None,
+        tokens_per_call: Tokens | None = None,
+        cost_per_call: float = 0.005,
+        duration_ms: int = 150,
+        effect: FakeEffect | None = None,
+    ) -> None:
+        self.default_mode = mode
+        self.scenario_modes = scenario_modes or {}
+        self.fixtures_dir = Path(fixtures_dir) if fixtures_dir else None
+        self.files_to_write = files_to_write or {}
+        self.crash_on_role = crash_on_role
+        self.crash_on_scenario = crash_on_scenario
+        self.tokens_per_call = tokens_per_call or Tokens(
+            input=100, output=50, cache_read=200, cache_write=20
+        )
+        self.cost_per_call = cost_per_call
+        self.duration_ms = duration_ms
+        self.effect = effect
+        self.calls: list[str] = []
+
+    def health(self) -> Health:
+        """Return healthy fake status."""
+        return Health(
+            ok=True,
+            cli_version=FAKE_CLI_VERSION,
+            auth_status="subscription",
+            message=None,
+        )
+
+    def _detect_scenario_id(self, prompt: str) -> str | None:
+        match = _SCENARIO_TAG_RE.search(prompt)
+        return match.group(1) if match else None
+
+    def _apply_filesystem_effects(
+        self,
+        mode: FakeMode,
+        cwd: Path,
+        role: str | None = None,
+        scenario_id: str | None = None,
+    ) -> None:
+        keys_to_apply: list[str] = [mode]
+        if role:
+            keys_to_apply.append(f"{mode}:{role}")
+            keys_to_apply.append(role)
+        if scenario_id:
+            keys_to_apply.append(f"{mode}:{scenario_id}")
+            keys_to_apply.append(scenario_id)
+
+        for key in keys_to_apply:
+            mode_files = self.files_to_write.get(key, {})
+            for rel_path, content in mode_files.items():
+                dest = cwd / rel_path
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                dest.write_text(content, encoding="utf-8")
+
+        if self.fixtures_dir:
+            src_mode_dir = self.fixtures_dir / mode
+            if src_mode_dir.is_dir():
+                for p in src_mode_dir.rglob("*"):
+                    if p.is_file():
+                        rel = p.relative_to(src_mode_dir)
+                        dest = cwd / rel
+                        dest.parent.mkdir(parents=True, exist_ok=True)
+                        dest.write_bytes(p.read_bytes())
+
+    def _build_mode_outcome(self, mode: FakeMode) -> tuple[AgentStatus, str | None, str]:
+        if mode == "conflict":
+            spec_conflict = "Escenario imposible o contradictorio con la especificación"
+            return "ok", spec_conflict, f"Analizando...\nLICTOR: SPEC_CONFLICT {spec_conflict}"
+        if mode == "rate_limit":
+            return "rate_limited", None, "API rate limit reached"
+        return "ok", None, "Fake execution completed"
+
+    def run(self, task: AgentTask) -> AgentResult:
+        """Execute a deterministic fake agent run according to active mode."""
+        scenario_id = self._detect_scenario_id(task.prompt) if task.role == "implement" else None
+        mode: FakeMode = self.default_mode
+        if scenario_id and scenario_id in self.scenario_modes:
+            mode = self.scenario_modes[scenario_id]
+
+        if self.crash_on_role and task.role == self.crash_on_role:
+            raise RuntimeError(f"Simulated FakeExecutor crash on role {task.role}")
+
+        if self.crash_on_scenario and scenario_id and scenario_id == self.crash_on_scenario:
+            raise RuntimeError(f"Simulated FakeExecutor crash on scenario {scenario_id}")
+
+        if mode == "crash":
+            raise RuntimeError("Simulated FakeExecutor crash")
+
+        call_key = scenario_id or task.role
+        self.calls.append(call_key)
+        self._apply_filesystem_effects(mode, task.cwd, role=task.role, scenario_id=scenario_id)
+        status, spec_conflict, result_text = self._build_mode_outcome(mode)
+        if self.effect is not None:
+            status = self.effect(task, scenario_id, self.calls.count(call_key)) or status
+
+        tokens = self.tokens_per_call if status != "rate_limited" else Tokens()
+        cost = self.cost_per_call if status != "rate_limited" else 0.0
+
+        raw_data: dict[str, Any] = {
+            "mode": mode,
+            "status": status,
+            "spec_conflict": spec_conflict,
+            "result": result_text,
+            "num_turns": 1 if status != "rate_limited" else 0,
+            "duration_ms": self.duration_ms,
+            "usage": {
+                "input_tokens": tokens.input,
+                "output_tokens": tokens.output,
+                "cache_read_input_tokens": tokens.cache_read,
+                "cache_creation_input_tokens": tokens.cache_write,
+            },
+            "total_cost_usd": cost,
+        }
+
+        task.raw_path.parent.mkdir(parents=True, exist_ok=True)
+        task.raw_path.write_text(json.dumps(raw_data, indent=2), encoding="utf-8")
+
+        return AgentResult(
+            status=status,
+            spec_conflict=spec_conflict,
+            text=result_text,
+            session_id="fake-session-id",
+            num_turns=1 if status != "rate_limited" else 0,
+            duration_ms=self.duration_ms,
+            tokens=tokens,
+            cost_usd=cost,
+            cost_kind="notional_subscription",
+            raw_path=task.raw_path,
+            cli_version=FAKE_CLI_VERSION,
+        )