codexloop 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

codexloop/__init__.py

@@ -1,3 +1,3 @@
 """codexloop — onion-architected, autonomous OpenAI Codex session runner."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

codexloop/application/interfaces/__init__.py

@@ -0,0 +1,75 @@
+"""Application interfaces -- every seam implemented by infrastructure/ and
+never imported from it.
+
+One module per collaborator family so a reader finds a seam by what it does
+rather than by scrolling one long file. `application/ports.py` re-exports
+this package unchanged, so existing imports keep working.
+"""
+
+from __future__ import annotations
+
+from codexloop.application.interfaces.agent import (
+    AgentGateway,
+    CapacityProbe,
+    RunResources,
+    ThreadCatalog,
+)
+from codexloop.application.interfaces.api import (
+    ApiGateway,
+)
+from codexloop.application.interfaces.control import (
+    ControlInbox,
+    RunControl,
+)
+from codexloop.application.interfaces.doctor import (
+    DoctorCheck,
+    DoctorEnvironment,
+    DoctorReport,
+)
+from codexloop.application.interfaces.observability import (
+    AuditLog,
+    Logger,
+    Notifier,
+    ProgressReporter,
+    RunEventSink,
+    StateBus,
+)
+from codexloop.application.interfaces.permissions import (
+    PermissionMode,
+)
+from codexloop.application.interfaces.storage import (
+    RunSnapshotSink,
+    RunStateStore,
+    SavePointStore,
+    SessionLock,
+)
+from codexloop.application.interfaces.system import (
+    Clock,
+    Sleeper,
+)
+
+__all__ = [
+    "AgentGateway",
+    "ApiGateway",
+    "AuditLog",
+    "CapacityProbe",
+    "Clock",
+    "ControlInbox",
+    "DoctorCheck",
+    "DoctorEnvironment",
+    "DoctorReport",
+    "Logger",
+    "Notifier",
+    "PermissionMode",
+    "ProgressReporter",
+    "RunControl",
+    "RunEventSink",
+    "RunResources",
+    "RunSnapshotSink",
+    "RunStateStore",
+    "SavePointStore",
+    "SessionLock",
+    "Sleeper",
+    "StateBus",
+    "ThreadCatalog",
+]

codexloop/application/interfaces/agent.py

@@ -0,0 +1,46 @@
+"""The vendor session seam: sending turns, probing capacity, enumerating
+sessions, and the run-scoped resources attached to one."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Protocol, runtime_checkable
+
+from codexloop.application.dto import ProbeResult, TurnOutcome
+from codexloop.application.interfaces.permissions import PermissionMode
+from codexloop.domain.model_profile import ModelEffortProfile
+from codexloop.domain.session import ThreadRef
+
+
+@runtime_checkable
+class AgentGateway(Protocol):
+    """Vendor-agnostic agent session (exec and app-server adapters implement this)."""
+
+    async def send_turn(self, prompt: str) -> TurnOutcome: ...
+    async def close(self) -> None: ...
+    async def set_profile(self, profile: ModelEffortProfile) -> None: ...
+    async def set_permission_mode(self, mode: PermissionMode) -> None: ...
+    async def set_cwd(self, path: str) -> None: ...
+    async def set_session_resources(self, resources: Mapping[str, object]) -> None: ...
+    def resolve_tool_approval(self, request_id: str, *, allow: bool, reason: str = "") -> bool: ...
+
+
+@runtime_checkable
+class CapacityProbe(Protocol):
+    async def probe(self) -> ProbeResult: ...
+
+
+@runtime_checkable
+class ThreadCatalog(Protocol):
+    """Our run registry keyed by ``thread_id``, not vendor session discovery."""
+
+    def list_threads(self) -> Sequence[ThreadRef]: ...
+    def get(self, thread_id: str) -> ThreadRef | None: ...
+    def record(self, ref: ThreadRef) -> None: ...
+
+
+@runtime_checkable
+class RunResources(Protocol):
+    """Placeholder for run-scoped attachments applied mid-run."""
+
+    def as_payload(self) -> Mapping[str, object]: ...

codexloop/application/interfaces/api.py

