codex-autorunner 0.1.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

codex_autorunner/core/exceptions.py

@@ -58,3 +58,7 @@ class CircuitOpenError(CriticalError):
             msg,
             user_message=f"{service_name} is temporarily unavailable. Please try again later.",
         )
+
+
+class AppServerError(CodexError):
+    pass

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,202 @@
+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}")
+            if record.status == FlowRunStatus.COMPLETED:
+                return cleared
+            state = dict(record.state or {})
+            engine = state.get("ticket_engine")
+            if isinstance(engine, dict):
+                engine = dict(engine)
+                engine["status"] = "running"
+                engine.pop("reason", None)
+                engine.pop("reason_details", None)
+                engine.pop("reason_code", None)
+                state["ticket_engine"] = engine
+            state.pop("reason_summary", None)
+
+            updated = self.store.update_flow_run_status(
+                run_id=run_id,
+                status=FlowRunStatus.RUNNING,
+                state=state,
+            )
+            if updated:
+                return 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
+
+    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,88 @@
+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"
+    AGENT_MESSAGE_COMPLETE = "agent_message_complete"
+    AGENT_FAILED = "agent_failed"
+    APP_SERVER_EVENT = "app_server_event"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    APPROVAL_REQUESTED = "approval_requested"
+    TOKEN_USAGE = "token_usage"
+    FLOW_STARTED = "flow_started"
+    FLOW_STOPPED = "flow_stopped"
+    FLOW_RESUMED = "flow_resumed"
+    FLOW_COMPLETED = "flow_completed"
+    FLOW_FAILED = "flow_failed"
+    RUN_STARTED = "run_started"
+    RUN_FINISHED = "run_finished"
+    RUN_STATE_CHANGED = "run_state_changed"
+    RUN_NO_PROGRESS = "run_no_progress"
+    PLAN_UPDATED = "plan_updated"
+    DIFF_UPDATED = "diff_updated"
+    RUN_TIMEOUT = "run_timeout"
+    RUN_CANCELLED = "run_cancelled"
+
+
+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)

codex_autorunner/core/flows/reasons.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .models import FlowRunStatus
+
+MAX_REASON_SUMMARY_LEN = 120
+
+
+def _truncate(text: str, max_len: int = MAX_REASON_SUMMARY_LEN) -> str:
+    if len(text) <= max_len:
+        return text
+    return f"{text[:max_len].rstrip()}…"
+
+
+def ensure_reason_summary(
+    state: Any,
+    *,
+    status: FlowRunStatus,
+    error_message: Optional[str] = None,
+    default: Optional[str] = None,
+) -> dict[str, Any]:
+    """Ensure state includes a short reason_summary when stopping/pausing/failing."""
+    normalized: dict[str, Any] = dict(state) if isinstance(state, dict) else {}
+    existing = normalized.get("reason_summary")
+    if isinstance(existing, str) and existing.strip():
+        return normalized
+
+    reason: Optional[str] = None
+    engine = normalized.get("ticket_engine")
+    if isinstance(engine, dict):
+        engine_reason = engine.get("reason")
+        if isinstance(engine_reason, str) and engine_reason.strip():
+            reason = engine_reason.strip()
+
+    if not reason and isinstance(error_message, str) and error_message.strip():
+        reason = error_message.strip()
+
+    if not reason:
+        if default:
+            reason = default
+        else:
+            fallback = {
+                FlowRunStatus.PAUSED: "Paused",
+                FlowRunStatus.FAILED: "Failed",
+                FlowRunStatus.STOPPED: "Stopped",
+            }
+            reason = fallback.get(status)
+
+    if reason:
+        normalized["reason_summary"] = _truncate(reason)
+    return normalized

