codexloop 0.1.0__py3-none-any.whl

codexloop/infrastructure/agent/process.py

@@ -0,0 +1,208 @@
+"""Supervised ``codex`` subprocess: concurrent pumps and process-group teardown.
+
+``ProcessResult.stderr_tail`` is the last :data:`STDERR_TAIL_BYTES` (8 KiB) of
+stderr, not the full stream. Oversized stdout lines are truncated to
+``max_line_bytes`` and counted in ``truncated_lines``; they never raise and
+never accumulate past that ceiling.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+import anyio
+from anyio import EndOfStream
+from anyio.abc import ByteReceiveStream, Process
+
+from codexloop.domain.errors import CodexBinaryError
+
+STDERR_TAIL_BYTES: Final[int] = 8 * 1024
+_KILL_GRACE_SECONDS: Final[float] = 0.5
+_RECEIVE_CHUNK: Final[int] = 8192
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessResult:
+    stdout_lines: list[str]
+    stderr_tail: str
+    exit_code: int
+    truncated_lines: int
+
+
+async def run_codex(
+    argv: Sequence[str],
+    *,
+    cwd: str | Path,
+    env: Mapping[str, str],
+    timeout: float,
+    max_line_bytes: int,
+) -> ProcessResult:
+    """Run ``argv`` (no shell) with concurrent stdout/stderr pumps.
+
+    The child is started in its own session (``start_new_session=True``) so
+    timeout and cancellation send ``SIGTERM`` then ``SIGKILL`` to the whole
+    process group. Stdin is ``DEVNULL`` (not a TTY; reads return EOF).
+    """
+    if not argv:
+        raise CodexBinaryError("argv must be a non-empty list")
+
+    stdout_collector = _StdoutCollector(max_line_bytes)
+    stderr_collector = _StderrTail()
+    # Child stdin is not a TTY; reads return EOF immediately.
+    devnull_fd = os.open(os.devnull, os.O_RDONLY)
+    try:
+        process = await anyio.open_process(
+            list(argv),
+            stdin=devnull_fd,
+            cwd=os.fspath(cwd),
+            env=dict(env),
+            start_new_session=True,
+        )
+    finally:
+        os.close(devnull_fd)
+    try:
+        with anyio.fail_after(timeout):
+            async with anyio.create_task_group() as tg:
+                if process.stdout is not None:  # pragma: no branch
+                    tg.start_soon(_pump_stdout, process.stdout, stdout_collector, max_line_bytes)
+                if process.stderr is not None:  # pragma: no branch
+                    tg.start_soon(_pump_stderr, process.stderr, stderr_collector)
+                await process.wait()
+    except TimeoutError:
+        await _terminate_group(process)
+        raise CodexBinaryError(f"timed out after {timeout}s") from None
+    except BaseException:
+        await _terminate_group(process)
+        raise
+    else:
+        code = process.returncode
+        return ProcessResult(
+            stdout_lines=stdout_collector.lines,
+            stderr_tail=stderr_collector.text(),
+            exit_code=0 if code is None else code,
+            truncated_lines=stdout_collector.truncated_lines,
+        )
+    finally:
+        with anyio.CancelScope(shield=True):
+            await process.aclose()
+
+
+async def _pump_stdout(
+    stream: ByteReceiveStream,
+    collector: _StdoutCollector,
+    max_line_bytes: int,
+) -> None:
+    chunk_size = max(1, min(_RECEIVE_CHUNK, max_line_bytes))
+    try:
+        while True:
+            try:
+                chunk = await stream.receive(chunk_size)
+            except EndOfStream:
+                break
+            collector.feed(chunk)
+    finally:
+        collector.flush()
+
+
+async def _pump_stderr(stream: ByteReceiveStream, collector: _StderrTail) -> None:
+    while True:
+        try:
+            chunk = await stream.receive(_RECEIVE_CHUNK)
+        except EndOfStream:
+            break
+        collector.feed(chunk)
+
+
+async def _terminate_group(process: Process) -> None:
+    pid = process.pid
+    with anyio.CancelScope(shield=True):
+        _signal_group(pid, signal.SIGTERM)
+        with anyio.move_on_after(_KILL_GRACE_SECONDS):
+            await process.wait()
+        _signal_group(pid, signal.SIGKILL)
+        with anyio.move_on_after(2.0):
+            await process.wait()
+
+
+def _signal_group(pid: int, sig: int) -> None:
+    try:
+        os.killpg(pid, sig)
+    except ProcessLookupError:  # pragma: no cover — process already gone
+        return
+    except OSError:  # pragma: no cover — fall back to kill(pid)
+        try:
+            os.kill(pid, sig)
+        except (ProcessLookupError, OSError):
+            return
+
+
+class _StdoutCollector:
+    """Bound stdout to ``max_line_bytes`` per line; skip overflow until newline."""
+
+    def __init__(self, max_line_bytes: int) -> None:
+        self.max_line_bytes = max_line_bytes
+        self.lines: list[str] = []
+        self.truncated_lines = 0
+        self._buf = bytearray()
+        self._skipping = False
+
+    def feed(self, chunk: bytes) -> None:
+        offset = 0
+        length = len(chunk)
+        while offset < length:
+            if self._skipping:
+                nl = chunk.find(b"\n", offset)
+                if nl == -1:
+                    return
+                self._skipping = False
+                offset = nl + 1
+                continue
+            nl = chunk.find(b"\n", offset)
+            end = length if nl == -1 else nl
+            piece = chunk[offset:end]
+            space = self.max_line_bytes - len(self._buf)
+            if len(piece) > space:
+                if space > 0:
+                    self._buf.extend(piece[:space])
+                self._emit(truncated=True)
+                if nl == -1:
+                    self._skipping = True
+                    return
+                offset = nl + 1
+                continue
+            self._buf.extend(piece)
+            if nl == -1:
+                return
+            self._emit(truncated=False)
+            offset = nl + 1
+
+    def flush(self) -> None:
+        if self._buf:
+            self._emit(truncated=False)
+
+    def _emit(self, *, truncated: bool) -> None:
+        if truncated:
+            self.truncated_lines += 1
+        self.lines.append(bytes(self._buf).decode("utf-8", errors="replace"))
+        self._buf.clear()
+
+
+class _StderrTail:
+    """Rolling last-``STDERR_TAIL_BYTES`` of stderr."""
+
+    def __init__(self) -> None:
+        self._buf = bytearray()
+
+    def feed(self, chunk: bytes) -> None:
+        self._buf.extend(chunk)
+        extra = len(self._buf) - STDERR_TAIL_BYTES
+        if extra > 0:
+            del self._buf[:extra]
+
+    def text(self) -> str:
+        return bytes(self._buf).decode("utf-8", errors="replace")

codexloop/infrastructure/agent/schema.py

@@ -0,0 +1,31 @@
+"""JSON Schema for structured completion verdicts (R12)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Final
+
+COMPLETION_OUTPUT_SCHEMA: Final[dict[str, object]] = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "CodexloopCompletionVerdict",
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["complete", "remaining_work", "blocked_on", "summary"],
+    "properties": {
+        "complete": {"type": "boolean"},
+        "remaining_work": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+        "blocked_on": {"type": ["string", "null"]},
+        "summary": {"type": "string"},
+    },
+}
+
+
+def write_output_schema(path: str | Path) -> Path:
+    """Write the completion JSON Schema to ``path`` and return that path."""
+    dest = Path(path)
+    dest.write_text(json.dumps(COMPLETION_OUTPUT_SCHEMA, indent=2) + "\n", encoding="utf-8")
+    return dest

