hyperloop 0.1.0__py3-none-any.whl

hyperloop/compose.py

@@ -0,0 +1,126 @@
+"""Prompt composition — assembles worker prompts from base + overlay + task context.
+
+Three layers composed at spawn time:
+1. Base prompt from base/{role}.yaml
+2. Process overlay from specs/prompts/{role}-overlay.yaml (if exists)
+3. Task context: spec content, findings, traceability refs (spec_ref, task_id)
+
+For v1, kustomize integration (project overlay) is skipped. The orchestrator
+reads base YAML files directly and injects process overlays + task context.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+import yaml
+
+if TYPE_CHECKING:
+    from hyperloop.ports.state import StateStore
+
+
+class PromptComposer:
+    """Composes agent prompts from base definitions + overlays + task context."""
+
+    def __init__(self, base_dir: str | Path, state: StateStore) -> None:
+        """Load base agent definitions from base_dir.
+
+        Args:
+            base_dir: Path to the directory containing base agent YAML files.
+            state: StateStore used to read process overlays and spec files
+                   from the target repo.
+        """
+        self._base_dir = Path(base_dir)
+        self._state = state
+        self._base_prompts: dict[str, str] = {}
+        self._load_base_definitions()
+
+    def _load_base_definitions(self) -> None:
+        """Load all base agent YAML files and extract their prompt fields."""
+        for yaml_file in self._base_dir.glob("*.yaml"):
+            with open(yaml_file) as f:
+                doc = yaml.safe_load(f)
+            if doc and doc.get("kind") == "Agent" and "prompt" in doc:
+                name = doc["name"]
+                self._base_prompts[name] = doc["prompt"]
+
+    def compose(
+        self,
+        role: str,
+        task_id: str,
+        spec_ref: str,
+        findings: str,
+    ) -> str:
+        """Compose the full prompt for a worker.
+
+        Layers:
+        1. Base prompt from base/{role}.yaml
+        2. Process overlay from specs/prompts/{role}-overlay.yaml (if exists)
+        3. Task context: spec content, findings, traceability refs
+
+        Args:
+            role: Agent role name (e.g. "implementer", "verifier").
+            task_id: Task identifier (e.g. "task-027").
+            spec_ref: Path to the originating spec file (e.g. "specs/persistence.md").
+            findings: Findings from prior rounds (empty string if none).
+
+        Returns:
+            The composed prompt string ready to pass to a worker.
+
+        Raises:
+            ValueError: If the role has no base agent definition.
+        """
+        # Layer 1: Base prompt
+        if role not in self._base_prompts:
+            msg = f"Unknown role '{role}': no base agent definition found in {self._base_dir}"
+            raise ValueError(msg)
+
+        base_prompt = self._base_prompts[role]
+
+        # Replace template variables
+        prompt = base_prompt.replace("{spec_ref}", spec_ref).replace("{task_id}", task_id)
+
+        # Layer 2: Process overlay (from target repo specs/prompts/)
+        overlay_path = f"specs/prompts/{role}-overlay.yaml"
+        overlay_content = self._state.read_file(overlay_path)
+        overlay_text = ""
+        if overlay_content is not None:
+            overlay_text = self._extract_overlay_prompt(overlay_content)
+
+        # Layer 3: Task context — spec content
+        spec_content = self._state.read_file(spec_ref)
+
+        # Assemble the final prompt
+        sections: list[str] = [prompt.rstrip()]
+
+        if overlay_text:
+            sections.append(f"## Process Overlay\n{overlay_text}")
+
+        if spec_content is not None:
+            sections.append(f"## Spec\n{spec_content}")
+        else:
+            sections.append(
+                f"## Spec\n[Spec file '{spec_ref}' not found. Proceed with available context.]"
+            )
+
+        if findings:
+            sections.append(f"## Findings\n{findings}")
+
+        return "\n\n".join(sections) + "\n"
+
+    @staticmethod
+    def _extract_overlay_prompt(raw_yaml: str) -> str:
+        """Extract prompt or content from overlay YAML.
+
+        Overlay files may contain a 'prompt' field (like agent definitions)
+        or raw text content. Handles both.
+        """
+        try:
+            doc = yaml.safe_load(raw_yaml)
+            if isinstance(doc, dict) and "prompt" in doc:
+                return str(cast("dict[str, object]", doc)["prompt"]).strip()
+        except yaml.YAMLError:
+            pass
+        # Fall back to raw content
+        return raw_yaml.strip()

hyperloop/config.py

@@ -0,0 +1,161 @@
+"""Configuration loading — parse .hyperloop.yaml with defaults.
+
+Reads the YAML config file, applies defaults for missing fields, and
+returns a frozen Config dataclass. CLI arguments can override file values.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+import yaml
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ConfigError(Exception):
+    """Raised when the config file cannot be parsed or is structurally invalid."""
+
+
+@dataclass(frozen=True)
+class Config:
+    """Typed, immutable configuration for the orchestrator."""
+
+    repo: str | None  # owner/repo or inferred from git remote
+    base_branch: str  # default: "main"
+    specs_dir: str  # default: "specs"
+    overlay: str | None  # path or git URL to kustomization dir
+    runtime: str  # "local" (v1 only)
+    max_workers: int  # default: 6
+    auto_merge: bool  # default: True
+    merge_strategy: str  # default: "squash"
+    delete_branch: bool  # default: True
+    poll_interval: int  # default: 30
+    max_rounds: int  # default: 50
+    max_rebase_attempts: int  # default: 3
+
+
+def _defaults() -> dict[str, object]:
+    """Return the full default config as a flat dict."""
+    return {
+        "repo": None,
+        "base_branch": "main",
+        "specs_dir": "specs",
+        "overlay": None,
+        "runtime": "local",
+        "max_workers": 6,
+        "auto_merge": True,
+        "merge_strategy": "squash",
+        "delete_branch": True,
+        "poll_interval": 30,
+        "max_rounds": 50,
+        "max_rebase_attempts": 3,
+    }
+
+
+def _flatten_yaml(raw: dict[str, object]) -> dict[str, object]:
+    """Flatten the nested YAML structure into a flat dict matching Config fields.
+
+    The YAML has nested sections (target, runtime, merge) but Config is flat.
+    """
+    flat: dict[str, object] = {}
+
+    # Top-level scalars
+    for key in ("overlay", "poll_interval", "max_rounds", "max_rebase_attempts"):
+        if key in raw:
+            flat[key] = raw[key]
+
+    # target section
+    target = raw.get("target")
+    if isinstance(target, dict):
+        if "repo" in target:
+            flat["repo"] = target["repo"]
+        if "base_branch" in target:
+            flat["base_branch"] = target["base_branch"]
+        if "specs_dir" in target:
+            flat["specs_dir"] = target["specs_dir"]
+
+    # runtime section
+    runtime = raw.get("runtime")
+    if isinstance(runtime, dict):
+        if "default" in runtime:
+            flat["runtime"] = runtime["default"]
+        if "max_workers" in runtime:
+            flat["max_workers"] = runtime["max_workers"]
+
+    # merge section
+    merge = raw.get("merge")
+    if isinstance(merge, dict):
+        if "auto_merge" in merge:
+            flat["auto_merge"] = merge["auto_merge"]
+        if "strategy" in merge:
+            flat["merge_strategy"] = merge["strategy"]
+        if "delete_branch" in merge:
+            flat["delete_branch"] = merge["delete_branch"]
+
+    return flat
+
+
+def load_config(
+    path: Path | None = None,
+    *,
+    repo: str | None = None,
+    base_branch: str | None = None,
+    max_workers: int | None = None,
+) -> Config:
+    """Load config from a YAML file, with defaults for missing fields.
+
+    Args:
+        path: Path to .hyperloop.yaml. If None or non-existent, use all defaults.
+        repo: CLI override for target.repo.
+        base_branch: CLI override for target.base_branch.
+        max_workers: CLI override for runtime.max_workers.
+
+    Returns:
+        A frozen Config instance.
+
+    Raises:
+        ConfigError: If the file exists but contains invalid YAML or is not a mapping.
+    """
+    values = _defaults()
+
+    # Load from file if it exists
+    if path is not None and path.exists():
+        try:
+            raw = yaml.safe_load(path.read_text())
+        except yaml.YAMLError as exc:
+            msg = f"Failed to parse config file {path}: {exc}"
+            raise ConfigError(msg) from exc
+
+        if raw is not None:
+            if not isinstance(raw, dict):
+                msg = f"Config file {path} must be a YAML mapping, got {type(raw).__name__}"
+                raise ConfigError(msg)
+
+            file_values = _flatten_yaml(cast("dict[str, object]", raw))
+            values.update(file_values)
+
+    # Apply CLI overrides (only if not None)
+    if repo is not None:
+        values["repo"] = repo
+    if base_branch is not None:
+        values["base_branch"] = base_branch
+    if max_workers is not None:
+        values["max_workers"] = max_workers
+
+    return Config(
+        repo=values["repo"],  # type: ignore[arg-type]
+        base_branch=str(values["base_branch"]),
+        specs_dir=str(values["specs_dir"]),
+        overlay=values["overlay"] if values["overlay"] is not None else None,  # type: ignore[arg-type]
+        runtime=str(values["runtime"]),
+        max_workers=int(values["max_workers"]),  # type: ignore[arg-type]
+        auto_merge=bool(values["auto_merge"]),
+        merge_strategy=str(values["merge_strategy"]),
+        delete_branch=bool(values["delete_branch"]),
+        poll_interval=int(values["poll_interval"]),  # type: ignore[arg-type]
+        max_rounds=int(values["max_rounds"]),  # type: ignore[arg-type]
+        max_rebase_attempts=int(values["max_rebase_attempts"]),  # type: ignore[arg-type]
+    )

