refactor: extract run data types from engine into _run_types module

RunStatus, RunConfig, and RunState are data types used by cli, manager,
and UI modules that don't need the engine's execution logic. Separating
them makes engine.py focused on the loop (~390 lines of execution code)
and lets type-only consumers avoid importing the engine's heavy deps.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

src/ralphify/_run_types.py

@@ -0,0 +1,113 @@
+"""Data types for run configuration and state.
+
+These are the core types shared across the engine, CLI, manager, and UI
+modules.  They are intentionally separate from ``engine.py`` so modules
+that only need the types don't pull in the engine's execution logic.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class RunStatus(Enum):
+    """Lifecycle status of a run."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    PAUSED = "paused"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class RunConfig:
+    """All settings for a single run.  Mutable — fields can change mid-run."""
+
+    command: str
+    args: list[str]
+    prompt_file: str
+    prompt_text: str | None = None
+    prompt_name: str | None = None
+    max_iterations: int | None = None
+    delay: float = 0
+    timeout: float | None = None
+    stop_on_error: bool = False
+    log_dir: str | None = None
+    project_root: Path = field(default_factory=lambda: Path("."))
+
+
+@dataclass
+class RunState:
+    """Observable state for a run.
+
+    Control methods (:meth:`request_stop`, :meth:`request_pause`,
+    :meth:`request_resume`) use :class:`threading.Event` so the run loop
+    can react at iteration boundaries without busy-waiting.
+
+    **Threading model**: counters (``iteration``, ``completed``, etc.) are
+    written only by the engine thread and read by API threads.  Under
+    CPython's GIL this is safe — readers may see a briefly stale value,
+    which is acceptable for dashboard display.
+    """
+
+    run_id: str
+    status: RunStatus = RunStatus.PENDING
+    iteration: int = 0
+    completed: int = 0
+    failed: int = 0
+    timed_out: int = 0
+
+    _stop_requested: bool = False
+    _pause_event: threading.Event = field(default_factory=threading.Event)
+    _reload_requested: bool = False
+
+    def __post_init__(self) -> None:
+        # Start un-paused
+        self._pause_event.set()
+
+    def request_stop(self) -> None:
+        """Signal the loop to stop after the current iteration."""
+        self._stop_requested = True
+        # Unpause so the loop can exit
+        self._pause_event.set()
+
+    def request_pause(self) -> None:
+        """Pause the loop between iterations until resumed."""
+        self.status = RunStatus.PAUSED
+        self._pause_event.clear()
+
+    def request_resume(self) -> None:
+        """Resume a paused loop."""
+        self.status = RunStatus.RUNNING
+        self._pause_event.set()
+
+    def request_reload(self) -> None:
+        """Request re-discovery of primitives before the next iteration."""
+        self._reload_requested = True
+
+    @property
+    def stop_requested(self) -> bool:
+        """Whether a stop has been requested."""
+        return self._stop_requested
+
+    @property
+    def paused(self) -> bool:
+        """Whether the run is currently paused."""
+        return not self._pause_event.is_set()
+
+    def wait_for_unpause(self, timeout: float | None = None) -> bool:
+        """Block until unpaused or timeout. Returns True if unpaused."""
+        return self._pause_event.wait(timeout=timeout)
+
+    def consume_reload_request(self) -> bool:
+        """If a reload was requested, clear the flag and return True."""
+        if self._reload_requested:
+            self._reload_requested = False
+            return True
+        return False

src/ralphify/cli.py

@@ -19,7 +19,8 @@
 from ralphify._frontmatter import CHECK_MARKER, CONTEXT_MARKER, INSTRUCTION_MARKER, PROMPT_MARKER
 from ralphify.checks import discover_checks
 from ralphify.contexts import discover_contexts
-from ralphify.engine import RunConfig, RunState, run_loop
+from ralphify._run_types import RunConfig, RunState
+from ralphify.engine import run_loop
 from ralphify.instructions import discover_instructions
 from ralphify.prompts import discover_prompts, is_prompt_name, resolve_prompt_name
 from ralphify.detector import detect_project

src/ralphify/engine.py

@@ -1,8 +1,11 @@
-"""Extracted run loop with structured event emission.
+"""Run loop with structured event emission.
 
