codexloop 0.1.0__py3-none-any.whl

codexloop/domain/error_codes.py

@@ -0,0 +1,75 @@
+"""OpenAI / Codex error-code taxonomy for capacity classification."""
+
+from __future__ import annotations
+
+from enum import Enum, auto
+
+
+class ErrorClass(Enum):
+    """Coarse classification of vendor error codes / types."""
+
+    AUTH = auto()
+    QUOTA = auto()
+    WINDOW = auto()
+    THROTTLE = auto()
+    TRANSIENT = auto()
+    FATAL = auto()
+    UNKNOWN = auto()
+
+
+QUOTA_CODES: frozenset[str] = frozenset(
+    {
+        "insufficient_quota",
+        "credit_balance_exhausted",
+        "usage_not_included",
+    }
+)
+
+AUTH_CODES: frozenset[str] = frozenset(
+    {
+        "invalid_api_key",
+        "token_expired",
+        "refresh_token_expired",
+        "refresh_token_reused",
+        "refresh_token_invalidated",
+    }
+)
+
+WINDOW_CODES: frozenset[str] = frozenset({"usage_limit_reached"})
+
+THROTTLE_CODES: frozenset[str] = frozenset(
+    {
+        "rate_limit_exceeded",
+        "slow_down",
+    }
+)
+
+TRANSIENT_CODES: frozenset[str] = frozenset({"server_is_overloaded"})
+
+FATAL_CODES: frozenset[str] = frozenset(
+    {
+        "context_length_exceeded",
+        "invalid_prompt",
+    }
+)
+
+_CODE_TO_CLASS: dict[str, ErrorClass] = {
+    **dict.fromkeys(QUOTA_CODES, ErrorClass.QUOTA),
+    **dict.fromkeys(AUTH_CODES, ErrorClass.AUTH),
+    **dict.fromkeys(WINDOW_CODES, ErrorClass.WINDOW),
+    **dict.fromkeys(THROTTLE_CODES, ErrorClass.THROTTLE),
+    **dict.fromkeys(TRANSIENT_CODES, ErrorClass.TRANSIENT),
+    **dict.fromkeys(FATAL_CODES, ErrorClass.FATAL),
+}
+
+
+def classify_code(code: str | None, type_: str | None) -> ErrorClass:
+    """Map an OpenAI/Codex ``error.code`` / ``error.type`` to an :class:`ErrorClass`.
+
+    Prefers ``code`` when present; consults ``type_`` only when ``code`` is absent.
+    Unrecognised values yield :attr:`ErrorClass.UNKNOWN`.
+    """
+    token = code if code is not None else type_
+    if token is None:
+        return ErrorClass.UNKNOWN
+    return _CODE_TO_CLASS.get(token, ErrorClass.UNKNOWN)

codexloop/domain/errors.py

@@ -0,0 +1,35 @@
+"""Domain exception hierarchy for codexloop."""
+
+from __future__ import annotations
+
+
+class CodexloopError(Exception):
+    """Base error for all codexloop domain failures."""
+
+
+class ConfigurationError(CodexloopError):
+    """Invalid or incomplete configuration."""
+
+
+class CapacityError(CodexloopError):
+    """Capacity, quota, or rate-limit related failure."""
+
+
+class AuthError(CodexloopError):
+    """Authentication or credential failure."""
+
+
+class CodexBinaryError(CodexloopError):
+    """Codex CLI binary missing, broken, or unusable."""
+
+
+class CodexProtocolError(CodexloopError):
+    """Malformed or unexpected Codex protocol / event stream."""
+
+
+class BudgetExceeded(CodexloopError):
+    """Operator-configured budget or spend limit reached."""
+
+
+class WaitDeadlineExceeded(CodexloopError):
+    """Wait / probe loop hit the configured max-wait deadline."""

codexloop/domain/loop.py