hyperloop/domain/decide.py

@@ -0,0 +1,104 @@
+"""Decision function — given a World snapshot, return a list of Actions.
+
+This is the orchestrator's brain: a pure function with no I/O dependencies.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hyperloop.domain.model import (
+    AdvanceTask,
+    Halt,
+    ReapWorker,
+    SpawnWorker,
+    TaskStatus,
+)
+
+if TYPE_CHECKING:
+    from hyperloop.domain.model import Action, Task, World
+
+
+def _deps_met(task: Task, tasks: dict[str, Task]) -> bool:
+    """Check if all dependencies of a task are complete."""
+    for dep_id in task.deps:
+        dep = tasks.get(dep_id)
+        if dep is None or dep.status != TaskStatus.COMPLETE:
+            return False
+    return True
+
+
+def _task_has_worker(task_id: str, world: World) -> bool:
+    """Check if a task has any worker (running, done, or failed).
+
+    Tasks with a worker in any state should not be re-spawned: running workers
+    are active, done/failed workers are about to be reaped by the loop.
+    """
+    return any(ws.task_id == task_id for ws in world.workers.values())
+
+
+def decide(world: World, max_workers: int, max_rounds: int) -> list[Action]:
+    """Decide what actions to take given the current world state.
+
+    Returns an ordered list of actions: reaps first, then advances, then spawns,
+    then halt if applicable.
+    """
+    actions: list[Action] = []
+
+    # ---- 1. Reap finished workers (status == "done" or "failed") -----------
+    for ws in world.workers.values():
+        if ws.status in ("done", "failed"):
+            actions.append(ReapWorker(task_id=ws.task_id))
+
+    # ---- 2. Check for tasks that hit max_rounds → AdvanceTask + Halt ------
+    for task in world.tasks.values():
+        if task.status == TaskStatus.IN_PROGRESS and task.round >= max_rounds:
+            actions.append(AdvanceTask(task_id=task.id, to_status=TaskStatus.FAILED, to_phase=None))
+            actions.append(Halt(reason=f"task {task.id} exceeded max_rounds ({max_rounds})"))
+            return actions
+
+    # ---- 3. Count active (running) workers ---------------------------------
+    active_count = sum(1 for ws in world.workers.values() if ws.status == "running")
+
+    # ---- 4. Find eligible tasks to spawn -----------------------------------
+    # Priority order:
+    #   1. needs-rebase tasks (rebase-resolver, from merge conflict handling)
+    #   2. in-progress without a worker (crash recovery / pipeline resume)
+    #   3. not-started with all deps met
+    #
+    # The role is a hint: "rebase-resolver" for needs-rebase tasks,
+    # "implementer" as a default for others. The loop overrides the role
+    # for in-progress tasks based on their pipeline position.
+    needs_rebase: list[Task] = []
+    resuming: list[Task] = []
+    ready: list[Task] = []
+
+    for task in world.tasks.values():
+        if task.status == TaskStatus.NEEDS_REBASE and not _task_has_worker(task.id, world):
+            needs_rebase.append(task)
+        elif task.status == TaskStatus.IN_PROGRESS and not _task_has_worker(task.id, world):
+            resuming.append(task)
+        elif task.status == TaskStatus.NOT_STARTED and _deps_met(task, world.tasks):
+            ready.append(task)
+
+    # Stable sort by task id for determinism
+    needs_rebase.sort(key=lambda t: t.id)
+    resuming.sort(key=lambda t: t.id)
+    ready.sort(key=lambda t: t.id)
+
+    eligible = needs_rebase + resuming + ready
+    slots = max_workers - active_count
+    to_spawn = eligible[:slots] if slots > 0 else []
+
+    for task in to_spawn:
+        role = "rebase-resolver" if task.status == TaskStatus.NEEDS_REBASE else "implementer"
+        actions.append(SpawnWorker(task_id=task.id, role=role))
+
+    # ---- 5. Check convergence: all complete + no workers → Halt ------------
+    all_complete = all(t.status == TaskStatus.COMPLETE for t in world.tasks.values())
+    no_workers = len(world.workers) == 0
+
+    if world.tasks and all_complete and no_workers:
+        actions.append(Halt(reason="all tasks complete"))
+
+    return actions

hyperloop/domain/deps.py

@@ -0,0 +1,66 @@
+"""Dependency cycle detection for the task graph.
+
+Pure function, no I/O. Used by intake to reject dependency cycles.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from hyperloop.domain.model import Task
+
+
+def detect_cycles(tasks: dict[str, Task]) -> list[list[str]]:
+    """Detect dependency cycles in the task graph.
+
+    Returns a list of cycles, where each cycle is a list of task IDs.
+    Empty list means no cycles. Dependencies referencing task IDs not
+    present in the dict are ignored (unmet, not cyclic).
+    """
+    # Standard DFS-based cycle detection with three coloring states
+    WHITE = 0  # not visited
+    GRAY = 1  # on the current DFS path
+    BLACK = 2  # fully processed
+
+    color: dict[str, int] = {tid: WHITE for tid in tasks}
+    parent: dict[str, str | None] = {}
+    cycles: list[list[str]] = []
+
+    def dfs(node: str) -> None:
+        color[node] = GRAY
+        task = tasks[node]
+        for dep in task.deps:
+            if dep not in tasks:
+                # Dependency references a task not in the dict -- skip
+                continue
+            if color[dep] == GRAY:
+                # Found a cycle -- trace back from node to dep
+                cycle = _extract_cycle(node, dep, parent)
+                cycles.append(cycle)
+            elif color[dep] == WHITE:
+                parent[dep] = node
+                dfs(dep)
+        color[node] = BLACK
+
+    for tid in tasks:
+        if color[tid] == WHITE:
+            parent[tid] = None
+            dfs(tid)
+
+    return cycles
+
+
+def _extract_cycle(current: str, back_edge_target: str, parent: dict[str, str | None]) -> list[str]:
+    """Extract the cycle path from the parent map.
+
+    Walks from `current` back through `parent` until reaching `back_edge_target`.
+    """
+    cycle = [back_edge_target]
+    node: str | None = current
+    while node != back_edge_target:
+        assert node is not None
+        cycle.append(node)
+        node = parent.get(node)
+    cycle.reverse()
+    return cycle

