codexloop 0.1.0__py3-none-any.whl

codexloop/cli/render.py

@@ -0,0 +1,39 @@
+"""Human-readable rendering of CLI results."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+
+from codexloop.application.dto import RunResult
+from codexloop.domain.session import ThreadRef
+
+
+def render_result(result: RunResult) -> str:
+    status = "done" if result.success else result.reason
+    thread = result.thread_id or "-"
+    return f"{status}  turns={result.turns}  thread={thread}"
+
+
+def render_threads(threads: Sequence[ThreadRef]) -> str:
+    if not threads:
+        return "No threads recorded."
+    return "\n".join(
+        f"{ref.thread_id}\t{ref.model}\t{ref.cwd}\t{ref.started_at.isoformat()}" for ref in threads
+    )
+
+
+def render_runs(records: Sequence[Mapping[str, object]]) -> str:
+    if not records:
+        return "No runs."
+    return "\n".join(str(record.get("run_id", "-")) for record in records)
+
+
+def render_status(record: Mapping[str, object] | None) -> str:
+    if record is None:
+        return "No runs."
+    return json.dumps(dict(record), indent=2, default=str)
+
+
+def render_logs(text: str) -> str:
+    return text if text else "No logs."

codexloop/domain/__init__.py

@@ -0,0 +1,26 @@
+"""Pure domain layer — stdlib only."""
+
+from codexloop.domain.error_codes import ErrorClass, classify_code
+from codexloop.domain.errors import (
+    AuthError,
+    BudgetExceeded,
+    CapacityError,
+    CodexBinaryError,
+    CodexloopError,
+    CodexProtocolError,
+    ConfigurationError,
+    WaitDeadlineExceeded,
+)
+
+__all__ = [
+    "AuthError",
+    "BudgetExceeded",
+    "CapacityError",
+    "CodexBinaryError",
+    "CodexloopError",
+    "CodexProtocolError",
+    "ConfigurationError",
+    "ErrorClass",
+    "WaitDeadlineExceeded",
+    "classify_code",
+]

codexloop/domain/approval.py

@@ -0,0 +1,38 @@
+"""Approval policy × sandbox mode. Defaults never wait and stay in-workspace."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from codexloop.domain.errors import ConfigurationError
+
+
+class ApprovalPolicy(StrEnum):
+    NEVER = "never"
+    ON_REQUEST = "on-request"
+    ON_FAILURE = "on-failure"
+    UNTRUSTED = "untrusted"
+
+
+class SandboxMode(StrEnum):
+    READ_ONLY = "read-only"
+    WORKSPACE_WRITE = "workspace-write"
+    DANGER_FULL_ACCESS = "danger-full-access"
+
+
+DEFAULT_APPROVAL = ApprovalPolicy.NEVER
+DEFAULT_SANDBOX = SandboxMode.WORKSPACE_WRITE
+
+
+def validate(
+    policy: ApprovalPolicy,
+    sandbox: SandboxMode,
+    *,
+    allow_dangerous: bool = False,
+) -> None:
+    """Raise unless ``danger-full-access`` is paired with ``allow_dangerous=True``."""
+    if sandbox is SandboxMode.DANGER_FULL_ACCESS and not allow_dangerous:
+        raise ConfigurationError(
+            f"sandbox mode {sandbox.value} requires allow_dangerous=True"
+            f" (approval_policy={policy.value})"
+        )

codexloop/domain/backoff.py