@@ -0,0 +1,10 @@
+"""The generated REST surface seam."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ApiGateway(Protocol):
+    def invoke(self, method_path: str, **kwargs: object) -> object: ...

codexloop/application/interfaces/control.py

@@ -0,0 +1,21 @@
+"""The out-of-band control plane: commands an operator drops for a live run."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from codexloop.domain.control import ControlCommand
+
+
+@runtime_checkable
+class RunControl(Protocol):
+    def poll(self) -> Sequence[ControlCommand]: ...
+
+
+@runtime_checkable
+class ControlInbox(Protocol):
+    """Where an out-of-band command is dropped for a live run to pick up."""
+
+    def enqueue(self, command: ControlCommand) -> Path: ...

codexloop/application/interfaces/doctor.py

@@ -0,0 +1,35 @@
+"""What `doctor` needs from the outside world, and the vocabulary it answers in.
+
+The result types live here alongside the Protocol: they are part of the seam's
+vocabulary, not of the use case that consumes it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorCheck:
+    name: str
+    passed: bool
+    detail: str
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorReport:
+    checks: tuple[DoctorCheck, ...]
+    auth_mode: str
+    probe_strategies: Mapping[str, bool] = field(default_factory=dict)
+
+    @property
+    def all_passed(self) -> bool:
+        return all(check.passed for check in self.checks)
+
+
+@runtime_checkable
+class DoctorEnvironment(Protocol):
+    def diagnose(self, *, cwd: Path) -> DoctorReport: ...

codexloop/application/interfaces/observability.py

@@ -0,0 +1,42 @@
+"""Everything the run emits outward: logs, audit records, progress, events,
+state publications, usage reads, and operator notifications."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ProgressReporter(Protocol):
+    def report(self, event: str, **detail: object) -> None: ...
+
+
+@runtime_checkable
+class AuditLog(Protocol):
+    def append(self, event_type: str, payload: Mapping[str, object]) -> None: ...
+
+
+@runtime_checkable
+class Notifier(Protocol):
+    def notify(self, title: str, body: str) -> None: ...
+
+
+@runtime_checkable
+class Logger(Protocol):
+    def bind(self, **kwargs: object) -> Logger: ...
+    def debug(self, event: str, **kwargs: object) -> None: ...
+    def info(self, event: str, **kwargs: object) -> None: ...
+    def warning(self, event: str, **kwargs: object) -> None: ...
+    def error(self, event: str, **kwargs: object) -> None: ...
+
+
+@runtime_checkable
+class RunEventSink(Protocol):
+    def emit(self, event: Mapping[str, object]) -> None: ...
+
+
+@runtime_checkable
+class StateBus(Protocol):
+    def publish(self, event_type: str, payload: Mapping[str, object]) -> None: ...
+    def subscribe(self, callback: Callable[[str, Mapping[str, object]], None]) -> None: ...

codexloop/application/interfaces/permissions.py

@@ -0,0 +1,14 @@
+"""Permission vocabulary shared across the seam, so vendor CLI flag strings
+never leak up into the application layer."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class PermissionMode(StrEnum):
+    """Autonomy posture at the application boundary — not Codex CLI flag strings."""
+
+    AUTONOMOUS = "autonomous"
+    READ_ONLY = "read_only"
+    FULL_ACCESS = "full_access"

codexloop/application/interfaces/storage.py

@@ -0,0 +1,31 @@
+"""Durable run state: the state store, the run lock, git save points, and the
+snapshot sink."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class RunStateStore(Protocol):
+    def load(self, run_id: str) -> dict[str, object] | None: ...
+    def save(self, run_id: str, state: Mapping[str, object]) -> None: ...
+
+
+@runtime_checkable
+class SessionLock(Protocol):
+    def acquire(self, thread_id: str) -> bool: ...
+    def release(self, thread_id: str) -> None: ...
+
+
+@runtime_checkable
+class SavePointStore(Protocol):
+    def create(self, run_id: str, label: str) -> str: ...
+    def list(self, run_id: str) -> Sequence[str]: ...
+    def unwind(self, run_id: str, to: str) -> None: ...
+
+
+@runtime_checkable
+class RunSnapshotSink(Protocol):
+    def write(self, snapshot: Mapping[str, object]) -> None: ...

codexloop/application/interfaces/system.py

