sbxloop 0.2.0__py3-none-any.whl

sbxloop/engine/engine.py

@@ -0,0 +1,383 @@
+"""LoopEngine: drives DECOMPOSE → (PLAN → EXECUTE → SCRUTINIZE → VERIFY →
+VALIDATE)* under budgets, with SQLite checkpointing after every transition.
+
+Failure semantics:
+
+- Budget exhaustion (revisions/replans) fails the *task*; dependents are
+  skipped and the run continues, finishing ``failed`` if any task failed.
+- Infrastructure errors (worker/sbx crashes) propagate after state is
+  persisted — equivalent to a kill. ``resume()`` re-provisions a fresh
+  sandbox pair (sandboxes are cattle; the workspace and SQLite state
+  persist on the host) and continues from the last committed transition:
+  a phase whose result was never committed re-runs from its start.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable, Sequence
+
+from sbxloop.config import Config, load_config, load_dotenv_file
+from sbxloop.engine.model import (
+    RESUMABLE_RUN_STATES,
+    RunResult,
+    RunState,
+    TaskRecord,
+    TaskState,
+)
+from sbxloop.engine.phases import PhaseRunner, clip
+from sbxloop.engine.store import StateStore
+from sbxloop.errors import BudgetExceededError, SdxloopError, StateError
+from sbxloop.events import EventBus, Hook, HostEventTypes
+from sbxloop.gh.ops import GithubOps
+from sbxloop.gh.reporter import GithubReporterHook
+from sbxloop.ids import new_run_id
+from sbxloop.sbx.cli import SbxCLI
+from sbxloop.sbx.provision import Provisioner
+from sbxloop.worker.client import WorkerClient
+
+
+class LoopEngine:
+    def __init__(
+        self,
+        config: Config | None = None,
+        *,
+        store: StateStore | None = None,
+        bus: EventBus | None = None,
+        hooks: Sequence[Hook] = (),
+        sbx: SbxCLI | None = None,
+        worker_python: str | None = None,
+        install_workers: bool | None = None,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        # Library parity with the CLI: a ./.env supplies tokens/settings even
+        # when the caller passes a prebuilt Config (real env vars still win).
+        load_dotenv_file()
+        self.config = config or load_config()
+        self.store = store or StateStore(self.config.state_dir / "state.db")
+        self.bus = bus or EventBus()
+        self.sbx = sbx or SbxCLI(app_name=self.config.app_name or None)
+        self.worker_python = (
+            worker_python if worker_python is not None else (self.config.worker_python)
+        )
+        self.install_workers = (
+            install_workers if install_workers is not None else self.config.install_workers
+        )
+        self.clock = clock
+        for hook in hooks:
+            self.bus.attach_hook(hook)
+        self.bus.subscribe(self._persist_event)
+
+    def _persist_event(self, event: object) -> None:
+        from sbxloop_worker.protocol import Event
+
+        assert isinstance(event, Event)
+        self.store.append_event(event)
+
+    # -- public API --------------------------------------------------------
+
+    def start(self, outcome: str, *, run_id: str | None = None) -> RunResult:
+        run_id = run_id or new_run_id()
+        self.store.create_run(run_id, outcome, self.config.model_dump_json())
+        self.bus.emit(HostEventTypes.RUN_START, run_id, outcome=outcome)
+        return self._drive(run_id, outcome)
+
+    def resume(self, run_id: str) -> RunResult:
+        run = self.store.get_run(run_id)
+        if run.state not in RESUMABLE_RUN_STATES:
+            raise StateError(f"run {run_id} is {run.state}; only unfinished runs can resume")
+        self.bus.emit(HostEventTypes.RUN_START, run_id, outcome=run.outcome, resumed=True)
+        return self._drive(run_id, run.outcome)
+
+    def cancel(self, run_id: str) -> None:
+        self.store.get_run(run_id)  # raises for unknown runs
+        self.store.set_run_state(run_id, "cancelled")
+
+    # -- run driver --------------------------------------------------------
+
+    def _drive(self, run_id: str, outcome: str) -> RunResult:
+        deadline = self.clock() + self.config.budgets.max_wall_clock_s
+        self._set_run_state(run_id, "provisioning")
+        provisioner = Provisioner(self.sbx, self.config, self.bus)
+        pair = provisioner.ensure_pair(run_id)
+        try:
+            with pair:
+                agent = WorkerClient(
+                    pair.agent,
+                    self.bus,
+                    transport=self.config.worker_transport,
+                    python=self.worker_python,
+                )
+                github = WorkerClient(
+                    pair.github,
+                    self.bus,
+                    transport=self.config.worker_transport,
+                    python=self.worker_python,
+                )
+                if self.install_workers:
+                    agent.install(extras="copilot")
+                    github.install(extras="")
+                detach = self._attach_reporter(github, run_id)
+                try:
+                    phases = PhaseRunner(agent, self.config, run_id, outcome)
+                    state = self._run_phases(run_id, phases, deadline)
+                finally:
+                    detach()
+        except SdxloopError:
+            # State is already persisted; the exception is the kill signal.
+            raise
+        self._set_run_state(run_id, state)
+        tasks = self.store.get_tasks(run_id)
+        self.bus.emit(HostEventTypes.RUN_END, run_id, state=state)
+        return RunResult(run_id=run_id, state=state, tasks=tasks)
+
+    def _attach_reporter(self, github: WorkerClient, run_id: str) -> Callable[[], None]:
+        repo = self.config.github.report_repo
+        if not repo:
+            return lambda: None
+        hook = GithubReporterHook(GithubOps(github, run_id), repo)
+        return self.bus.attach_hook(hook)
+
+    def _run_phases(self, run_id: str, phases: PhaseRunner, deadline: float) -> RunState:
+        tasks = self.store.get_tasks(run_id)
+        if not tasks:
+            self._set_run_state(run_id, "decomposing")
+            started = time.time()
+            graph = phases.decompose()
+            if len(graph.tasks) > self.config.budgets.max_tasks:
+                raise BudgetExceededError(
+                    f"decomposition produced {len(graph.tasks)} tasks "
+                    f"(max {self.config.budgets.max_tasks})"
+                )
+            ordered = graph.topo_order()
+            self.store.save_tasks(run_id, ordered)
+            self.store.record_phase(
+                run_id,
+                "decompose",
+                task_id=None,
+                attempt=1,
+                status="ok",
+                output_json=graph.model_dump_json(),
+                started_at=started,
+            )
+            tasks = self.store.get_tasks(run_id)
+
+        self._set_run_state(run_id, "running")
+        failed_ids: set[str] = {t.spec.id for t in tasks if t.state == "failed"}
+        skipped_ids: set[str] = {t.spec.id for t in tasks if t.state == "skipped"}
+        for task in tasks:
+            if task.terminal:
+                failed_ids |= {task.spec.id} if task.state == "failed" else set()
+                continue
+            blocked = [d for d in task.spec.depends_on if d in failed_ids | skipped_ids]
+            if blocked:
+                task.state = "skipped"
+                skipped_ids.add(task.spec.id)
+                self.store.update_task(run_id, task)
+                self._emit_task_end(run_id, task)
+                continue
+            self._run_task(run_id, phases, task, deadline)
+            if task.state == "failed":
+                failed_ids.add(task.spec.id)
+
+        self._set_run_state(run_id, "finalizing")
+        return "failed" if failed_ids or skipped_ids else "completed"
+
+    # -- task state machine ------------------------------------------------
+
+    def _run_task(
+        self,
+        run_id: str,
+        phases: PhaseRunner,
+        task: TaskRecord,
+        deadline: float,
+    ) -> None:
+        budgets = self.config.budgets
+        if task.state == "pending":
+            self._set_task_state(run_id, task, "planning")
+        self.bus.emit(
+            HostEventTypes.TASK_START, run_id, task_id=task.spec.id, title=task.spec.title
+        )
+        # Resume mapping: executing/scrutinizing restart at executing (the
+        # plan is persisted); a missing plan always restarts at planning.
+        if task.state in ("executing", "scrutinizing") and task.plan is None:
+            self._set_task_state(run_id, task, "planning")
+        if task.state in ("verifying", "validating") and task.plan is None:
+            self._set_task_state(run_id, task, "planning")
+        if task.state == "scrutinizing":
+            self._set_task_state(run_id, task, "executing")
+
+        while not task.terminal:
+            self._check_cancelled_and_clock(run_id, deadline)
+            if task.state == "planning":
+                self._phase_plan(run_id, phases, task)
+            elif task.state == "executing":
+                self._phase_execute_and_scrutinize(run_id, phases, task, budgets)
+            elif task.state == "verifying":
+                self._phase_verify(run_id, phases, task, budgets)
+            elif task.state == "validating":
+                self._phase_validate(run_id, phases, task, budgets)
+            else:  # pragma: no cover - defensive
+                raise StateError(f"task {task.spec.id} in unexpected state {task.state}")
+
+        self._emit_task_end(run_id, task)
+
+    def _phase_plan(self, run_id: str, phases: PhaseRunner, task: TaskRecord) -> None:
+        started = time.time()
+        plan = phases.plan(task)
+        task.plan = plan
+        self.store.record_phase(
+            run_id,
+            "plan",
+            task_id=task.spec.id,
+            attempt=task.replans + 1,
+            status="ok",
+            output_json=plan.model_dump_json(),
+            started_at=started,
+        )
+        self._set_task_state(run_id, task, "executing")
+
+    def _phase_execute_and_scrutinize(
+        self,
+        run_id: str,
+        phases: PhaseRunner,
+        task: TaskRecord,
+        budgets: object,
+    ) -> None:
+        assert task.plan is not None
+        started = time.time()
+        result = phases.execute(task, task.plan)
+        task.session_id = result.session_id
+        executor_report = clip(result.output_text)
+        self.store.record_phase(
+            run_id,
+            "execute",
+            task_id=task.spec.id,
+            attempt=task.revisions + 1,
+            status="ok",
+            output_json=json.dumps({"report": executor_report, "session_id": result.session_id}),
+            started_at=started,
+        )
+        self._set_task_state(run_id, task, "scrutinizing")
+
+        started = time.time()
+        verdict = phases.scrutinize(task, task.plan, executor_report)
+        self.store.record_phase(
+            run_id,
+            "scrutinize",
+            task_id=task.spec.id,
+            attempt=task.revisions + 1,
+            status=verdict.verdict,
+            output_json=verdict.model_dump_json(),
+            started_at=started,
+        )
+        if verdict.verdict == "revise":
+            self._register_revision(run_id, task, verdict.feedback or "scrutiny found issues")
+        else:
+            task.last_feedback = ""
+            self._set_task_state(run_id, task, "verifying")
+
+    def _phase_verify(
+        self,
+        run_id: str,
+        phases: PhaseRunner,
+        task: TaskRecord,
+        budgets: object,
+    ) -> None:
+        assert task.plan is not None
+        started = time.time()
+        passed, feedback = phases.verify(task, task.plan)
+        self.store.record_phase(
+            run_id,
+            "verify",
+            task_id=task.spec.id,
+            attempt=task.revisions + 1,
+            status="ok" if passed else "failed",
+            output_json=json.dumps({"passed": passed, "feedback": clip(feedback)}),
+            started_at=started,
+        )
+        if passed:
+            self._set_task_state(run_id, task, "validating")
+        else:
+            self._register_revision(run_id, task, feedback)
+
+    def _phase_validate(
+        self,
+        run_id: str,
+        phases: PhaseRunner,
+        task: TaskRecord,
+        budgets: object,
+    ) -> None:
+        started = time.time()
+        verdict = phases.validate(task)
+        self.store.record_phase(
+            run_id,
+            "validate",
+            task_id=task.spec.id,
+            attempt=task.replans + 1,
+            status=verdict.verdict,
+            output_json=verdict.model_dump_json(),
+            started_at=started,
+        )
+        if verdict.verdict == "accept":
+            self._set_task_state(run_id, task, "done")
+            return
+        task.replans += 1
+        if task.replans > self.config.budgets.max_replans_per_task:
+            task.last_feedback = verdict.feedback
+            self._set_task_state(run_id, task, "failed")
+            return
+        task.last_feedback = verdict.feedback or "validation rejected the result"
+        task.plan = None
+        task.revisions = 0
+        self._set_task_state(run_id, task, "planning")
+
+    def _register_revision(self, run_id: str, task: TaskRecord, feedback: str) -> None:
+        task.revisions += 1
+        task.last_feedback = feedback
+        if task.revisions > self.config.budgets.max_revisions_per_task:
+            self._set_task_state(run_id, task, "failed")
+        else:
+            self._set_task_state(run_id, task, "executing")
+
+    # -- bookkeeping -------------------------------------------------------
+
+    def _check_cancelled_and_clock(self, run_id: str, deadline: float) -> None:
+        if self.store.get_run(run_id).state == "cancelled":
+            raise StateError(f"run {run_id} was cancelled")
+        if self.clock() > deadline:
+            self._set_run_state(run_id, "failed")
+            raise BudgetExceededError(
+                f"run {run_id} exceeded max_wall_clock_s={self.config.budgets.max_wall_clock_s}"
+            )
+
+    def _set_run_state(self, run_id: str, state: RunState) -> None:
+        self.store.set_run_state(run_id, state)
+        self.bus.emit(HostEventTypes.RUN_STATE, run_id, state=state)
+
+    def _set_task_state(self, run_id: str, task: TaskRecord, state: TaskState) -> None:
+        task.state = state
+        self.store.update_task(run_id, task)
+        self.bus.emit(
+            HostEventTypes.TASK_STATE,
+            run_id,
+            task_id=task.spec.id,
+            state=state,
+            revisions=task.revisions,
+            replans=task.replans,
+        )
+
+    def _emit_task_end(self, run_id: str, task: TaskRecord) -> None:
+        self.bus.emit(
+            HostEventTypes.TASK_END,
+            run_id,
+            task_id=task.spec.id,
+            title=task.spec.title,
+            state=task.state,
+        )
+
+
+def run_outcome(outcome: str, config: Config | None = None) -> RunResult:
+    """Convenience one-shot API: run an outcome with default wiring."""
+    return LoopEngine(config or load_config()).start(outcome)

sbxloop/engine/model.py

@@ -0,0 +1,151 @@
+"""Engine domain models: runs, tasks, plans, verdicts, the task graph."""
+
+from __future__ import annotations
+
+from graphlib import CycleError, TopologicalSorter
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+RunState = Literal[
+    "created",
+    "provisioning",
+    "decomposing",
+    "running",
+    "finalizing",
+    "completed",
+    "failed",
+    "cancelled",
+]
+
+TaskState = Literal[
+    "pending",
+    "planning",
+    "executing",
+    "scrutinizing",
+    "verifying",
+    "validating",
+    "done",
+    "failed",
+    "skipped",
+]
+
+TERMINAL_TASK_STATES: frozenset[str] = frozenset({"done", "failed", "skipped"})
+RESUMABLE_RUN_STATES: frozenset[str] = frozenset(
+    {"created", "provisioning", "decomposing", "running", "finalizing", "failed"}
+)
+
+Phase = Literal["decompose", "plan", "execute", "scrutinize", "verify", "validate"]
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class TaskSpec(_Model):
+    """One unit of the decomposed outcome (agent-authored, engine-validated)."""
+
+    id: str
+    title: str
+    description: str = ""
+    depends_on: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    verify_commands: list[str] = Field(default_factory=list)
+
+
+class TaskGraph(_Model):
+    tasks: list[TaskSpec]
+
+    @model_validator(mode="after")
+    def _check_graph(self) -> TaskGraph:
+        if not self.tasks:
+            raise ValueError("task graph must contain at least one task")
+        ids = [t.id for t in self.tasks]
+        if len(set(ids)) != len(ids):
+            raise ValueError(f"duplicate task ids: {ids}")
+        known = set(ids)
+        for task in self.tasks:
+            unknown = [d for d in task.depends_on if d not in known]
+            if unknown:
+                raise ValueError(f"task {task.id} depends on unknown tasks: {unknown}")
+            if task.id in task.depends_on:
+                raise ValueError(f"task {task.id} depends on itself")
+        try:
+            self.topo_order()
+        except CycleError as exc:
+            raise ValueError(f"task graph contains a cycle: {exc.args}") from exc
+        return self
+
+    def topo_order(self) -> list[TaskSpec]:
+        """Dependency order; ties broken by authored order (depth, position)."""
+        by_id = {t.id: t for t in self.tasks}
+        # TopologicalSorter validates the cycle; the actual ordering is
+        # deterministic: dependency depth first, authored position second.
+        list(TopologicalSorter({t.id: set(t.depends_on) for t in self.tasks}).static_order())
+        position = {t.id: i for i, t in enumerate(self.tasks)}
+        return sorted(
+            self.tasks,
+            key=lambda t: (self._depth(t, by_id), position[t.id]),
+        )
+
+    def _depth(self, task: TaskSpec, by_id: dict[str, TaskSpec]) -> int:
+        if not task.depends_on:
+            return 0
+        return 1 + max(self._depth(by_id[d], by_id) for d in task.depends_on)
+
+
+class PlanModel(_Model):
+    """The agent's plan for one task."""
+
+    steps: list[str]
+    expected_artifacts: list[str] = Field(default_factory=list)
+    verify_commands: list[str] = Field(default_factory=list)
+
+
+class Issue(_Model):
+    severity: Literal["low", "medium", "high"] = "medium"
+    detail: str
+
+
+class Verdict(_Model):
+    """Critic output: scrutinize uses pass/revise, validate uses accept/reject."""
+
+    verdict: Literal["pass", "revise", "accept", "reject"]
+    issues: list[Issue] = Field(default_factory=list)
+    feedback: str = ""
+
+
+class TaskRecord(_Model):
+    """Persisted per-task state."""
+
+    spec: TaskSpec
+    state: TaskState = "pending"
+    revisions: int = 0
+    replans: int = 0
+    last_feedback: str = ""
+    session_id: str | None = None
+    plan: PlanModel | None = None
+
+    @property
+    def terminal(self) -> bool:
+        return self.state in TERMINAL_TASK_STATES
+
+
+class RunRecord(_Model):
+    run_id: str
+    outcome: str
+    state: RunState
+    created_at: float
+    updated_at: float
+
+
+class RunResult(_Model):
+    """What LoopEngine.start()/resume() returns to callers."""
+
+    run_id: str
+    state: RunState
+    tasks: list[TaskRecord] = Field(default_factory=list)
+
+    @property
+    def succeeded(self) -> bool:
+        return self.state == "completed"