@@ -0,0 +1,34 @@
+"""Pure exponential backoff with injected jitter."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from datetime import timedelta
+
+
+def backoff(
+    attempt: int,
+    *,
+    base: timedelta,
+    ceiling: timedelta,
+    jitter_ratio: float,
+    rand: Callable[[], float],
+) -> timedelta:
+    """Return ``min(ceiling, base * 2^attempt)`` scaled by jitter from ``rand``.
+
+    ``rand`` must return a float in ``[0, 1]``. Jitter maps that onto
+    ``[1 - jitter_ratio, 1 + jitter_ratio]``. The result is never negative and
+    never exceeds ``ceiling``.
+    """
+    ceiling_s = max(ceiling.total_seconds(), 0.0)
+    base_s = max(base.total_seconds(), 0.0)
+    try:
+        exponential = math.ldexp(base_s, attempt)
+    except (OverflowError, ValueError):
+        exponential = math.inf
+    delay_s = min(ceiling_s, exponential)
+    factor = (1.0 - jitter_ratio) + (2.0 * jitter_ratio * rand())
+    jittered = delay_s * factor
+    clamped = min(max(jittered, 0.0), ceiling_s)
+    return timedelta(seconds=clamped)

codexloop/domain/budget.py

@@ -0,0 +1,56 @@
+"""Turn / dollar / wall-clock budgets and a monotonic ledger."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+
+from codexloop.domain.errors import ConfigurationError
+
+_ZERO = timedelta(0)
+
+
+@dataclass(frozen=True, slots=True)
+class Budget:
+    max_turns: int | None
+    max_dollars: float | None
+    max_wall_clock: timedelta | None
+
+
+class BudgetLedger:
+    """Accumulates usage against a :class:`Budget`. Counters never decrease."""
+
+    def __init__(self, budget: Budget) -> None:
+        self._budget = budget
+        self._turns = 0
+        self._dollars = 0.0
+        self._elapsed = _ZERO
+
+    @property
+    def turns(self) -> int:
+        return self._turns
+
+    @property
+    def dollars(self) -> float:
+        return self._dollars
+
+    @property
+    def elapsed(self) -> timedelta:
+        return self._elapsed
+
+    def record(self, turns: int = 0, dollars: float = 0.0, elapsed: timedelta = _ZERO) -> None:
+        if turns < 0 or dollars < 0 or elapsed < _ZERO:
+            raise ConfigurationError("budget ledger cannot decrease")
+        self._turns += turns
+        self._dollars += dollars
+        self._elapsed += elapsed
+
+    def exceeded(self) -> str | None:
+        budget = self._budget
+        if budget.max_turns is not None and self._turns >= budget.max_turns:
+            return "turns"
+        if budget.max_dollars is not None and self._dollars >= budget.max_dollars:
+            return "dollars"
+        if budget.max_wall_clock is not None and self._elapsed >= budget.max_wall_clock:
+            return "wall_clock"
+        return None

codexloop/domain/capacity.py