@@ -0,0 +1,16 @@
+"""Time and sleeping -- the two ambient effects the run loop needs faked."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Clock(Protocol):
+    def now(self) -> datetime: ...
+
+
+@runtime_checkable
+class Sleeper(Protocol):
+    async def sleep_until(self, when: datetime) -> None: ...

codexloop/application/ports.py

@@ -1,19 +1,38 @@
-"""Application ports — Protocols implemented by infrastructure, never imported from it.
+"""Backwards-compatible re-export of `application.interfaces`.
 
-``application/`` knows the shape of a collaborator, never a concrete adapter.
+The Protocols moved into `application/interfaces/` so every seam lives in
+one discoverable place, one module per collaborator family. This shim keeps
+the old `from codexloop.application.ports import X` path working; new code
+should import from `codexloop.application.interfaces`.
 """
 
 from __future__ import annotations
 
-from collections.abc import Callable, Mapping, Sequence
-from datetime import datetime
-from enum import StrEnum
-from typing import Protocol, runtime_checkable
-
-from codexloop.application.dto import ProbeResult, TurnOutcome
-from codexloop.domain.control import ControlCommand
-from codexloop.domain.model_profile import ModelEffortProfile
-from codexloop.domain.session import ThreadRef
+from codexloop.application.interfaces import (
+    AgentGateway,
+    ApiGateway,
+    AuditLog,
+    CapacityProbe,
+    Clock,
+    ControlInbox,
+    DoctorCheck,
+    DoctorEnvironment,
+    DoctorReport,
+    Logger,
+    Notifier,
+    PermissionMode,
+    ProgressReporter,
+    RunControl,
+    RunEventSink,
+    RunResources,
+    RunSnapshotSink,
+    RunStateStore,
+    SavePointStore,
+    SessionLock,
+    Sleeper,
+    StateBus,
+    ThreadCatalog,
+)
 
 __all__ = [
     "AgentGateway",
@@ -21,6 +40,10 @@ __all__ = [
     "AuditLog",
     "CapacityProbe",
     "Clock",
+    "ControlInbox",
+    "DoctorCheck",
+    "DoctorEnvironment",
+    "DoctorReport",
     "Logger",
     "Notifier",
     "PermissionMode",
@@ -36,123 +59,3 @@ __all__ = [
     "StateBus",
     "ThreadCatalog",
 ]
-
-
-class PermissionMode(StrEnum):
-    """Autonomy posture at the application boundary — not Codex CLI flag strings."""
-
-    AUTONOMOUS = "autonomous"
-    READ_ONLY = "read_only"
-    FULL_ACCESS = "full_access"
-
-
-@runtime_checkable
-class Clock(Protocol):
-    def now(self) -> datetime: ...
-
-
-@runtime_checkable
-class Sleeper(Protocol):
-    async def sleep_until(self, when: datetime) -> None: ...
-
-
-@runtime_checkable
-class AgentGateway(Protocol):
-    """Vendor-agnostic agent session (exec and app-server adapters implement this)."""
-
-    async def send_turn(self, prompt: str) -> TurnOutcome: ...
-    async def close(self) -> None: ...
-    async def set_profile(self, profile: ModelEffortProfile) -> None: ...
-    async def set_permission_mode(self, mode: PermissionMode) -> None: ...
-    async def set_cwd(self, path: str) -> None: ...
-    async def set_session_resources(self, resources: Mapping[str, object]) -> None: ...
-    def resolve_tool_approval(self, request_id: str, *, allow: bool, reason: str = "") -> bool: ...
-
-
-@runtime_checkable
-class CapacityProbe(Protocol):
-    async def probe(self) -> ProbeResult: ...
-
-
-@runtime_checkable
-class ThreadCatalog(Protocol):
-    """Our run registry keyed by ``thread_id``, not vendor session discovery."""
-
-    def list_threads(self) -> Sequence[ThreadRef]: ...
-    def get(self, thread_id: str) -> ThreadRef | None: ...
-    def record(self, ref: ThreadRef) -> None: ...
-
-
-@runtime_checkable
-class ProgressReporter(Protocol):
-    def report(self, event: str, **detail: object) -> None: ...
-
-
-@runtime_checkable
-class AuditLog(Protocol):
-    def append(self, event_type: str, payload: Mapping[str, object]) -> None: ...
-
-
-@runtime_checkable
-class Notifier(Protocol):
-    def notify(self, title: str, body: str) -> None: ...
-
-
-@runtime_checkable
-class Logger(Protocol):
-    def bind(self, **kwargs: object) -> Logger: ...
-    def info(self, event: str, **kwargs: object) -> None: ...
-    def warning(self, event: str, **kwargs: object) -> None: ...
-    def error(self, event: str, **kwargs: object) -> None: ...
-
-
-@runtime_checkable
-class RunStateStore(Protocol):
-    def load(self, run_id: str) -> dict[str, object] | None: ...
-    def save(self, run_id: str, state: Mapping[str, object]) -> None: ...
-
-
-@runtime_checkable
-class SessionLock(Protocol):
-    def acquire(self, thread_id: str) -> bool: ...
-    def release(self, thread_id: str) -> None: ...
-
-
-@runtime_checkable
-class RunControl(Protocol):
-    def poll(self) -> Sequence[ControlCommand]: ...
-
-
-@runtime_checkable
-class RunEventSink(Protocol):
-    def emit(self, event: Mapping[str, object]) -> None: ...
-
-
-@runtime_checkable
-class StateBus(Protocol):
-    def publish(self, event_type: str, payload: Mapping[str, object]) -> None: ...
-    def subscribe(self, callback: Callable[[str, Mapping[str, object]], None]) -> None: ...
-
-
-@runtime_checkable
-class SavePointStore(Protocol):
-    def create(self, run_id: str, label: str) -> str: ...
-    def list(self, run_id: str) -> Sequence[str]: ...
-    def unwind(self, run_id: str, to: str) -> None: ...
-
-
-@runtime_checkable
-class RunSnapshotSink(Protocol):
-    def write(self, snapshot: Mapping[str, object]) -> None: ...
-
-
-@runtime_checkable
-class ApiGateway(Protocol):
-    def invoke(self, method_path: str, **kwargs: object) -> object: ...
-
-
-@runtime_checkable
-class RunResources(Protocol):
-    """Placeholder for run-scoped attachments applied mid-run."""
-
-    def as_payload(self) -> Mapping[str, object]: ...

codexloop/application/runner.py

@@ -12,6 +12,7 @@ from codexloop.application.ports import (
     AgentGateway,
     CapacityProbe,
     Clock,
+    Logger,
     Notifier,
     PermissionMode,
     ProgressReporter,
@@ -45,6 +46,14 @@ from codexloop.domain.control import (
     Stop,
 )
 from codexloop.domain.error_codes import ErrorClass, classify_code
+from codexloop.domain.forecast import (
+    BurnRate,
+    WindDown,
+    WindDownPolicy,
+    forecast,
+    should_wind_down,
+)
+from codexloop.domain.handoff_marker import HandoffMarker
 from codexloop.domain.loop import (
     BackoffUntil,
     Drain,
@@ -55,6 +64,7 @@ from codexloop.domain.loop import (
     RunState,
     SendTurn,
     WaitUntil,
+    WindDownAndFinish,
 )
 from codexloop.domain.model_profile import Effort, ModelEffortProfile
 from codexloop.domain.plan import WorkPlan
@@ -66,6 +76,26 @@ _FAR_FUTURE = timedelta(days=3650)
 _ZERO = timedelta(0)
 
 
+class _NullLogger:
+    """Diagnostics are optional; a run must not require them to be wired."""
+
+    def bind(self, **kwargs: object) -> _NullLogger:
+        del kwargs
+        return self
+
+    def debug(self, event: str, **kwargs: object) -> None:
+        del event, kwargs
+
+    def info(self, event: str, **kwargs: object) -> None:
+        del event, kwargs
+
+    def warning(self, event: str, **kwargs: object) -> None:
+        del event, kwargs
+
+    def error(self, event: str, **kwargs: object) -> None:
+        del event, kwargs
+
+
 def _discard_artifact(name: str, content: str) -> None:
     del name, content
 
@@ -90,6 +120,9 @@ class RunnerContext:
     )
     wait_policy: AdaptiveWaitPolicy | None = None
     max_wait: timedelta | None = None
+    logger: Logger | None = None
+    handoff_marker_writer: Callable[[HandoffMarker], None] | None = None
+    wind_down_policy: WindDownPolicy = field(default_factory=WindDownPolicy)
     run_id: str = "anonymous"
     cwd: str = "."
     model: str = "unknown"
@@ -110,6 +143,9 @@ class AutonomousRunner:
         self._notifier = ctx.notifier
         self._reporter = ctx.reporter
         self._budget = ctx.budget
+        self._log = ctx.logger or _NullLogger()
+        self._handoff_marker_writer = ctx.handoff_marker_writer
+        self._wind_down_policy = ctx.wind_down_policy
         self._wait_policy = ctx.wait_policy or AdaptiveWaitPolicy(WaitConfig(), rand=lambda: 0.0)
         self._max_wait = ctx.max_wait
         self._run_id = ctx.run_id
@@ -188,7 +224,11 @@ class AutonomousRunner:
                         self._record_thread(thread_id, started)
                         wait_attempt = 0
                         self._quota_notified = False
-                        outcome = LoopOutcome(capacity=capacity, completion=completion)
+                        outcome = LoopOutcome(
+                            capacity=capacity,
+                            completion=completion,
+                            wind_down=self._project_wind_down(capacity),
+                        )
                     case Probe():
                         probed = await self._probe.probe()
                         outcome = LoopOutcome(capacity=probed.outcome)
@@ -207,6 +247,22 @@ class AutonomousRunner:
                             first_turn_done=not first_turn,
                             plan_text=plan_text,
                         )
+                    case WindDownAndFinish() as wound_down:
+                        self._write_stop_summary(thread_id, remaining)
+                        self._persist(
+                            key=thread_id,
+                            remaining=remaining,
+                            first_turn_done=not first_turn,
+                            plan_text=plan_text,
+                            reason=f"wind-down: {wound_down.reason}",
+                        )
+                        self._write_handoff_marker(wound_down, thread_id, remaining)
+                        return RunResult(
+                            success=False,
+                            reason=f"wind-down: {wound_down.reason}",
+                            turns=self._ledger.turns,
+                            thread_id=thread_id,
+                        )
                     case Finish() as finish:
                         self._persist(
                             key=thread_id,
@@ -401,6 +457,64 @@ class AutonomousRunner:
         )
         self._write_artifact("stop-summary.md", body)
 
+    def _project_wind_down(self, capacity: CapacityState) -> WindDown | None:
+        """Forecast remaining capacity, but only while the vendor says we are
+        not already blocked.
+
+        Returning None for every non-Available state is what keeps the plan
+        windows from ever influencing whether a turn is *sent*: once a real
+        rejection lands, the state machine's capacity routing owns it.
+        """
+        if not isinstance(capacity, Available):
+            return None
+        now = self._clock.now()
+        turns = self._ledger.turns
+        projection = forecast(
+            capacity,
+            turns_spent=turns,
+            max_turns=self._budget.max_turns,
+            dollars_spent=self._ledger.dollars,
+            max_dollars=self._budget.max_dollars,
+            observed=BurnRate(
+                turns=turns,
+                elapsed_seconds=self._ledger.elapsed.total_seconds(),
+                dollars=self._ledger.dollars,
+            ),
+            capacity_as_of=now,
+            now=now,
+            policy=self._wind_down_policy,
+        )
+        self._log.debug(
+            "capacity.forecast",
+            headroom=projection.binding.fraction,
+            source=projection.binding.source,
+            turns_until_exhaustion=projection.turns_until_exhaustion,
+        )
+        return should_wind_down(projection, self._wind_down_policy, turns_spent=turns)
+
+    def _write_handoff_marker(
+        self, decision: WindDownAndFinish, thread_id: str | None, remaining: list[str]
+    ) -> None:
+        """Written last, after the summary and state it names, so that a marker
+        on disk means everything it points at is on disk."""
+        if self._handoff_marker_writer is None:
+            return
+        binding = decision.forecast.binding
+        self._handoff_marker_writer(
+            HandoffMarker(
+                run_id=self._run_id,
+                reason=decision.reason,
+                produced_at=self._clock.now(),
+                headroom=binding.fraction,
+                headroom_source=binding.source,
+                resets_at=binding.resets_at,
+                session_id=thread_id,
+                turns_spent=self._ledger.turns,
+                dollars_spent=self._ledger.dollars,
+                remaining_work=tuple(remaining),
+            )
+        )
+
 
 def _permission_mode(sandbox: SandboxMode) -> PermissionMode:
     match sandbox: