sdxloop 0.1.0__py3-none-any.whl

sdxloop/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"

sdxloop/engine/phases.py

@@ -0,0 +1,223 @@
+"""Phase handlers: each turns engine state into one or more worker jobs.
+
+Session strategy per phase (a deliberate design decision):
+
+- DECOMPOSE / PLAN / EXECUTE run as fresh agent sessions with full ("auto")
+  permissions — the microVM is the security boundary.
+- SCRUTINIZE / VALIDATE run as **fresh sessions in the same agent sandbox
+  with read-only permissions**: a fresh session removes conversational
+  anchoring to the executor's claims, read-only permissions stop the critic
+  from "fixing" things itself, and reusing the sandbox preserves the
+  workspace state the critic must inspect (a fresh sandbox per critic would
+  cost minutes and lose it).
+- VERIFY is mechanical — shell commands, no LLM, no opinions.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from sdxloop.config import Config
+from sdxloop.engine.model import PlanModel, TaskGraph, TaskRecord, Verdict
+from sdxloop.engine.prompts import bullet_list, render
+from sdxloop.errors import WorkerError
+from sdxloop.ids import new_job_id
+from sdxloop.worker.client import WorkerClient
+from sdxloop_worker.protocol import JobRequest, JobResult
+
+EVIDENCE_COMMANDS: tuple[tuple[str, str], ...] = (
+    ("git status", "git status --short 2>&1 | head -50"),
+    ("git diff stat", "git diff --stat 2>&1 | head -50"),
+    ("recent files", "find . -type f -newer /tmp -not -path './.git/*' 2>/dev/null | head -30"),
+)
+
+OUTPUT_CLIP = 6_000
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+
+def clip(text: str | None, limit: int = OUTPUT_CLIP) -> str:
+    text = text or ""
+    if len(text) <= limit:
+        return text
+    return f"...(clipped)...\n{text[-limit:]}"
+
+
+class PhaseRunner:
+    """Runs the six phases for one run against the agent sandbox's worker."""
+
+    def __init__(self, agent: WorkerClient, config: Config, run_id: str, outcome: str) -> None:
+        self.agent = agent
+        self.config = config
+        self.run_id = run_id
+        self.outcome = outcome
+
+    # -- job plumbing ------------------------------------------------------
+
+    def _agent_job(
+        self,
+        prompt: str,
+        *,
+        permission_mode: Literal["auto", "read_only"],
+        expect: Literal["text", "json"],
+    ) -> JobResult:
+        job = JobRequest(
+            job_id=new_job_id(),
+            run_id=self.run_id,
+            kind="agent.session",
+            prompt=prompt,
+            model=self.config.model,
+            permission_mode=permission_mode,
+            expect=expect,
+            timeout_s=self.config.budgets.per_job_timeout_s,
+        )
+        result = self.agent.submit(job)
+        if result.status != "ok":
+            assert result.error is not None
+            raise WorkerError(f"agent job failed ({result.error.type}): {result.error.message}")
+        return result
+
+    def _agent_json(
+        self,
+        model_cls: type[ModelT],
+        prompt_name: str,
+        context: dict[str, str],
+        *,
+        permission_mode: Literal["auto", "read_only"] = "auto",
+    ) -> ModelT:
+        """Run a JSON-expecting agent job; one retry with the validation error."""
+        retry_context = ""
+        last_error: Exception | None = None
+        for _ in range(2):
+            prompt = render(prompt_name, retry_context=retry_context, **context)
+            result = self._agent_job(prompt, permission_mode=permission_mode, expect="json")
+            try:
+                return model_cls.model_validate(result.output_json)
+            except ValidationError as exc:
+                last_error = exc
+                retry_context = (
+                    "\n## Previous attempt was invalid\n\n"
+                    "Your previous response failed validation with:\n\n"
+                    f"```\n{exc}\n```\n\nFix the structure and respond again."
+                )
+        raise WorkerError(f"{prompt_name} produced invalid output twice: {last_error}")
+
+    def shell(self, command: str, *, cwd: str | None = None) -> JobResult:
+        job = JobRequest(
+            job_id=new_job_id(),
+            run_id=self.run_id,
+            kind="shell.check",
+            argv=["sh", "-c", command],
+            cwd=cwd,
+            timeout_s=self.config.budgets.per_job_timeout_s,
+        )
+        result = self.agent.submit(job)
+        if result.status != "ok":
+            assert result.error is not None
+            raise WorkerError(f"shell job failed ({result.error.type}): {result.error.message}")
+        return result
+
+    # -- phases ------------------------------------------------------------
+
+    def decompose(self) -> TaskGraph:
+        return self._agent_json(
+            TaskGraph,
+            "decompose",
+            {
+                "outcome": self.outcome,
+                "max_tasks": str(self.config.budgets.max_tasks),
+            },
+        )
+
+    def plan(self, task: TaskRecord) -> PlanModel:
+        return self._agent_json(
+            PlanModel,
+            "plan",
+            {
+                "outcome": self.outcome,
+                "task_id": task.spec.id,
+                "task_title": task.spec.title,
+                "task_description": task.spec.description or "(no further description)",
+                "acceptance_criteria": bullet_list(task.spec.acceptance_criteria),
+                "feedback": task.last_feedback or "(none — first attempt)",
+            },
+        )
+
+    def execute(self, task: TaskRecord, plan: PlanModel) -> JobResult:
+        prompt = render(
+            "execute",
+            outcome=self.outcome,
+            task_id=task.spec.id,
+            task_title=task.spec.title,
+            task_description=task.spec.description or "(no further description)",
+            plan_steps=bullet_list(plan.steps),
+            expected_artifacts=bullet_list(plan.expected_artifacts),
+            feedback=task.last_feedback or "(none — first attempt)",
+        )
+        return self._agent_job(prompt, permission_mode="auto", expect="text")
+
+    def scrutinize(self, task: TaskRecord, plan: PlanModel, executor_report: str) -> Verdict:
+        evidence_parts: list[str] = []
+        for label, command in EVIDENCE_COMMANDS:
+            try:
+                result = self.shell(command)
+            except WorkerError:
+                continue
+            output = clip(result.output_text, 1_500).strip()
+            if output:
+                evidence_parts.append(f"### {label}\n```\n{output}\n```")
+        verdict = self._agent_json(
+            Verdict,
+            "scrutinize",
+            {
+                "task_id": task.spec.id,
+                "task_title": task.spec.title,
+                "task_description": task.spec.description or "(no further description)",
+                "acceptance_criteria": bullet_list(task.spec.acceptance_criteria),
+                "plan_steps": bullet_list(plan.steps),
+                "executor_report": clip(executor_report) or "(executor produced no report)",
+                "evidence": "\n\n".join(evidence_parts) or "(no evidence gathered)",
+            },
+            permission_mode="read_only",
+        )
+        if verdict.verdict not in ("pass", "revise"):
+            raise WorkerError(f"scrutinize returned invalid verdict {verdict.verdict!r}")
+        return verdict
+
+    def verify(self, task: TaskRecord, plan: PlanModel) -> tuple[bool, str]:
+        """Run every verify command; returns (all_passed, failure_feedback)."""
+        commands = list(dict.fromkeys(task.spec.verify_commands + plan.verify_commands))
+        failures: list[str] = []
+        results: list[str] = []
+        for command in commands:
+            result = self.shell(command)
+            output = clip(result.output_text, 1_500)
+            results.append(f"$ {command}\n(exit {result.exit_code})\n{output}")
+            if result.exit_code != 0:
+                failures.append(
+                    f"verify command failed: `{command}` (exit {result.exit_code})\n{output}"
+                )
+        self._last_verify_results = "\n\n".join(results) or "(no verify commands)"
+        return (not failures, "\n\n".join(failures))
+
+    _last_verify_results: str = "(verification not run)"
+
+    def validate(self, task: TaskRecord) -> Verdict:
+        verdict = self._agent_json(
+            Verdict,
+            "validate",
+            {
+                "outcome": self.outcome,
+                "task_id": task.spec.id,
+                "task_title": task.spec.title,
+                "task_description": task.spec.description or "(no further description)",
+                "acceptance_criteria": bullet_list(task.spec.acceptance_criteria),
+                "verify_results": self._last_verify_results,
+            },
+            permission_mode="read_only",
+        )
+        if verdict.verdict not in ("accept", "reject"):
+            raise WorkerError(f"validate returned invalid verdict {verdict.verdict!r}")
+        return verdict