@@ -0,0 +1,81 @@
+"""Capacity value objects and waitability for plan windows / rate limits."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import assert_never
+
+
+@dataclass(frozen=True, slots=True)
+class RateLimitWindow:
+    used_percent: float | None
+    window_minutes: int
+    resets_at: datetime | None
+
+    @property
+    def remaining_percent(self) -> float | None:
+        if self.used_percent is None:
+            return None
+        return max(0.0, min(100.0, 100.0 - self.used_percent))
+
+
+@dataclass(frozen=True, slots=True)
+class PlanWindows:
+    primary: RateLimitWindow | None
+    secondary: RateLimitWindow | None
+    plan_type: str | None
+    limit_reached: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class Available:
+    plan_windows: PlanWindows | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ThrottleExhausted:
+    retry_after: timedelta | None = None
+    aggressive: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class WindowExhausted:
+    resets_at: datetime | None = None
+    window: str = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class QuotaExhausted:
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class AuthFailed:
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class TransientBackendError:
+    retry_after: timedelta | None = None
+
+
+CapacityState = (
+    Available
+    | ThrottleExhausted
+    | WindowExhausted
+    | QuotaExhausted
+    | AuthFailed
+    | TransientBackendError
+)
+
+
+def is_waitable(state: CapacityState) -> bool:
+    """Return False only for billing walls and auth failures."""
+    match state:
+        case QuotaExhausted() | AuthFailed():
+            return False
+        case Available() | ThrottleExhausted() | WindowExhausted() | TransientBackendError():
+            return True
+        case _:  # pragma: no cover — match is exhaustive over CapacityState
+            assert_never(state)

codexloop/domain/classify.py

@@ -0,0 +1,98 @@
+"""Classify TurnSignals into a CapacityState (body first, status second)."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from codexloop.domain.capacity import (
+    AuthFailed,
+    Available,
+    CapacityState,
+    PlanWindows,
+    QuotaExhausted,
+    ThrottleExhausted,
+    TransientBackendError,
+    WindowExhausted,
+)
+from codexloop.domain.error_codes import ErrorClass, classify_code
+from codexloop.domain.signals import TurnSignals
+
+
+def classify(signals: TurnSignals) -> CapacityState:
+    """Map turn signals to a capacity state using the documented ladder.
+
+    Completion claims, Retry-After headers, and high ``used_percent`` never
+    outrank a body-level billing or auth marker. HTTP 429 is consulted only
+    after ``error.code`` / ``error.type``.
+    """
+    code_cls = classify_code(signals.error_code, None)
+    type_cls = classify_code(None, signals.error_type)
+    status = signals.http_status
+
+    if _has(ErrorClass.AUTH, code_cls, type_cls) or status == 401:
+        return AuthFailed(reason=_reason(signals, ErrorClass.AUTH, "unauthorized"))
+
+    if _has(ErrorClass.QUOTA, code_cls, type_cls):
+        return QuotaExhausted(reason=_reason(signals, ErrorClass.QUOTA, "quota"))
+
+    if _has(ErrorClass.WINDOW, code_cls, type_cls):
+        resets_at, window = _window_from_plan(signals.plan_windows)
+        return WindowExhausted(resets_at=resets_at, window=window)
+
+    if _has(ErrorClass.THROTTLE, code_cls, type_cls):
+        return ThrottleExhausted(
+            retry_after=_retry_after(signals.retry_after_s),
+            aggressive=_is_slow_down(signals),
+        )
+
+    if _has(ErrorClass.TRANSIENT, code_cls, type_cls):
+        return TransientBackendError(retry_after=_retry_after(signals.retry_after_s))
+
+    if _has(ErrorClass.FATAL, code_cls, type_cls):
+        return Available(plan_windows=signals.plan_windows)
+
+    if status is not None and 500 <= status <= 599:
+        return TransientBackendError(retry_after=_retry_after(signals.retry_after_s))
+
+    if status == 429:
+        return WindowExhausted(resets_at=None, window="unknown")
+
+    return Available(plan_windows=signals.plan_windows)
+
+
+def _has(target: ErrorClass, code_cls: ErrorClass, type_cls: ErrorClass) -> bool:
+    return target is code_cls or target is type_cls
+
+
+def _reason(signals: TurnSignals, wanted: ErrorClass, fallback: str) -> str:
+    if classify_code(signals.error_code, None) is wanted and signals.error_code is not None:
+        return signals.error_code
+    if classify_code(None, signals.error_type) is wanted and signals.error_type is not None:
+        return signals.error_type
+    if signals.error_code is not None:
+        return signals.error_code
+    if signals.error_type is not None:
+        return signals.error_type
+    return fallback
+
+
+def _retry_after(seconds: float | None) -> timedelta | None:
+    if seconds is None:
+        return None
+    return timedelta(seconds=seconds)
+
+
+def _is_slow_down(signals: TurnSignals) -> bool:
+    return signals.error_code == "slow_down" or signals.error_type == "slow_down"
+
+
+def _window_from_plan(plan: PlanWindows | None) -> tuple[datetime | None, str]:
+    if plan is None:
+        return None, "unknown"
+    primary = plan.primary
+    if primary is not None and primary.resets_at is not None:
+        return primary.resets_at, "five_hour"
+    secondary = plan.secondary
+    if secondary is not None and secondary.resets_at is not None:
+        return secondary.resets_at, "weekly"
+    return None, "unknown"

codexloop/domain/completion.py