hyperloop/domain/model.py

@@ -0,0 +1,221 @@
+"""Domain model — value objects, entities, and pipeline primitives.
+
+All types are pure data with no I/O dependencies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal, NewType
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class TaskStatus(Enum):
+    """Lifecycle status of a task."""
+
+    NOT_STARTED = "not_started"
+    IN_PROGRESS = "in_progress"
+    NEEDS_REBASE = "needs_rebase"
+    COMPLETE = "complete"
+    FAILED = "failed"
+
+
+class Verdict(Enum):
+    """Outcome reported by a worker."""
+
+    PASS = "pass"
+    FAIL = "fail"
+    TIMEOUT = "timeout"
+    ERROR = "error"
+
+
+# ---------------------------------------------------------------------------
+# Simple types
+# ---------------------------------------------------------------------------
+
+Phase = NewType("Phase", str)
+"""Current pipeline step name — a branded string for type safety."""
+
+# ---------------------------------------------------------------------------
+# Core entities / value objects
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Task:
+    """A unit of work tracked by the orchestrator."""
+
+    id: str
+    title: str
+    spec_ref: str
+    status: TaskStatus
+    phase: Phase | None
+    deps: tuple[str, ...]
+    round: int
+    branch: str | None
+    pr: str | None
+
+
+@dataclass(frozen=True)
+class WorkerResult:
+    """Verdict reported by a finished worker."""
+
+    verdict: Verdict
+    findings: int
+    detail: str
+
+
+@dataclass(frozen=True)
+class WorkerHandle:
+    """Opaque handle to a running worker session."""
+
+    task_id: str
+    role: str
+    agent_id: str
+    session_id: str | None
+
+
+# ---------------------------------------------------------------------------
+# Pipeline primitives
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class RoleStep:
+    """Spawn an agent with a given role."""
+
+    role: str
+    on_pass: str | None
+    on_fail: str | None
+
+
+@dataclass(frozen=True)
+class GateStep:
+    """Block until an external signal is received."""
+
+    gate: str
+
+
+@dataclass(frozen=True)
+class LoopStep:
+    """Wrap steps — on fail retry from top, on pass continue."""
+
+    steps: tuple[PipelineStep, ...]
+
+
+@dataclass(frozen=True)
+class ActionStep:
+    """Terminal operation (merge-pr, mark-pr-ready, etc.)."""
+
+    action: str
+
+
+PipelineStep = RoleStep | GateStep | LoopStep | ActionStep
+"""Union of all pipeline primitive types."""
+
+
+@dataclass(frozen=True)
+class PipelinePosition:
+    """Path through a nested pipeline structure.
+
+    Each element in `path` is an index into a list of steps at that nesting level.
+    Example: path=[0, 1] means "first step in pipeline (a LoopStep), second step within
+    that loop."
+    """
+
+    path: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class Process:
+    """A named process with intake and per-task pipelines."""
+
+    name: str
+    intake: tuple[PipelineStep, ...]
+    pipeline: tuple[PipelineStep, ...]
+
+
+# ---------------------------------------------------------------------------
+# World snapshot (input to the decide function)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class WorkerState:
+    """Snapshot of a worker's current status."""
+
+    task_id: str
+    role: str
+    status: Literal["running", "done", "failed"]
+
+
+@dataclass(frozen=True)
+class World:
+    """Complete snapshot of orchestrator state — input to decide()."""
+
+    tasks: dict[str, Task]
+    workers: dict[str, WorkerState]
+    epoch: str
+
+
+# ---------------------------------------------------------------------------
+# Actions (output of the decide function)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SpawnWorker:
+    """Spawn a new worker for a task with a given role."""
+
+    task_id: str
+    role: str
+
+
+@dataclass(frozen=True)
+class ReapWorker:
+    """Collect results from a finished worker."""
+
+    task_id: str
+
+
+@dataclass(frozen=True)
+class AdvanceTask:
+    """Transition a task to a new status and/or phase."""
+
+    task_id: str
+    to_status: TaskStatus
+    to_phase: Phase | None
+
+
+@dataclass(frozen=True)
+class RunPM:
+    """Run the PM intake process."""
+
+
+@dataclass(frozen=True)
+class RunProcessImprover:
+    """Run the process improver with accumulated findings."""
+
+    findings: dict[str, int]
+
+
+@dataclass(frozen=True)
+class MergePR:
+    """Squash-merge a task's PR."""
+
+    task_id: str
+
+
+@dataclass(frozen=True)
+class Halt:
+    """Stop the orchestrator loop."""
+
+    reason: str
+
+
+Action = SpawnWorker | ReapWorker | AdvanceTask | RunPM | RunProcessImprover | MergePR | Halt
+"""Union of all action types emitted by the decide function."""