codex-autorunner 0.1.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

codex_autorunner/core/exceptions.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+
+class Severity(str, Enum):
+    """Error severity levels."""
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+class CodexError(Exception):
+    """Base exception for all codex-autorunner errors."""
+
+    severity: Severity = Severity.WARNING
+    recoverable: bool = True
+    user_message: Optional[str] = None
+
+    def __init__(self, message: str, *, user_message: Optional[str] = None) -> None:
+        super().__init__(message)
+        if user_message is not None:
+            self.user_message = user_message
+
+
+class TransientError(CodexError):
+    """Retryable errors (network, rate limits, temporary failures)."""
+
+    recoverable = True
+    severity = Severity.WARNING
+
+
+class PermanentError(CodexError):
+    """Non-retryable errors (config, auth, validation)."""
+
+    recoverable = False
+    severity = Severity.ERROR
+
+
+class CriticalError(CodexError):
+    """System-level failures requiring intervention."""
+
+    severity = Severity.CRITICAL
+    recoverable = False
+
+
+class CircuitOpenError(CriticalError):
+    """Raised when a circuit breaker is open."""
+
+    def __init__(self, service_name: str, message: Optional[str] = None) -> None:
+        self.service_name = service_name
+        msg = message or f"Circuit breaker is open for {service_name}"
+        super().__init__(
+            msg,
+            user_message=f"{service_name} is temporarily unavailable. Please try again later.",
+        )

codex_autorunner/core/flows/__init__.py

@@ -0,0 +1,25 @@
+from .controller import FlowController
+from .definition import FlowDefinition, StepFn, StepOutcome
+from .models import (
+    FlowArtifact,
+    FlowEvent,
+    FlowEventType,
+    FlowRunRecord,
+    FlowRunStatus,
+)
+from .runtime import FlowRuntime
+from .store import FlowStore
+
+__all__ = [
+    "FlowController",
+    "FlowDefinition",
+    "StepFn",
+    "StepOutcome",
+    "FlowArtifact",
+    "FlowEvent",
+    "FlowEventType",
+    "FlowRunRecord",
+    "FlowRunStatus",
+    "FlowRuntime",
+    "FlowStore",
+]

codex_autorunner/core/flows/controller.py