@@ -0,0 +1,130 @@
+"""Three-layer completion evaluation: structured output → marker → continue."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import assert_never
+
+from codexloop.domain.capacity import (
+    AuthFailed,
+    Available,
+    CapacityState,
+    QuotaExhausted,
+    ThrottleExhausted,
+    TransientBackendError,
+    WindowExhausted,
+)
+from codexloop.domain.signals import TurnSignals
+
+DEFAULT_DONE_MARKER = "CODEXLOOP_TASK_FULLY_COMPLETE"
+
+
+@dataclass(frozen=True, slots=True)
+class Done:
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class Continue:
+    remaining: list[str]
+
+
+@dataclass(frozen=True, slots=True)
+class Blocked:
+    reason: str
+
+
+CompletionVerdict = Done | Continue | Blocked
+
+
+class CompletionEvaluator:
+    """Map turn signals + capacity into a completion verdict.
+
+    Capacity rejection always outranks a completion claim. Within an
+    ``Available`` turn the layers are: structured output, then a done-marker
+    line in the final message, then ``Continue``.
+    """
+
+    def __init__(self, done_marker: str = DEFAULT_DONE_MARKER) -> None:
+        self._done_marker = done_marker
+
+    def evaluate(self, signals: TurnSignals, capacity: CapacityState) -> CompletionVerdict:
+        parsed = _parse_structured(signals.structured_output)
+
+        if not _is_available(capacity):
+            return Continue(remaining=_remaining_from(parsed))
+
+        if parsed is not None:
+            structured = _verdict_from_structured(parsed)
+            if structured is not None:
+                return structured
+
+        if _marker_on_own_line(signals.final_message, self._done_marker):
+            return Done()
+
+        return Continue(remaining=[])
+
+
+def _is_available(capacity: CapacityState) -> bool:
+    match capacity:
+        case Available():
+            return True
+        case (
+            ThrottleExhausted()
+            | WindowExhausted()
+            | QuotaExhausted()
+            | AuthFailed()
+            | TransientBackendError()
+        ):
+            return False
+        case _:  # pragma: no cover — match is exhaustive over CapacityState
+            assert_never(capacity)
+
+
+def _parse_structured(value: object | None) -> Mapping[str, object] | None:
+    if value is None:
+        return None
+    if isinstance(value, Mapping):
+        return value
+    if isinstance(value, str):
+        try:
+            loaded = json.loads(value)
+        except json.JSONDecodeError:
+            return None
+        if isinstance(loaded, Mapping):
+            return loaded
+        return None
+    return None
+
+
+def _verdict_from_structured(parsed: Mapping[str, object]) -> CompletionVerdict | None:
+    blocked_on = parsed.get("blocked_on")
+    if blocked_on:
+        return Blocked(reason=str(blocked_on))
+
+    remaining = _remaining_from(parsed)
+    complete = parsed.get("complete")
+    if complete is True:
+        if not remaining:
+            return Done()
+        return Continue(remaining=remaining)
+    if complete is False:
+        return Continue(remaining=remaining)
+    return None
+
+
+def _remaining_from(parsed: Mapping[str, object] | None) -> list[str]:
+    if parsed is None:
+        return []
+    raw = parsed.get("remaining_work")
+    if not isinstance(raw, list):
+        return []
+    return [str(item) for item in raw]
+
+
+def _marker_on_own_line(message: str | None, done_marker: str) -> bool:
+    if message is None:
+        return False
+    return any(line.strip() == done_marker for line in message.splitlines())

codexloop/domain/control.py

@@ -0,0 +1,167 @@
+"""Operator inbox commands: parse a JSON dict, never ignore unknown kinds."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import cast
+
+from codexloop.domain.approval import ApprovalPolicy, SandboxMode
+from codexloop.domain.errors import ConfigurationError
+from codexloop.domain.model_profile import Effort
+
+
+class PromptTiming(StrEnum):
+    NOW = "now"
+    NEXT_TURN = "next_turn"
+
+
+@dataclass(frozen=True, slots=True)
+class Stop:
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": "stop"}
+
+
+@dataclass(frozen=True, slots=True)
+class Prompt:
+    text: str
+    timing: PromptTiming
+
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": "prompt", "text": self.text, "timing": self.timing.value}
+
+
+@dataclass(frozen=True, slots=True)
+class SetModel:
+    model: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": "set_model", "model": self.model}
+
+
+@dataclass(frozen=True, slots=True)
+class SetEffort:
+    effort: Effort
+
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": "set_effort", "effort": self.effort.value}
+
+
+@dataclass(frozen=True, slots=True)
+class SetApproval:
+    policy: ApprovalPolicy
+
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": "set_approval", "policy": self.policy.value}
+
+
+@dataclass(frozen=True, slots=True)
+class SetSandbox:
+    sandbox: SandboxMode
+
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": "set_sandbox", "sandbox": self.sandbox.value}
+
+
+@dataclass(frozen=True, slots=True)
+class SetCwd:
+    cwd: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": "set_cwd", "cwd": self.cwd}
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot:
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": "snapshot"}
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceMutate:
+    payload: dict[str, object]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "payload", dict(self.payload))
+
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": "resource_mutate", "payload": dict(self.payload)}
+
+
+ControlCommand = (
+    Stop
+    | Prompt
+    | SetModel
+    | SetEffort
+    | SetApproval
+    | SetSandbox
+    | SetCwd
+    | Snapshot
+    | ResourceMutate
+)
+
+
+def parse_control(data: Mapping[str, object]) -> ControlCommand:
+    kind = data.get("kind")
+    if not isinstance(kind, str):
+        raise ConfigurationError("control command missing kind")
+    builder = _BUILDERS.get(kind)
+    if builder is None:
+        raise ConfigurationError(f"unknown control command kind: {kind!r}")
+    try:
+        return builder(data)
+    except (KeyError, TypeError, ValueError) as exc:
+        raise ConfigurationError(f"invalid control command {kind!r}: {exc}") from exc
+
+
+def _parse_stop(_data: Mapping[str, object]) -> Stop:
+    return Stop()
+
+
+def _parse_prompt(data: Mapping[str, object]) -> Prompt:
+    return Prompt(text=str(data["text"]), timing=PromptTiming(str(data["timing"])))
+
+
+def _parse_set_model(data: Mapping[str, object]) -> SetModel:
+    return SetModel(model=str(data["model"]))
+
+
+def _parse_set_effort(data: Mapping[str, object]) -> SetEffort:
+    return SetEffort(effort=Effort(str(data["effort"])))
+
+
+def _parse_set_approval(data: Mapping[str, object]) -> SetApproval:
+    return SetApproval(policy=ApprovalPolicy(str(data["policy"])))
+
+
+def _parse_set_sandbox(data: Mapping[str, object]) -> SetSandbox:
+    return SetSandbox(sandbox=SandboxMode(str(data["sandbox"])))
+
+
+def _parse_set_cwd(data: Mapping[str, object]) -> SetCwd:
+    return SetCwd(cwd=str(data["cwd"]))
+
+
+def _parse_snapshot(_data: Mapping[str, object]) -> Snapshot:
+    return Snapshot()
+
+
+def _parse_resource_mutate(data: Mapping[str, object]) -> ResourceMutate:
+    payload = data["payload"]
+    if not isinstance(payload, Mapping):
+        raise TypeError("resource_mutate payload must be a mapping")
+    return ResourceMutate(payload=dict(cast(Mapping[str, object], payload)))
+
+
+_BUILDERS: dict[str, Callable[[Mapping[str, object]], ControlCommand]] = {
+    "stop": _parse_stop,
+    "prompt": _parse_prompt,
+    "set_model": _parse_set_model,
+    "set_effort": _parse_set_effort,
+    "set_approval": _parse_set_approval,
+    "set_sandbox": _parse_set_sandbox,
+    "set_cwd": _parse_set_cwd,
+    "snapshot": _parse_snapshot,
+    "resource_mutate": _parse_resource_mutate,
+}