sdxloop/engine/prompts/__init__.py

@@ -0,0 +1,31 @@
+"""Prompt template loading and rendering.
+
+Templates are Markdown files shipped in this package, rendered with
+``string.Template`` ($-substitution) so JSON braces in the templates need no
+escaping. Rendering fails loudly on missing variables — a silently empty
+prompt section is a debugging nightmare.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from importlib import resources
+from string import Template
+
+
+@cache
+def _template(name: str) -> Template:
+    text = (resources.files(__name__) / f"{name}.md").read_text()
+    return Template(text)
+
+
+def render(name: str, **context: str) -> str:
+    """Render prompt template ``name`` with strict substitution."""
+    context.setdefault("retry_context", "")
+    return _template(name).substitute(context)
+
+
+def bullet_list(items: list[str], empty: str = "(none)") -> str:
+    if not items:
+        return empty
+    return "\n".join(f"- {item}" for item in items)

sdxloop/engine/prompts/decompose.md

@@ -0,0 +1,41 @@
+# Decompose an outcome into a task graph
+
+You are the planning stage of an automated engineering loop running inside an
+isolated sandbox. Break the outcome below into a small dependency-ordered set
+of concrete, independently verifiable tasks.
+
+## Outcome
+
+$outcome
+
+## Rules
+
+- At most $max_tasks tasks. Prefer fewer, larger, coherent tasks over many
+  fragments.
+- Every task needs: a stable short `id` (t1, t2, ...), a `title`, a concrete
+  `description` of what to do and where, `depends_on` (ids of prerequisite
+  tasks, often empty), `acceptance_criteria` (specific, checkable statements),
+  and `verify_commands` (shell commands that exit 0 only when the task is
+  genuinely done — e.g. test runs, linters, greps; never `echo`).
+- Tasks must form a DAG: no cycles, dependencies only on listed ids.
+- Work happens in the current working directory of this sandbox.
+
+## Response format
+
+Respond with exactly one fenced JSON block:
+
+```json
+{
+  "tasks": [
+    {
+      "id": "t1",
+      "title": "...",
+      "description": "...",
+      "depends_on": [],
+      "acceptance_criteria": ["..."],
+      "verify_commands": ["..."]
+    }
+  ]
+}
+```
+$retry_context

sdxloop/engine/prompts/execute.md

@@ -0,0 +1,31 @@
+# Execute one task
+
+You are the execution stage of an automated engineering loop running with full
+tool access inside an isolated sandbox. Complete the task below by actually
+doing the work: create and edit files, run commands, and verify as you go.
+Work in the current working directory.
+
+## Overall outcome
+
+$outcome
+
+## Task $task_id: $task_title
+
+$task_description
+
+## Plan
+
+$plan_steps
+
+Expected artifacts:
+$expected_artifacts
+
+## Prior feedback to address
+
+$feedback
+
+## When you are done
+
+Finish with a short summary of what you changed, listing the files you
+created or modified and any commands you ran to check your work. Do not
+claim success for anything you did not actually verify.

sdxloop/engine/prompts/plan.md

@@ -0,0 +1,35 @@
+# Plan one task
+
+You are the planning stage of an automated engineering loop. Produce a
+concrete execution plan for the task below. Do not execute anything yet.
+
+## Overall outcome
+
+$outcome
+
+## Task $task_id: $task_title
+
+$task_description
+
+Acceptance criteria:
+$acceptance_criteria
+
+## Prior feedback
+
+$feedback
+
+## Response format
+
+Respond with exactly one fenced JSON block:
+
+```json
+{
+  "steps": ["specific action 1", "specific action 2"],
+  "expected_artifacts": ["files or outputs this task should produce"],
+  "verify_commands": ["shell commands that exit 0 only when the work is correct"]
+}
+```
+
+Steps must be specific enough that an executor with no other context can
+follow them. Include the task's own verification ideas in `verify_commands`.
+$retry_context

sdxloop/engine/prompts/scrutinize.md

@@ -0,0 +1,43 @@
+# Scrutinize completed work (read-only)
+
+You are an independent, skeptical reviewer in an automated engineering loop.
+You have read-only access: inspect files and run read-only commands, but do
+not modify anything. Judge whether the executed work below actually satisfies
+its task. Look for: incomplete implementations, unhandled edge cases, work
+that was claimed but not done, and deviations from the plan.
+
+## Task $task_id: $task_title
+
+$task_description
+
+Acceptance criteria:
+$acceptance_criteria
+
+## The plan that was supposed to be executed
+
+$plan_steps
+
+## The executor's report
+
+$executor_report
+
+## Workspace evidence
+
+$evidence
+
+## Response format
+
+Respond with exactly one fenced JSON block:
+
+```json
+{
+  "verdict": "pass",
+  "issues": [{"severity": "high", "detail": "..."}],
+  "feedback": "actionable instructions for the executor if verdict is revise"
+}
+```
+
+`verdict` must be `"pass"` or `"revise"`. Verify claims yourself where
+possible instead of trusting the report. Only demand revisions for real
+problems that block the acceptance criteria — not stylistic preferences.
+$retry_context

sdxloop/engine/prompts/validate.md

@@ -0,0 +1,38 @@
+# Validate a task against its acceptance criteria (read-only)
+
+You are the final acceptance gate in an automated engineering loop. You have
+read-only access. The task's work has already been reviewed and its
+verification commands have passed. Your job is different: judge whether the
+result genuinely satisfies each acceptance criterion and serves the overall
+outcome — not whether the code is pretty.
+
+## Overall outcome
+
+$outcome
+
+## Task $task_id: $task_title
+
+$task_description
+
+Acceptance criteria:
+$acceptance_criteria
+
+## Verification results
+
+$verify_results
+
+## Response format
+
+Respond with exactly one fenced JSON block:
+
+```json
+{
+  "verdict": "accept",
+  "issues": [{"severity": "high", "detail": "which criterion fails and why"}],
+  "feedback": "if rejecting: what a new plan must do differently"
+}
+```
+
+`verdict` must be `"accept"` or `"reject"`. Reject only when an acceptance
+criterion is genuinely unmet.
+$retry_context