codexloop/infrastructure/agent/scripted.py

@@ -0,0 +1,201 @@
+"""JSON-scripted AgentGateway / CapacityProbe for system-live tests.
+
+Activated only via the composition-root test gate in ``bootstrap`` when both
+``CODEXLOOP_ALLOW_TEST_AGENT=1`` and ``CODEXLOOP_TEST_AGENT_SCRIPT`` are set.
+Not a user-facing feature.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any
+
+from codexloop.application.dto import ProbeResult, TurnOutcome
+from codexloop.application.ports import PermissionMode
+from codexloop.domain.capacity import PlanWindows, RateLimitWindow
+from codexloop.domain.classify import classify
+from codexloop.domain.model_profile import ModelEffortProfile
+from codexloop.domain.signals import TurnSignals
+
+ALLOW_TEST_AGENT_ENV = "CODEXLOOP_ALLOW_TEST_AGENT"
+TEST_AGENT_SCRIPT_ENV = "CODEXLOOP_TEST_AGENT_SCRIPT"
+
+
+@dataclass(frozen=True, slots=True)
+class ScriptedTurn:
+    signals: TurnSignals = field(default_factory=TurnSignals)
+    thread_id: str | None = "scripted-session"
+    cost_dollars: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class AgentScript:
+    probes: tuple[TurnSignals, ...]
+    turns: tuple[ScriptedTurn, ...]
+
+
+class ScriptedAgentGateway:
+    """Replays scripted turns for system harnesses."""
+
+    def __init__(self, script: Sequence[ScriptedTurn]) -> None:
+        self._script = list(script)
+        self.sent_prompts: list[str] = []
+        self.closed = False
+        self.profiles: list[ModelEffortProfile] = []
+        self.permission_modes: list[PermissionMode] = []
+        self.cwds: list[str] = []
+        self.resource_updates: list[Mapping[str, object]] = []
+        self.tool_resolutions: list[tuple[str, bool, str]] = []
+
+    async def send_turn(self, prompt: str) -> TurnOutcome:
+        self.sent_prompts.append(prompt)
+        if not self._script:
+            raise IndexError(f"ScriptedAgentGateway: no turns left (prompt={prompt!r})")
+        turn = self._script.pop(0)
+        return TurnOutcome(
+            signals=turn.signals,
+            thread_id=turn.thread_id,
+            cost_dollars=turn.cost_dollars,
+        )
+
+    async def close(self) -> None:
+        self.closed = True
+
+    async def set_profile(self, profile: ModelEffortProfile) -> None:
+        self.profiles.append(profile)
+
+    async def set_permission_mode(self, mode: PermissionMode) -> None:
+        self.permission_modes.append(mode)
+
+    async def set_cwd(self, path: str) -> None:
+        self.cwds.append(path)
+
+    async def set_session_resources(self, resources: Mapping[str, object]) -> None:
+        self.resource_updates.append(resources)
+
+    def resolve_tool_approval(self, request_id: str, *, allow: bool, reason: str = "") -> bool:
+        self.tool_resolutions.append((request_id, allow, reason))
+        return allow
+
+
+class ScriptedCapacityProbe:
+    def __init__(self, script: Sequence[TurnSignals]) -> None:
+        self._script = list(script)
+        self.calls = 0
+
+    async def probe(self) -> ProbeResult:
+        self.calls += 1
+        if not self._script:
+            raise IndexError("ScriptedCapacityProbe: no probes left in script")
+        signals = self._script.pop(0)
+        return ProbeResult(outcome=classify(signals), snapshot=signals.plan_windows)
+
+
+def load_agent_script(path: Path | str) -> AgentScript:
+    raw = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError("agent script root must be a JSON object")
+    probes_raw = raw.get("probes", [{}])
+    turns_raw = raw.get("turns", [])
+    if not isinstance(probes_raw, list) or not isinstance(turns_raw, list):
+        raise ValueError("agent script 'probes' and 'turns' must be arrays")
+    if not turns_raw:
+        raise ValueError("agent script must include at least one turn")
+    probes = tuple(_parse_signals(item) for item in probes_raw)
+    turns = tuple(_parse_turn(item) for item in turns_raw)
+    return AgentScript(probes=probes, turns=turns)
+
+
+def resolve_test_agent_from_env() -> tuple[ScriptedAgentGateway, ScriptedCapacityProbe] | None:
+    """Return scripted adapters when the test gate is fully enabled.
+
+    Raises ``RuntimeError`` if the script path is set without the allow flag.
+    """
+    allow = os.environ.get(ALLOW_TEST_AGENT_ENV, "").strip()
+    script_path = os.environ.get(TEST_AGENT_SCRIPT_ENV, "").strip()
+    if script_path and allow not in {"1", "true", "TRUE", "yes", "YES"}:
+        raise RuntimeError(
+            f"{TEST_AGENT_SCRIPT_ENV} is set but {ALLOW_TEST_AGENT_ENV}=1 is "
+            "required. The scripted agent is test-only and will not activate "
+            "without the allow flag."
+        )
+    if not script_path:
+        return None
+    if allow not in {"1", "true", "TRUE", "yes", "YES"}:  # pragma: no cover — raised above
+        return None
+    script = load_agent_script(script_path)
+    return ScriptedAgentGateway(script.turns), ScriptedCapacityProbe(script.probes)
+
+
+def _parse_turn(item: object) -> ScriptedTurn:
+    if not isinstance(item, dict):
+        raise ValueError("each turn must be a JSON object")
+    signals = _parse_signals(item.get("signals", {}))
+    thread_id = item.get("thread_id", "scripted-session")
+    return ScriptedTurn(
+        signals=signals,
+        thread_id=None if thread_id is None else str(thread_id),
+        cost_dollars=float(item.get("cost_dollars", 0.0)),
+    )
+
+
+def _parse_signals(item: object) -> TurnSignals:
+    if isinstance(item, dict) and "signals" in item and set(item) <= {"signals"}:
+        item = item["signals"]
+    if not isinstance(item, dict):
+        raise ValueError("signals must be a JSON object")
+    data: dict[str, Any] = dict(item)
+    if "plan_windows" in data:
+        data["plan_windows"] = _parse_plan_windows(data["plan_windows"])
+    known = {f.name for f in fields(TurnSignals)}
+    filtered = {k: v for k, v in data.items() if k in known}
+    return TurnSignals(**filtered)
+
+
+def _parse_plan_windows(raw: object) -> PlanWindows | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        raise ValueError("plan_windows must be an object")
+    return PlanWindows(
+        primary=_parse_window(raw.get("primary")),
+        secondary=_parse_window(raw.get("secondary")),
+        plan_type=None if raw.get("plan_type") is None else str(raw["plan_type"]),
+        limit_reached=(
+            None
+            if raw.get("rate_limit_reached_type") is None
+            else str(raw["rate_limit_reached_type"])
+        ),
+    )
+
+
+def _parse_window(raw: object) -> RateLimitWindow | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        return None
+    minutes = raw.get("window_minutes")
+    if not isinstance(minutes, int):
+        return None
+    used = raw.get("used_percent")
+    return RateLimitWindow(
+        used_percent=float(used) if isinstance(used, int | float) else None,
+        window_minutes=minutes,
+        resets_at=None,
+    )
+
+
+__all__ = [
+    "ALLOW_TEST_AGENT_ENV",
+    "TEST_AGENT_SCRIPT_ENV",
+    "AgentScript",
+    "ScriptedAgentGateway",
+    "ScriptedCapacityProbe",
+    "ScriptedTurn",
+    "load_agent_script",
+    "resolve_test_agent_from_env",
+]

codexloop/infrastructure/agent/translate.py

@@ -0,0 +1,120 @@
+"""JSONL events + process result → TurnSignals."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from datetime import datetime
+from typing import assert_never
+
+from codexloop.domain.capacity import PlanWindows
+from codexloop.domain.signals import TurnSignals
+from codexloop.infrastructure.agent.events import (
+    CodexEvent,
+    ErrorEvent,
+    ErrorPayload,
+    ItemCompleted,
+    ItemStarted,
+    RateLimitsUpdated,
+    ThreadStarted,
+    TurnCompleted,
+    TurnFailed,
+    TurnStarted,
+    UnknownEvent,
+)
+
+
+def to_turn_signals(
+    events: Iterable[CodexEvent | None],
+    *,
+    exit_code: int,
+    stderr_tail: str,
+    now: datetime,
+) -> TurnSignals:
+    """Fold a parsed event stream plus process result into classification signals.
+
+    ``exit_code`` and ``stderr_tail`` are always taken from the process result so a
+    malformed or truncated JSONL stream still yields a classifiable outcome.
+    """
+    _ = now
+    error_code: str | None = None
+    error_type: str | None = None
+    http_status: int | None = None
+    retry_after_s: float | None = None
+    plan_windows: PlanWindows | None = None
+    completed = False
+    failed = False
+    final_message: str | None = None
+    usage: object | None = None
+
+    for event in events:
+        if event is None:
+            continue
+        match event:
+            case TurnCompleted(usage=turn_usage):
+                completed = True
+                usage = turn_usage
+            case TurnFailed(error=error):
+                failed = True
+                error_code, error_type, http_status, retry_after_s = _merge_error(
+                    error, error_code, error_type, http_status, retry_after_s
+                )
+            case ErrorEvent(error=error):
+                error_code, error_type, http_status, retry_after_s = _merge_error(
+                    error, error_code, error_type, http_status, retry_after_s
+                )
+            case RateLimitsUpdated(plan_windows=windows):
+                if windows is not None:
+                    plan_windows = windows
+            case ItemCompleted(item=item):
+                text = _agent_message_text(item)
+                if text is not None:
+                    final_message = text
+            case ThreadStarted() | TurnStarted() | ItemStarted() | UnknownEvent():
+                continue
+            case _:  # pragma: no cover — exhaustive CodexEvent union
+                assert_never(event)
+
+    return TurnSignals(
+        error_code=error_code,
+        error_type=error_type,
+        http_status=http_status,
+        retry_after_s=retry_after_s,
+        plan_windows=plan_windows,
+        completed=completed,
+        failed=failed,
+        final_message=final_message,
+        usage=usage,
+        exit_code=exit_code,
+        stderr_tail=stderr_tail,
+    )
+
+
+def _merge_error(
+    error: ErrorPayload | None,
+    error_code: str | None,
+    error_type: str | None,
+    http_status: int | None,
+    retry_after_s: float | None,
+) -> tuple[str | None, str | None, int | None, float | None]:
+    if error is None:
+        return error_code, error_type, http_status, retry_after_s
+    extra = getattr(error, "retry_after_s", None)
+    if isinstance(extra, int | float) and not isinstance(extra, bool):
+        retry_after_s = float(extra)
+    return (
+        error.code if error.code is not None else error_code,
+        error.type if error.type is not None else error_type,
+        error.status if error.status is not None else http_status,
+        retry_after_s,
+    )
+
+
+def _agent_message_text(item: Mapping[str, object] | None) -> str | None:
+    if item is None:
+        return None
+    if item.get("type") != "agent_message":
+        return None
+    text = item.get("text")
+    if isinstance(text, str):
+        return text
+    return None

codexloop/infrastructure/api/__init__.py

@@ -0,0 +1,26 @@
+"""Generated OpenAI SDK REST CLI (M4)."""
+
+from __future__ import annotations
+
+from codexloop.infrastructure.api.binder import build_api_typer_app
+from codexloop.infrastructure.api.gateway import OpenAIApiGateway, default_gateway
+from codexloop.infrastructure.api.introspect import (
+    LOCAL_HELPER_PATHS,
+    SDK_VERSION,
+    EndpointSpec,
+    discover_surface,
+    method_by_path,
+    resolve_callable,
+)
+
+__all__ = [
+    "LOCAL_HELPER_PATHS",
+    "SDK_VERSION",
+    "EndpointSpec",
+    "OpenAIApiGateway",
+    "build_api_typer_app",
+    "default_gateway",
+    "discover_surface",
+    "method_by_path",
+    "resolve_callable",
+]