@@ -0,0 +1,190 @@
+"""Pure run-loop state machine: (RunState, LoopOutcome, now) -> Decision."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+
+from codexloop.domain.budget import BudgetLedger
+from codexloop.domain.capacity import (
+    AuthFailed,
+    Available,
+    CapacityState,
+    QuotaExhausted,
+    ThrottleExhausted,
+    TransientBackendError,
+    WindowExhausted,
+)
+from codexloop.domain.completion import Blocked, CompletionVerdict, Continue, Done
+from codexloop.domain.control import ControlCommand, Stop
+
+
+class RunState(StrEnum):
+    Preflight = "Preflight"
+    Running = "Running"
+    Evaluating = "Evaluating"
+    ThrottleBackoff = "ThrottleBackoff"
+    Waiting = "Waiting"
+    Probing = "Probing"
+    Stopping = "Stopping"
+    Complete = "Complete"
+    Failed = "Failed"
+
+
+@dataclass(frozen=True, slots=True)
+class SendTurn:
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class Probe:
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class WaitUntil:
+    until: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class BackoffUntil:
+    until: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class Finish:
+    success: bool
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class Drain:
+    pass
+
+
+Decision = SendTurn | Probe | WaitUntil | BackoffUntil | Finish | Drain
+
+_TERMINAL = frozenset({RunState.Complete, RunState.Failed})
+_DEADLINE_STATES = frozenset(
+    {
+        RunState.Preflight,
+        RunState.Waiting,
+        RunState.Probing,
+        RunState.ThrottleBackoff,
+    }
+)
+_WAKE_STATES = frozenset({RunState.Waiting, RunState.ThrottleBackoff})
+_TURN_STATES = frozenset({RunState.Running, RunState.Evaluating})
+
+
+@dataclass(frozen=True, slots=True)
+class LoopOutcome:
+    """Domain-side turn/probe result. Application TurnOutcome is not imported."""
+
+    capacity: CapacityState
+    completion: CompletionVerdict | None = None
+    deadline_exceeded: bool = False
+
+
+class RunLoopStateMachine:
+    """Total function over run state, capacity, completion, budget, and controls."""
+
+    def advance(
+        self,
+        state: RunState,
+        outcome: LoopOutcome,
+        now: datetime,
+        ledger: BudgetLedger,
+        controls: Sequence[ControlCommand],
+    ) -> tuple[RunState, Decision]:
+        if state in _TERMINAL:
+            return _stay_terminal(state)
+
+        if state is RunState.Stopping:
+            return RunState.Failed, Finish(success=False, reason="stop")
+
+        if _has_stop(controls):
+            return RunState.Stopping, Drain()
+
+        if outcome.deadline_exceeded and state in _DEADLINE_STATES:
+            return RunState.Failed, Finish(success=False, reason="max_wait")
+
+        return _route_capacity(state, outcome, now, ledger)
+
+
+def _stay_terminal(state: RunState) -> tuple[RunState, Decision]:
+    if state is RunState.Complete:
+        return RunState.Complete, Finish(success=True, reason="done")
+    return RunState.Failed, Finish(success=False, reason="failed")
+
+
+def _has_stop(controls: Sequence[ControlCommand]) -> bool:
+    return any(isinstance(command, Stop) for command in controls)
+
+
+def _route_capacity(
+    state: RunState,
+    outcome: LoopOutcome,
+    now: datetime,
+    ledger: BudgetLedger,
+) -> tuple[RunState, Decision]:
+    capacity = outcome.capacity
+    if isinstance(capacity, AuthFailed):
+        return RunState.Failed, Finish(success=False, reason="auth")
+
+    if state in _WAKE_STATES:
+        return RunState.Probing, Probe()
+
+    if isinstance(capacity, ThrottleExhausted):
+        return RunState.ThrottleBackoff, BackoffUntil(until=now)
+
+    if isinstance(capacity, (WindowExhausted, QuotaExhausted, TransientBackendError)):
+        return RunState.Waiting, WaitUntil(until=now)
+
+    if isinstance(capacity, Available):
+        return _route_available(state, outcome, ledger)
+
+    # Closed-union exhaustiveness: CapacityState is a finite ADT. This assert is
+    # a precondition on that union, not a security gate.
+    assert False, f"unhandled capacity state: {capacity!r}"  # noqa: B011  # nosec B101  # pragma: no cover
+
+
+def _route_available(
+    state: RunState,
+    outcome: LoopOutcome,
+    ledger: BudgetLedger,
+) -> tuple[RunState, Decision]:
+    if state is RunState.Preflight or state is RunState.Probing:
+        return _send_turn_or_budget(ledger)
+    if state in _TURN_STATES:
+        return _evaluate_completion(outcome, ledger)
+    # Closed-union exhaustiveness: remaining RunState values are a finite ADT.
+    # This assert is a precondition on that union, not a security gate.
+    assert False, f"unhandled run state: {state!r}"  # noqa: B011  # nosec B101  # pragma: no cover
+
+
+def _send_turn_or_budget(ledger: BudgetLedger) -> tuple[RunState, Decision]:
+    exceeded = ledger.exceeded()
+    if exceeded is not None:
+        return RunState.Failed, Finish(success=False, reason=exceeded)
+    return RunState.Running, SendTurn()
+
+
+def _evaluate_completion(outcome: LoopOutcome, ledger: BudgetLedger) -> tuple[RunState, Decision]:
+    completion = outcome.completion
+    if isinstance(completion, Done):
+        return RunState.Complete, Finish(success=True, reason="done")
+    if isinstance(completion, Blocked):
+        return RunState.Failed, Finish(success=False, reason=completion.reason)
+    exceeded = ledger.exceeded()
+    if exceeded is not None:
+        return RunState.Failed, Finish(success=False, reason=exceeded)
+    if isinstance(completion, Continue):
+        return RunState.Running, SendTurn()
+    if completion is None:
+        return RunState.Evaluating, Probe()
+    # Closed-union exhaustiveness: CompletionVerdict | None is a finite ADT.
+    # This assert is a precondition on that union, not a security gate.
+    assert False, f"unhandled completion verdict: {completion!r}"  # noqa: B011  # nosec B101  # pragma: no cover

codexloop/domain/model_profile.py

@@ -0,0 +1,30 @@
+"""Model + reasoning-effort profile with low/medium/high presets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class Effort(StrEnum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+@dataclass(frozen=True, slots=True)
+class ModelEffortProfile:
+    model: str
+    effort: Effort
+
+    @classmethod
+    def low(cls, model: str) -> ModelEffortProfile:
+        return cls(model=model, effort=Effort.LOW)
+
+    @classmethod
+    def medium(cls, model: str) -> ModelEffortProfile:
+        return cls(model=model, effort=Effort.MEDIUM)
+
+    @classmethod
+    def high(cls, model: str) -> ModelEffortProfile:
+        return cls(model=model, effort=Effort.HIGH)

codexloop/domain/plan.py

@@ -0,0 +1,38 @@
+"""Markdown work-plan parsing. Checkboxes are the load-bearing items."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from codexloop.domain.errors import ConfigurationError
+
+_CHECKBOX = re.compile(r"^[ \t]*[-*+][ \t]+\[([ xX])\][ \t]+(\S.*)$")
+
+
+@dataclass(frozen=True, slots=True)
+class PlanItem:
+    name: str
+    done: bool
+
+
+@dataclass(frozen=True, slots=True)
+class WorkPlan:
+    items: tuple[PlanItem, ...]
+
+    @classmethod
+    def parse(cls, text: str) -> WorkPlan:
+        items: list[PlanItem] = []
+        for line in text.splitlines():
+            matched = _CHECKBOX.match(line.rstrip())
+            if matched is None:
+                continue
+            marker, name = matched.group(1), matched.group(2).strip()
+            items.append(PlanItem(name=name, done=marker in "xX"))
+        if not items:
+            raise ConfigurationError("work plan has no checkbox items")
+        return cls(items=tuple(items))
+
+    @property
+    def remaining_work(self) -> tuple[str, ...]:
+        return tuple(item.name for item in self.items if not item.done)

codexloop/domain/savepoint.py

@@ -0,0 +1,32 @@
+"""Git save-point value objects — migration-like snapshots of the worktree."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(frozen=True, slots=True)
+class SavePointRef:
+    n: int
+    ref: str
+    sha: str
+    label: str
+    at: datetime
+    plan_item: str | None = None
+    committed: bool = False
+
+    def __post_init__(self) -> None:
+        if self.n < 1:
+            raise ValueError("save point number must be >= 1")
+        if not self.ref.strip():
+            raise ValueError("save point ref must not be blank")
+        if not self.sha.strip():
+            raise ValueError("save point sha must not be blank")
+
+
+@dataclass(frozen=True, slots=True)
+class UnwindResult:
+    to: SavePointRef
+    backup_ref: str | None
+    restored_sha: str

codexloop/domain/savepoint_message.py

@@ -0,0 +1,56 @@
+"""Pure formatting for git savepoint commit subjects and bodies."""
+
+from __future__ import annotations
+
+_SUBJECT_MAX = 72
+
+
+def format_savepoint_commit_message(
+    *,
+    run_id: str,
+    attempt: int,
+    verdict_name: str,
+    summary: str,
+    remaining_work: tuple[str, ...] = (),
+    changed_paths: tuple[str, ...] = (),
+    label: str = "",
+) -> tuple[str, str]:
+    """Return (subject, body) using Conventional Commits.
+
+    Subject: ``chore(codexloop): turn {n} — {headline}``
+    """
+    headline = _headline(summary=summary, changed_paths=changed_paths)
+    subject = f"chore(codexloop): turn {attempt} — {headline}"
+    if len(subject) > _SUBJECT_MAX:
+        subject = subject[: _SUBJECT_MAX - 1].rstrip() + "…"
+
+    remaining_lines = (
+        "\n".join(f"- {item}" for item in remaining_work) if remaining_work else "- (none)"
+    )
+    path_lines = "\n".join(f"- {path}" for path in changed_paths) if changed_paths else "- (none)"
+    summary_block = summary.strip() if summary.strip() else "(none)"
+    body = (
+        f"Run: {run_id}\n"
+        f"Attempt: {attempt}\n"
+        f"Verdict: {verdict_name}\n"
+        f"Label: {label}\n"
+        f"\n"
+        f"Summary:\n{summary_block}\n"
+        f"\n"
+        f"Remaining work:\n{remaining_lines}\n"
+        f"\n"
+        f"Changed paths:\n{path_lines}\n"
+    )
+    return subject, body
+
+
+def _headline(*, summary: str, changed_paths: tuple[str, ...]) -> str:
+    for line in summary.splitlines():
+        cleaned = line.strip()
+        if cleaned:
+            return cleaned
+    if changed_paths:
+        name = changed_paths[0].rstrip("/").rsplit("/", 1)[-1]
+        if name:
+            return name
+    return "workspace checkpoint"

codexloop/domain/session.py

@@ -0,0 +1,32 @@
+"""Thread identity and how a run selects a session."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(frozen=True, slots=True)
+class ThreadRef:
+    thread_id: str
+    cwd: str
+    started_at: datetime
+    model: str
+
+
+@dataclass(frozen=True, slots=True)
+class PlanFile:
+    path: str
+
+
+@dataclass(frozen=True, slots=True)
+class MostRecent:
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class Explicit:
+    thread_id: str
+
+
+SessionSelector = PlanFile | MostRecent | Explicit

codexloop/domain/signals.py

@@ -0,0 +1,25 @@
+"""Turn-level signals consumed by capacity classification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from codexloop.domain.capacity import PlanWindows
+
+
+@dataclass(frozen=True, slots=True)
+class TurnSignals:
+    """Bundle of independent turn signals assembled at the infrastructure edge."""
+
+    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: bool = False
+    failed: bool = False
+    final_message: str | None = None
+    structured_output: object | None = None
+    usage: object | None = None
+    exit_code: int | None = None
+    stderr_tail: str | None = None

codexloop/domain/waiting.py

@@ -0,0 +1,120 @@
+"""Adaptive wait policy: the next instant to probe, never a blind sleep."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from random import random
+from typing import assert_never
+
+from codexloop.domain.backoff import backoff
+from codexloop.domain.capacity import (
+    AuthFailed,
+    Available,
+    CapacityState,
+    QuotaExhausted,
+    ThrottleExhausted,
+    TransientBackendError,
+    WindowExhausted,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class WaitConfig:
+    """Cadence knobs for :class:`AdaptiveWaitPolicy`.
+
+    Defaults match the waiting table: throttle 60s, aggressive 300s, transient
+    120s, unknown-window / quota probe 120s → 600s.
+    """
+
+    grace: timedelta = timedelta(seconds=2)
+    window_probe_interval: timedelta = timedelta(seconds=60)
+    quota_probe_base: timedelta = timedelta(seconds=120)
+    quota_probe_ceiling: timedelta = timedelta(seconds=600)
+    throttle_ceiling: timedelta = timedelta(seconds=60)
+    aggressive_ceiling: timedelta = timedelta(seconds=300)
+    transient_ceiling: timedelta = timedelta(seconds=120)
+    jitter_ratio: float = 0.1
+    backoff_base: timedelta = timedelta(seconds=1)
+
+
+class AdaptiveWaitPolicy:
+    """Map a capacity state to the next probe instant."""
+
+    def __init__(self, config: WaitConfig, *, rand: Callable[[], float] = random) -> None:
+        self._config = config
+        self._rand = rand
+
+    def next_probe_at(
+        self,
+        state: CapacityState,
+        now: datetime,
+        attempt: int,
+        deadline: datetime,
+    ) -> datetime:
+        match state:
+            case Available():
+                return now
+            case AuthFailed():
+                return deadline
+            case ThrottleExhausted() as throttle:
+                return _clamp(now + self._throttle_delay(throttle, attempt), now, deadline)
+            case TransientBackendError():
+                delay = self._capped_backoff(attempt, self._config.transient_ceiling)
+                return _clamp(now + delay, now, deadline)
+            case WindowExhausted() as window:
+                return _clamp(self._window_instant(window, now, attempt), now, deadline)
+            case QuotaExhausted():
+                delay = self._quota_delay(attempt)
+                return _clamp(now + delay, now, deadline)
+            case _:  # pragma: no cover — match is exhaustive over CapacityState
+                assert_never(state)
+
+    def _throttle_delay(self, state: ThrottleExhausted, attempt: int) -> timedelta:
+        ceiling = (
+            self._config.aggressive_ceiling if state.aggressive else self._config.throttle_ceiling
+        )
+        delay = self._capped_backoff(attempt, ceiling)
+        if state.retry_after is not None:
+            # Retry-After is a minimum; add a small random delay so clients do not
+            # wake together when the header is the binding wait (R2).
+            retry_s = max(state.retry_after.total_seconds(), 0.0)
+            spread_s = retry_s * self._config.jitter_ratio * self._rand()
+            delay = max(delay, timedelta(seconds=retry_s + spread_s))
+        return min(delay, ceiling)
+
+    def _window_instant(self, state: WindowExhausted, now: datetime, attempt: int) -> datetime:
+        if state.resets_at is None:
+            return now + self._quota_delay(attempt)
+        target = state.resets_at + self._config.grace
+        interval_wake = now + self._config.window_probe_interval
+        if target <= now:
+            return interval_wake
+        return min(target, interval_wake)
+
+    def _quota_delay(self, attempt: int) -> timedelta:
+        return self._capped_backoff(
+            attempt,
+            self._config.quota_probe_ceiling,
+            base=self._config.quota_probe_base,
+        )
+
+    def _capped_backoff(
+        self,
+        attempt: int,
+        ceiling: timedelta,
+        *,
+        base: timedelta | None = None,
+    ) -> timedelta:
+        return backoff(
+            attempt,
+            base=self._config.backoff_base if base is None else base,
+            ceiling=ceiling,
+            jitter_ratio=self._config.jitter_ratio,
+            rand=self._rand,
+        )
+
+
+def _clamp(instant: datetime, now: datetime, deadline: datetime) -> datetime:
+    return min(deadline, max(now, instant))