@@ -0,0 +1,178 @@
+import asyncio
+import logging
+import uuid
+from pathlib import Path
+from typing import Any, AsyncGenerator, Callable, Dict, Optional, Set
+
+from .definition import FlowDefinition
+from .models import FlowEvent, FlowRunRecord, FlowRunStatus
+from .runtime import FlowRuntime
+from .store import FlowStore
+
+_logger = logging.getLogger(__name__)
+
+
+class FlowController:
+    def __init__(
+        self,
+        definition: FlowDefinition,
+        db_path: Path,
+        artifacts_root: Path,
+    ):
+        self.definition = definition
+        self.db_path = db_path
+        self.artifacts_root = artifacts_root
+        self.store = FlowStore(db_path)
+        self._event_listeners: Set[Callable[[FlowEvent], None]] = set()
+        self._lock = asyncio.Lock()
+
+    def initialize(self) -> None:
+        self.artifacts_root.mkdir(parents=True, exist_ok=True)
+        self.store.initialize()
+
+    def shutdown(self) -> None:
+        self.store.close()
+
+    async def start_flow(
+        self,
+        input_data: Dict[str, Any],
+        run_id: Optional[str] = None,
+        initial_state: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> FlowRunRecord:
+        """Create a new flow run record without executing the flow."""
+        if run_id is None:
+            run_id = str(uuid.uuid4())
+
+        async with self._lock:
+            existing = self.store.get_flow_run(run_id)
+            if existing:
+                raise ValueError(f"Flow run {run_id} already exists")
+
+            self._prepare_artifacts_dir(run_id)
+
+            record = self.store.create_flow_run(
+                run_id=run_id,
+                flow_type=self.definition.flow_type,
+                input_data=input_data,
+                metadata=metadata,
+                state=initial_state or {},
+                current_step=self.definition.initial_step,
+            )
+
+            return record
+
+    async def run_flow(
+        self, run_id: str, initial_state: Optional[Dict[str, Any]] = None
+    ) -> FlowRunRecord:
+        """Run or resume a flow to completion in-process (used by workers/tests)."""
+        runtime = FlowRuntime(
+            definition=self.definition,
+            store=self.store,
+            emit_event=self._emit_event,
+        )
+        return await runtime.run_flow(run_id=run_id, initial_state=initial_state)
+
+    async def stop_flow(self, run_id: str) -> FlowRunRecord:
+        record = self.store.set_stop_requested(run_id, True)
+        if not record:
+            raise ValueError(f"Flow run {run_id} not found")
+
+        if record.status == FlowRunStatus.RUNNING:
+            updated = self.store.update_flow_run_status(
+                run_id=run_id,
+                status=FlowRunStatus.STOPPING,
+            )
+            if updated:
+                record = updated
+
+        updated = self.store.get_flow_run(run_id)
+        if not updated:
+            raise RuntimeError(f"Failed to get record for run {run_id}")
+        return updated
+
+    async def resume_flow(self, run_id: str) -> FlowRunRecord:
+        async with self._lock:
+            record = self.store.get_flow_run(run_id)
+            if not record:
+                raise ValueError(f"Flow run {run_id} not found")
+
+            if record.status == FlowRunStatus.RUNNING:
+                raise ValueError(f"Flow run {run_id} is already active")
+
+            cleared = self.store.set_stop_requested(run_id, False)
+            if not cleared:
+                raise RuntimeError(f"Failed to clear stop flag for run {run_id}")
+            return cleared
+
+    def get_status(self, run_id: str) -> Optional[FlowRunRecord]:
+        return self.store.get_flow_run(run_id)
+
+    def list_runs(self, status: Optional[FlowRunStatus] = None) -> list[FlowRunRecord]:
+        return self.store.list_flow_runs(
+            flow_type=self.definition.flow_type, status=status
+        )
+
+    async def stream_events(
+        self, run_id: str, after_seq: Optional[int] = None
+    ) -> AsyncGenerator[FlowEvent, None]:
+        last_seq = after_seq
+
+        while True:
+            events = self.store.get_events(
+                run_id=run_id,
+                after_seq=last_seq,
+                limit=100,
+            )
+
+            for event in events:
+                yield event
+                last_seq = event.seq
+
+            record = self.store.get_flow_run(run_id)
+            if (
+                record
+                and (record.status.is_terminal() or record.status.is_paused())
+                and not events
+            ):
+                break
+
+            await asyncio.sleep(0.5)
+
+    def get_events(
+        self, run_id: str, after_seq: Optional[int] = None
+    ) -> list[FlowEvent]:
+        return self.store.get_events(run_id=run_id, after_seq=after_seq)
+
+    def add_event_listener(self, listener: Callable[[FlowEvent], None]) -> None:
+        self._event_listeners.add(listener)
+
+    def remove_event_listener(self, listener: Callable[[FlowEvent], None]) -> None:
+        self._event_listeners.discard(listener)
+
+    def _emit_event(self, event: FlowEvent) -> None:
+        for listener in self._event_listeners:
+            try:
+                listener(event)
+            except Exception as e:
+                _logger.exception("Error in event listener: %s", e)
+
+    def _prepare_artifacts_dir(self, run_id: str) -> Path:
+        artifacts_dir = self.artifacts_root / run_id
+        artifacts_dir.mkdir(parents=True, exist_ok=True)
+        return artifacts_dir
+
+    def get_artifacts_dir(self, run_id: str) -> Optional[Path]:
+        artifacts_dir = self.artifacts_root / run_id
+        if artifacts_dir.exists():
+            return artifacts_dir
+        return None
+
+    def get_artifacts(self, run_id: str) -> list:
+        return self.store.get_artifacts(run_id)
+
+    async def stream_events_since(
+        self, run_id: str, start_seq: Optional[int] = None
+    ) -> AsyncGenerator[FlowEvent, None]:
+        async for event in self.stream_events(run_id, after_seq=start_seq):
+            yield event

codex_autorunner/core/flows/definition.py

@@ -0,0 +1,82 @@
+import asyncio
+import logging
+from typing import Any, Awaitable, Callable, Dict, Optional, Set, Union
+
+from .models import FlowEventType, FlowRunRecord, FlowRunStatus
+
+_logger = logging.getLogger(__name__)
+
+
+class StepOutcome:
+    def __init__(
+        self,
+        status: FlowRunStatus,
+        next_steps: Optional[Set[str]] = None,
+        output: Optional[Dict[str, Any]] = None,
+        error: Optional[str] = None,
+    ):
+        self.status = status
+        self.next_steps = next_steps or set()
+        self.output = output or {}
+        self.error = error
+
+    @classmethod
+    def continue_to(
+        cls, next_steps: Set[str], output: Optional[Dict[str, Any]] = None
+    ) -> "StepOutcome":
+        return cls(status=FlowRunStatus.RUNNING, next_steps=next_steps, output=output)
+
+    @classmethod
+    def complete(cls, output: Optional[Dict[str, Any]] = None) -> "StepOutcome":
+        return cls(status=FlowRunStatus.COMPLETED, output=output)
+
+    @classmethod
+    def fail(cls, error: str, output: Optional[Dict[str, Any]] = None) -> "StepOutcome":
+        return cls(status=FlowRunStatus.FAILED, error=error, output=output)
+
+    @classmethod
+    def stop(cls, output: Optional[Dict[str, Any]] = None) -> "StepOutcome":
+        return cls(status=FlowRunStatus.STOPPED, output=output)
+
+    @classmethod
+    def pause(cls, output: Optional[Dict[str, Any]] = None) -> "StepOutcome":
+        return cls(status=FlowRunStatus.PAUSED, output=output)
+
+
+EmitEventFn = Callable[[FlowEventType, Dict[str, Any]], None]
+StepFn2 = Callable[[FlowRunRecord, Dict[str, Any]], Awaitable[StepOutcome]]
+StepFn3 = Callable[
+    [FlowRunRecord, Dict[str, Any], Optional[EmitEventFn]], Awaitable[StepOutcome]
+]
+StepFn = Union[StepFn2, StepFn3]
+
+
+class FlowDefinition:
+    def __init__(
+        self,
+        flow_type: str,
+        initial_step: str,
+        steps: Dict[str, StepFn],
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        input_schema: Optional[Dict[str, Any]] = None,
+    ):
+        self.flow_type = flow_type
+        self.initial_step = initial_step
+        self.steps = steps
+        self.name = name or flow_type
+        self.description = description
+        self.input_schema = input_schema
+
+    def validate(self) -> None:
+        if self.initial_step not in self.steps:
+            raise ValueError(
+                f"Initial step '{self.initial_step}' not found in steps: {list(self.steps.keys())}"
+            )
+
+        for step_id, step_fn in self.steps.items():
+            if not asyncio.iscoroutinefunction(step_fn):
+                raise ValueError(
+                    f"Step function for '{step_id}' must be async (coroutine function)"
+                )

codex_autorunner/core/flows/models.py

@@ -0,0 +1,75 @@
+import logging
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+_logger = logging.getLogger(__name__)
+
+
+class FlowRunStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    PAUSED = "paused"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+    def is_terminal(self) -> bool:
+        return self in {self.COMPLETED, self.FAILED, self.STOPPED}
+
+    def is_active(self) -> bool:
+        return self in {self.PENDING, self.RUNNING, self.STOPPING}
+
+    def is_paused(self) -> bool:
+        return self == self.PAUSED
+
+
+class FlowEventType(str, Enum):
+    STEP_STARTED = "step_started"
+    STEP_PROGRESS = "step_progress"
+    STEP_COMPLETED = "step_completed"
+    STEP_FAILED = "step_failed"
+    AGENT_STREAM_DELTA = "agent_stream_delta"
+    APP_SERVER_EVENT = "app_server_event"
+    TOKEN_USAGE = "token_usage"
+    FLOW_STARTED = "flow_started"
+    FLOW_STOPPED = "flow_stopped"
+    FLOW_RESUMED = "flow_resumed"
+    FLOW_COMPLETED = "flow_completed"
+    FLOW_FAILED = "flow_failed"
+
+
+class FlowRunRecord(BaseModel):
+    id: str
+    flow_type: str
+    status: FlowRunStatus
+    input_data: Dict[str, Any] = Field(default_factory=dict)
+    state: Dict[str, Any] = Field(default_factory=dict)
+    current_step: Optional[str] = None
+    stop_requested: bool = False
+    created_at: str
+    started_at: Optional[str] = None
+    finished_at: Optional[str] = None
+    error_message: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class FlowEvent(BaseModel):
+    seq: int
+    id: str
+    run_id: str
+    event_type: FlowEventType
+    timestamp: str
+    data: Dict[str, Any] = Field(default_factory=dict)
+    step_id: Optional[str] = None
+
+
+class FlowArtifact(BaseModel):
+    id: str
+    run_id: str
+    kind: str
+    path: str
+    created_at: str
+    metadata: Dict[str, Any] = Field(default_factory=dict)