-The core ``run_loop`` function is the autonomous agent loop previously
-inlined in ``cli.py:run()``.  It accepts a ``RunConfig``, ``RunState``,
-and ``EventEmitter``, making it reusable from both CLI and UI contexts.
+The core ``run_loop`` function is the autonomous agent loop.  It accepts
+a ``RunConfig``, ``RunState``, and ``EventEmitter``, making it reusable
+from both CLI and UI contexts.
+
+Run data types (``RunStatus``, ``RunConfig``, ``RunState``) live in
+``_run_types.py`` so modules that only need types don't import the engine.
 """
 
 from __future__ import annotations
@@ -11,14 +14,12 @@
 import sys
 import time
 import traceback
-import threading
-from dataclasses import dataclass, field
 from datetime import datetime
-from enum import Enum
 from pathlib import Path
 from typing import Any, NamedTuple
 from ralphify._events import Event, EventEmitter, EventType, NullEmitter
 from ralphify._output import collect_output, format_duration
+from ralphify._run_types import RunConfig, RunState, RunStatus
 from ralphify.checks import (
     Check,
     discover_checks,
@@ -36,106 +37,6 @@
 from ralphify.instructions import Instruction, discover_instructions, resolve_instructions
 
 
-class RunStatus(Enum):
-    """Lifecycle status of a run."""
-
-    PENDING = "pending"
-    RUNNING = "running"
-    PAUSED = "paused"
-    STOPPING = "stopping"
-    STOPPED = "stopped"
-    COMPLETED = "completed"
-    FAILED = "failed"
-
-
-@dataclass
-class RunConfig:
-    """All settings for a single run.  Mutable — fields can change mid-run."""
-
-    command: str
-    args: list[str]
-    prompt_file: str
-    prompt_text: str | None = None
-    prompt_name: str | None = None
-    max_iterations: int | None = None
-    delay: float = 0
-    timeout: float | None = None
-    stop_on_error: bool = False
-    log_dir: str | None = None
-    project_root: Path = field(default_factory=lambda: Path("."))
-
-
-@dataclass
-class RunState:
-    """Observable state for a run.
-
-    Control methods (:meth:`request_stop`, :meth:`request_pause`,
-    :meth:`request_resume`) use :class:`threading.Event` so the run loop
-    can react at iteration boundaries without busy-waiting.
-
-    **Threading model**: counters (``iteration``, ``completed``, etc.) are
-    written only by the engine thread and read by API threads.  Under
-    CPython's GIL this is safe — readers may see a briefly stale value,
-    which is acceptable for dashboard display.
-    """
-
-    run_id: str
-    status: RunStatus = RunStatus.PENDING
-    iteration: int = 0
-    completed: int = 0
-    failed: int = 0
-    timed_out: int = 0
-
-    _stop_requested: bool = False
-    _pause_event: threading.Event = field(default_factory=threading.Event)
-    _reload_requested: bool = False
-
-    def __post_init__(self) -> None:
-        # Start un-paused
-        self._pause_event.set()
-
-    def request_stop(self) -> None:
-        """Signal the loop to stop after the current iteration."""
-        self._stop_requested = True
-        # Unpause so the loop can exit
-        self._pause_event.set()
-
-    def request_pause(self) -> None:
-        """Pause the loop between iterations until resumed."""
-        self.status = RunStatus.PAUSED
-        self._pause_event.clear()
-
-    def request_resume(self) -> None:
-        """Resume a paused loop."""
-        self.status = RunStatus.RUNNING
-        self._pause_event.set()
-
-    def request_reload(self) -> None:
-        """Request re-discovery of primitives before the next iteration."""
-        self._reload_requested = True
-
-    @property
-    def stop_requested(self) -> bool:
-        """Whether a stop has been requested."""
-        return self._stop_requested
-
-    @property
-    def paused(self) -> bool:
-        """Whether the run is currently paused."""
-        return not self._pause_event.is_set()
-
-    def wait_for_unpause(self, timeout: float | None = None) -> bool:
-        """Block until unpaused or timeout. Returns True if unpaused."""
-        return self._pause_event.wait(timeout=timeout)
-
-    def consume_reload_request(self) -> bool:
-        """If a reload was requested, clear the flag and return True."""
-        if self._reload_requested:
-            self._reload_requested = False
-            return True
-        return False
-
-
 def _write_log(
     log_path_dir: Path,
     iteration: int,

src/ralphify/manager.py

@@ -10,7 +10,8 @@
 from dataclasses import dataclass, field
 
 from ralphify._events import EventEmitter, FanoutEmitter, QueueEmitter
-from ralphify.engine import RunConfig, RunState, run_loop
+from ralphify._run_types import RunConfig, RunState
+from ralphify.engine import run_loop
 
 
 @dataclass

src/ralphify/ui/api/runs.py

@@ -7,7 +7,7 @@
 from fastapi import APIRouter, Depends, HTTPException, Request
 
 from ralphify._frontmatter import PROMPT_MARKER
-from ralphify.engine import RunConfig
+from ralphify._run_types import RunConfig
 from ralphify.manager import ManagedRun, RunManager
 from ralphify.prompts import resolve_prompt_name
 from ralphify.ui.models import RunCreate, RunResponse, RunSettingsUpdate

tests/test_engine.py

@@ -7,7 +7,8 @@
 from unittest.mock import patch
 
 from ralphify._events import EventType, NullEmitter, QueueEmitter
-from ralphify.engine import RunConfig, RunState, RunStatus, run_loop
+from ralphify._run_types import RunConfig, RunState, RunStatus
+from ralphify.engine import run_loop
 
 _MOCK_SUBPROCESS = "ralphify.engine.subprocess.run"
 

tests/test_manager.py

@@ -7,7 +7,7 @@
 from unittest.mock import patch
 
 from ralphify._events import Event, EventType, FanoutEmitter, QueueEmitter
-from ralphify.engine import RunConfig, RunStatus
+from ralphify._run_types import RunConfig, RunStatus
 from ralphify.manager import ManagedRun, RunManager
 
 _MOCK_SUBPROCESS = "ralphify.engine.subprocess.run"