codex_autorunner/core/flows/reconciler.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from ..locks import FileLockBusy, file_lock
+from .models import FlowRunRecord, FlowRunStatus
+from .store import UNSET, FlowStore
+from .transition import resolve_flow_transition
+from .worker_process import FlowWorkerHealth, check_worker_health, clear_worker_metadata
+
+_logger = logging.getLogger(__name__)
+
+_ACTIVE_STATUSES = (
+    FlowRunStatus.RUNNING,
+    FlowRunStatus.STOPPING,
+    FlowRunStatus.PAUSED,
+)
+
+
+@dataclass
+class FlowReconcileSummary:
+    checked: int = 0
+    active: int = 0
+    updated: int = 0
+    locked: int = 0
+    errors: int = 0
+
+
+@dataclass
+class FlowReconcileResult:
+    records: list[FlowRunRecord]
+    summary: FlowReconcileSummary
+
+
+def _reconcile_lock_path(repo_root: Path, run_id: str) -> Path:
+    return repo_root / ".codex-autorunner" / "flows" / run_id / "reconcile.lock"
+
+
+def _ensure_worker_not_stale(health: FlowWorkerHealth) -> None:
+    if health.status in {"dead", "mismatch", "invalid"}:
+        try:
+            clear_worker_metadata(health.artifact_path.parent)
+        except Exception:
+            _logger.debug("Failed to clear worker metadata: %s", health.artifact_path)
+
+
+def reconcile_flow_run(
+    repo_root: Path,
+    record: FlowRunRecord,
+    store: FlowStore,
+    *,
+    logger: Optional[logging.Logger] = None,
+) -> tuple[FlowRunRecord, bool, bool]:
+    if record.status not in _ACTIVE_STATUSES:
+        return record, False, False
+
+    lock_path = _reconcile_lock_path(repo_root, record.id)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with file_lock(lock_path, blocking=False):
+            health = check_worker_health(repo_root, record.id)
+            decision = resolve_flow_transition(record, health)
+
+            if (
+                decision.status == record.status
+                and decision.finished_at == record.finished_at
+                and decision.state == (record.state or {})
+            ):
+                return record, False, False
+
+            (logger or _logger).info(
+                "Reconciling flow %s: %s -> %s (%s)",
+                record.id,
+                record.status.value,
+                decision.status.value,
+                decision.note or "reconcile",
+            )
+
+            updated = store.update_flow_run_status(
+                run_id=record.id,
+                status=decision.status,
+                state=decision.state,
+                finished_at=decision.finished_at if decision.finished_at else UNSET,
+            )
+            _ensure_worker_not_stale(health)
+            return (updated or record), bool(updated), False
+    except FileLockBusy:
+        return record, False, True
+    except Exception as exc:
+        (logger or _logger).warning("Failed to reconcile flow %s: %s", record.id, exc)
+        return record, False, False
+
+
+def reconcile_flow_runs(
+    repo_root: Path,
+    *,
+    flow_type: Optional[str] = None,
+    logger: Optional[logging.Logger] = None,
+) -> FlowReconcileResult:
+    db_path = repo_root / ".codex-autorunner" / "flows.db"
+    if not db_path.exists():
+        return FlowReconcileResult(records=[], summary=FlowReconcileSummary())
+    store = FlowStore(db_path)
+    summary = FlowReconcileSummary()
+    records: list[FlowRunRecord] = []
+    try:
+        store.initialize()
+        for record in store.list_flow_runs(flow_type=flow_type):
+            if record.status in _ACTIVE_STATUSES:
+                summary.active += 1
+                summary.checked += 1
+                record, updated, locked = reconcile_flow_run(
+                    repo_root, record, store, logger=logger
+                )
+                if updated:
+                    summary.updated += 1
+                if locked:
+                    summary.locked += 1
+            records.append(record)
+    except Exception as exc:
+        summary.errors += 1
+        (logger or _logger).warning("Flow reconcile run failed: %s", exc)
+    finally:
+        try:
+            store.close()
+        except Exception:
+            pass
+    return FlowReconcileResult(records=records, summary=summary)