hyperloop 0.1.0__py3-none-any.whl

hyperloop/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for ``python -m hyperloop``."""
+
+from hyperloop.cli import app
+
+app()

hyperloop/adapters/git_state.py

@@ -0,0 +1,254 @@
+"""GitStateStore — reads/writes task files in a git repo.
+
+Implements the StateStore protocol by parsing YAML frontmatter task files
+and using git for persistence.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from typing import TYPE_CHECKING, cast
+
+import yaml
+
+from hyperloop.domain.model import Phase, Task, TaskStatus, World
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# Map between kebab-case YAML values and TaskStatus enum members
+_STATUS_FROM_YAML: dict[str, TaskStatus] = {
+    "not-started": TaskStatus.NOT_STARTED,
+    "in-progress": TaskStatus.IN_PROGRESS,
+    "needs-rebase": TaskStatus.NEEDS_REBASE,
+    "complete": TaskStatus.COMPLETE,
+    "failed": TaskStatus.FAILED,
+}
+
+_STATUS_TO_YAML: dict[TaskStatus, str] = {v: k for k, v in _STATUS_FROM_YAML.items()}
+
+
+def _parse_task_file(content: str) -> tuple[dict[str, object], str]:
+    """Parse a task file into (frontmatter_dict, body_text).
+
+    The file format is YAML frontmatter delimited by --- lines, followed by
+    markdown body.
+    """
+    match = re.match(r"^---\n(.*?)\n---\n(.*)", content, re.DOTALL)
+    if not match:
+        msg = "Task file missing YAML frontmatter"
+        raise ValueError(msg)
+    fm_raw = match.group(1)
+    body = match.group(2)
+    frontmatter: dict[str, object] = yaml.safe_load(fm_raw)
+    return frontmatter, body
+
+
+def _frontmatter_to_task(fm: dict[str, object]) -> Task:
+    """Convert parsed YAML frontmatter into a Task domain object."""
+    raw_status = str(fm["status"])
+    status = _STATUS_FROM_YAML[raw_status]
+
+    raw_phase = fm.get("phase")
+    phase = Phase(str(raw_phase)) if raw_phase is not None else None
+
+    raw_deps = fm.get("deps")
+    dep_list = cast("list[object]", raw_deps) if isinstance(raw_deps, list) else []
+    deps = tuple(str(d) for d in dep_list)
+
+    raw_branch = fm.get("branch")
+    branch = str(raw_branch) if raw_branch is not None else None
+
+    raw_pr = fm.get("pr")
+    pr = str(raw_pr) if raw_pr is not None else None
+
+    return Task(
+        id=str(fm["id"]),
+        title=str(fm["title"]),
+        spec_ref=str(fm["spec_ref"]),
+        status=status,
+        phase=phase,
+        deps=deps,
+        round=int(fm.get("round", 0)),  # type: ignore[arg-type]
+        branch=branch,
+        pr=pr,
+    )
+
+
+def _serialize_task_file(fm: dict[str, object], body: str) -> str:
+    """Serialize frontmatter dict and body back into a task file string."""
+    # Preserve a specific field order for readability
+    ordered_keys = ["id", "title", "spec_ref", "status", "phase", "deps", "round", "branch", "pr"]
+    ordered_fm: dict[str, object] = {}
+    for key in ordered_keys:
+        if key in fm:
+            ordered_fm[key] = fm[key]
+    for key in fm:
+        if key not in ordered_keys:
+            ordered_fm[key] = fm[key]
+
+    fm_text = yaml.dump(
+        ordered_fm,
+        default_flow_style=False,
+        sort_keys=False,
+        allow_unicode=True,
+    )
+    return "---\n" + fm_text + "---\n" + body
+
+
+class GitStateStore:
+    """StateStore implementation backed by task files in a git repository."""
+
+    def __init__(self, repo_path: Path, specs_dir: str = "specs") -> None:
+        self._repo = repo_path
+        self._specs_dir = specs_dir
+        self._tasks_dir = repo_path / specs_dir / "tasks"
+        self._epochs: dict[str, str] = {}
+
+    def _task_file_path(self, task_id: str) -> Path:
+        return self._tasks_dir / f"{task_id}.md"
+
+    def _read_task_file(self, task_id: str) -> tuple[dict[str, object], str]:
+        """Read and parse a task file. Raises KeyError if not found."""
+        path = self._task_file_path(task_id)
+        if not path.exists():
+            raise KeyError(task_id)
+        return _parse_task_file(path.read_text())
+
+    def _write_task_file(self, task_id: str, fm: dict[str, object], body: str) -> None:
+        """Write a task file to disk (does NOT commit)."""
+        path = self._task_file_path(task_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(_serialize_task_file(fm, body))
+
+    def _git(self, *args: str) -> str:
+        """Run a git command in the repo and return stdout."""
+        result = subprocess.run(
+            ["git", "-C", str(self._repo), *args],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return result.stdout.strip()
+
+    # -- StateStore protocol ------------------------------------------------
+
+    def get_world(self) -> World:
+        """Return a complete snapshot of all tasks, workers, and the current epoch."""
+        tasks: dict[str, Task] = {}
+        if self._tasks_dir.exists():
+            for task_file in sorted(self._tasks_dir.glob("task-*.md")):
+                fm, _body = _parse_task_file(task_file.read_text())
+                task = _frontmatter_to_task(fm)
+                tasks[task.id] = task
+
+        try:
+            epoch = self._git("rev-parse", "HEAD")
+        except subprocess.CalledProcessError:
+            epoch = ""
+
+        return World(tasks=tasks, workers={}, epoch=epoch)
+
+    def get_task(self, task_id: str) -> Task:
+        """Return a single task by ID. Raises KeyError if not found."""
+        fm, _body = self._read_task_file(task_id)
+        return _frontmatter_to_task(fm)
+
+    def transition_task(
+        self,
+        task_id: str,
+        status: TaskStatus,
+        phase: Phase | None,
+        round: int | None = None,
+    ) -> None:
+        """Update a task's status, phase, and optionally round."""
+        fm, body = self._read_task_file(task_id)
+        fm["status"] = _STATUS_TO_YAML[status]
+        fm["phase"] = str(phase) if phase is not None else None
+        if round is not None:
+            fm["round"] = round
+        self._write_task_file(task_id, fm, body)
+
+    def store_findings(self, task_id: str, detail: str) -> None:
+        """Append findings detail text to the task file's Findings section."""
+        fm, body = self._read_task_file(task_id)
+        body = _append_to_findings(body, detail)
+        self._write_task_file(task_id, fm, body)
+
+    def get_findings(self, task_id: str) -> str:
+        """Return stored findings for a task. Empty string if none."""
+        _fm, body = self._read_task_file(task_id)
+        return _extract_findings(body)
+
+    def clear_findings(self, task_id: str) -> None:
+        """Clear the findings section of a task file."""
+        fm, body = self._read_task_file(task_id)
+        body = _clear_findings(body)
+        self._write_task_file(task_id, fm, body)
+
+    def get_epoch(self, key: str) -> str:
+        """Return content fingerprint. 'head' returns git HEAD SHA. Others use in-memory dict."""
+        if key == "head":
+            try:
+                return self._git("rev-parse", "HEAD")
+            except subprocess.CalledProcessError:
+                return ""
+        return self._epochs.get(key, "")
+
+    def set_epoch(self, key: str, value: str) -> None:
+        """Record a last-run marker."""
+        self._epochs[key] = value
+
+    def read_file(self, path: str) -> str | None:
+        """Read a file from the repo. Returns None if it does not exist."""
+        file_path = self._repo / path
+        if not file_path.exists():
+            return None
+        return file_path.read_text()
+
+    def commit(self, message: str) -> None:
+        """Stage all changes and create a git commit."""
+        self._git("add", "-A")
+        self._git("commit", "-m", message)
+
+
+# ---------------------------------------------------------------------------
+# Body manipulation helpers
+# ---------------------------------------------------------------------------
+
+
+def _append_to_findings(body: str, detail: str) -> str:
+    """Append text to the ## Findings section of the markdown body."""
+    # Find the ## Findings section
+    findings_match = re.search(r"(## Findings\n)", body)
+    if not findings_match:
+        # No findings section — append one
+        return body.rstrip() + "\n\n## Findings\n" + detail
+    # Insert the detail at the end of the body (after existing findings content)
+    # The findings section runs from the header to the end of the body
+    findings_start = findings_match.end()
+    existing = body[findings_start:]
+    if existing.strip():
+        # There's existing content — append after it
+        return body.rstrip() + "\n" + detail
+    else:
+        # Empty findings section — add content
+        return body[:findings_start] + detail
+
+
+def _extract_findings(body: str) -> str:
+    """Extract content from the ## Findings section. Returns empty string if none."""
+    findings_match = re.search(r"## Findings\n", body)
+    if not findings_match:
+        return ""
+    content = body[findings_match.end() :]
+    return content.strip()
+
+
+def _clear_findings(body: str) -> str:
+    """Clear the content of the ## Findings section, preserving the header."""
+    findings_match = re.search(r"(## Findings\n)", body)
+    if not findings_match:
+        return body
+    return body[: findings_match.end()]

hyperloop/adapters/local.py

@@ -0,0 +1,273 @@
+"""LocalRuntime — spawns workers as subprocesses in git worktrees.
+
+Uses the configured command (default: ``claude --dangerously-skip-permissions``)
+to run worker agents. Each worker gets its own worktree on a dedicated branch.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from hyperloop.domain.model import Verdict, WorkerHandle, WorkerResult
+
+if TYPE_CHECKING:
+    from hyperloop.ports.runtime import WorkerPollStatus
+
+
+def _clean_git_env() -> dict[str, str]:
+    """Return a copy of the environment with interfering GIT_* variables removed.
+
+    Git sets variables like GIT_INDEX_FILE, GIT_DIR, etc. when running hooks
+    or inside worktrees. These interfere when we spawn new git operations
+    targeting a different repo. Stripping them ensures each git command
+    operates on the repo specified via -C.
+    """
+    env = os.environ.copy()
+    for key in list(env):
+        if key.startswith("GIT_"):
+            del env[key]
+    return env
+
+
+class LocalRuntime:
+    """Runtime implementation using local git worktrees and subprocesses."""
+
+    def __init__(
+        self,
+        repo_path: str,
+        worktree_base: str | None = None,
+        command: str | None = None,
+    ) -> None:
+        self._repo_path = repo_path
+        self._worktree_base = worktree_base or f"{repo_path}/worktrees/workers"
+        self._command = command or "claude --dangerously-skip-permissions"
+        self._processes: dict[str, subprocess.Popen[bytes]] = {}
+        self._worktrees: dict[str, str] = {}  # task_id -> worktree_path
+
+    def spawn(self, task_id: str, role: str, prompt: str, branch: str) -> WorkerHandle:
+        """Create a worktree, write the prompt, start the subprocess, return a handle."""
+        worktree_path = os.path.join(self._worktree_base, task_id)
+
+        # Ensure the parent directory exists
+        os.makedirs(self._worktree_base, exist_ok=True)
+
+        # Create the git worktree on a new branch
+        subprocess.run(
+            [
+                "git",
+                "-C",
+                self._repo_path,
+                "worktree",
+                "add",
+                worktree_path,
+                "-b",
+                branch,
+                "HEAD",
+            ],
+            check=True,
+            capture_output=True,
+            env=_clean_git_env(),
+        )
+
+        # Write the prompt file
+        prompt_path = os.path.join(worktree_path, "prompt.md")
+        Path(prompt_path).write_text(prompt)
+
+        # Start the subprocess with stdin from the prompt file
+        with open(prompt_path) as prompt_file:
+            proc = subprocess.Popen(
+                self._command,
+                shell=True,
+                cwd=worktree_path,
+                stdin=prompt_file,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+
+        self._processes[task_id] = proc
+        self._worktrees[task_id] = worktree_path
+
+        return WorkerHandle(
+            task_id=task_id,
+            role=role,
+            agent_id=str(proc.pid),
+            session_id=None,
+        )
+
+    def poll(self, handle: WorkerHandle) -> WorkerPollStatus:
+        """Check subprocess status. Returns 'running', 'done', or 'failed'."""
+        task_id = handle.task_id
+        proc = self._processes.get(task_id)
+
+        if proc is None:
+            # No tracked process — check if worktree exists (orphan scenario)
+            worktree_path = self._worktrees.get(task_id)
+            if worktree_path and os.path.isdir(worktree_path):
+                return "done"
+            return "failed"
+
+        returncode = proc.poll()
+
+        if returncode is None:
+            return "running"
+        if returncode == 0:
+            return "done"
+        return "failed"
+
+    def reap(self, handle: WorkerHandle) -> WorkerResult:
+        """Read the result file, clean up worktree and branch, return WorkerResult."""
+        task_id = handle.task_id
+        worktree_path = self._worktrees.get(task_id)
+
+        if worktree_path is None:
+            worktree_path = os.path.join(self._worktree_base, task_id)
+
+        result = self._read_result(worktree_path)
+        branch = self._get_worktree_branch(worktree_path)
+        self._cleanup_worktree(task_id, worktree_path, branch)
+
+        return result
+
+    def cancel(self, handle: WorkerHandle) -> None:
+        """Kill the subprocess and clean up the worktree and branch."""
+        task_id = handle.task_id
+        proc = self._processes.get(task_id)
+
+        # Kill the process if it's still running
+        if proc is not None:
+            try:
+                proc.kill()
+                proc.wait(timeout=5)
+            except (ProcessLookupError, OSError):
+                pass  # Process already dead
+
+        worktree_path = self._worktrees.get(task_id)
+        if worktree_path is None:
+            worktree_path = os.path.join(self._worktree_base, task_id)
+
+        branch = self._get_worktree_branch(worktree_path)
+        self._cleanup_worktree(task_id, worktree_path, branch)
+
+    def find_orphan(self, task_id: str, branch: str) -> WorkerHandle | None:
+        """Check if a worktree exists for the given branch. Return a handle if so."""
+        worktree_path = os.path.join(self._worktree_base, task_id)
+
+        if not os.path.isdir(worktree_path):
+            return None
+
+        # Verify this worktree is on the expected branch
+        try:
+            result = subprocess.run(
+                ["git", "-C", worktree_path, "branch", "--show-current"],
+                check=True,
+                capture_output=True,
+                text=True,
+                env=_clean_git_env(),
+            )
+            current_branch = result.stdout.strip()
+            if current_branch != branch:
+                return None
+        except subprocess.CalledProcessError:
+            return None
+
+        return WorkerHandle(
+            task_id=task_id,
+            role="unknown",
+            agent_id="orphan",
+            session_id=None,
+        )
+
+    # -- Private helpers -------------------------------------------------------
+
+    def _read_result(self, worktree_path: str) -> WorkerResult:
+        """Read and parse .worker-result.json from the worktree."""
+        result_path = os.path.join(worktree_path, ".worker-result.json")
+
+        if not os.path.exists(result_path):
+            return WorkerResult(
+                verdict=Verdict.ERROR,
+                findings=0,
+                detail="Worker result file not found",
+            )
+
+        try:
+            with open(result_path) as f:
+                data = json.load(f)
+            return WorkerResult(
+                verdict=Verdict(data["verdict"]),
+                findings=int(data["findings"]),
+                detail=str(data["detail"]),
+            )
+        except (json.JSONDecodeError, KeyError, ValueError) as exc:
+            return WorkerResult(
+                verdict=Verdict.ERROR,
+                findings=0,
+                detail=f"Failed to parse worker result: {exc}",
+            )
+
+    def _get_worktree_branch(self, worktree_path: str) -> str | None:
+        """Get the branch name for a worktree, or None if it can't be determined."""
+        if not os.path.isdir(worktree_path):
+            return None
+
+        try:
+            result = subprocess.run(
+                ["git", "-C", worktree_path, "branch", "--show-current"],
+                check=True,
+                capture_output=True,
+                text=True,
+                env=_clean_git_env(),
+            )
+            branch = result.stdout.strip()
+            return branch if branch else None
+        except subprocess.CalledProcessError:
+            return None
+
+    def _cleanup_worktree(self, task_id: str, worktree_path: str, branch: str | None) -> None:
+        """Remove the worktree directory and delete the branch."""
+        # Remove from internal tracking
+        self._processes.pop(task_id, None)
+        self._worktrees.pop(task_id, None)
+
+        if not os.path.isdir(worktree_path):
+            return
+
+        # Try git worktree remove first; fall back to shutil.rmtree
+        env = _clean_git_env()
+        try:
+            subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    self._repo_path,
+                    "worktree",
+                    "remove",
+                    "--force",
+                    worktree_path,
+                ],
+                check=True,
+                capture_output=True,
+                env=env,
+            )
+        except subprocess.CalledProcessError:
+            # Force remove the directory if git worktree remove fails
+            shutil.rmtree(worktree_path, ignore_errors=True)
+            # Prune stale worktree references
+            subprocess.run(
+                ["git", "-C", self._repo_path, "worktree", "prune"],
+                capture_output=True,
+                env=env,
+            )
+
+        # Delete the branch
+        if branch:
+            subprocess.run(
+                ["git", "-C", self._repo_path, "branch", "-D", branch],
+                capture_output=True,
+                env=env,
+            )

hyperloop/cli.py

@@ -0,0 +1,166 @@
+"""CLI entry point — typer app with rich output formatting.
+
+Provides the ``hyperloop run`` command that loads config, constructs
+the orchestrator, and runs the loop with rich status output.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from hyperloop.config import Config, ConfigError, load_config
+
+app = typer.Typer(
+    name="hyperloop",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.callback()
+def main() -> None:
+    """AI agent orchestrator for composable process pipelines."""
+
+
+def _config_table(cfg: Config) -> Table:
+    """Build a rich table showing the current configuration."""
+    table = Table(title="Configuration", show_header=True, header_style="bold cyan")
+    table.add_column("Setting", style="bold")
+    table.add_column("Value")
+
+    table.add_row("repo", str(cfg.repo) if cfg.repo else "[dim]not set (will infer from git)[/dim]")
+    table.add_row("base_branch", cfg.base_branch)
+    table.add_row("specs_dir", cfg.specs_dir)
+    table.add_row("overlay", cfg.overlay or "[dim]none[/dim]")
+    table.add_row("runtime", cfg.runtime)
+    table.add_row("max_workers", str(cfg.max_workers))
+    table.add_row("auto_merge", str(cfg.auto_merge))
+    table.add_row("merge_strategy", cfg.merge_strategy)
+    table.add_row("delete_branch", str(cfg.delete_branch))
+    table.add_row("poll_interval", f"{cfg.poll_interval}s")
+    table.add_row("max_rounds", str(cfg.max_rounds))
+    table.add_row("max_rebase_attempts", str(cfg.max_rebase_attempts))
+
+    return table
+
+
+@app.command()
+def run(
+    repo: str | None = typer.Option(
+        None,
+        help="GitHub repo (owner/repo). Inferred from git remote if not set.",
+    ),
+    branch: str | None = typer.Option(
+        None,
+        help="Base branch. Default: from config or 'main'.",
+    ),
+    config_file: Path | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Config file path. Default: .hyperloop.yaml",
+    ),
+    max_workers: int | None = typer.Option(
+        None,
+        help="Max parallel workers.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show what would be done without executing.",
+    ),
+) -> None:
+    """Run the orchestrator loop."""
+    # 1. Load config (file + CLI overrides)
+    config_path = config_file or Path(".hyperloop.yaml")
+    try:
+        cfg = load_config(
+            config_path,
+            repo=repo,
+            base_branch=branch,
+            max_workers=max_workers,
+        )
+    except ConfigError as exc:
+        console.print(f"[bold red]Config error:[/bold red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    # 2. Show config
+    console.print()
+    console.print(
+        Panel(
+            "[bold]hyperloop[/bold]",
+            subtitle="AI agent orchestrator",
+            style="blue",
+        )
+    )
+    console.print(_config_table(cfg))
+    console.print()
+
+    # 3. Dry run — show config and exit
+    if dry_run:
+        console.print("[bold yellow]Dry run[/bold yellow] -- exiting without executing.")
+        return
+
+    # 4. Validate repo is set (required for actual run)
+    if cfg.repo is None:
+        console.print(
+            "[bold red]Error:[/bold red] No repo specified. "
+            "Use --repo owner/repo or set target.repo in .hyperloop.yaml"
+        )
+        raise typer.Exit(code=1)
+
+    # 5. Construct runtime and state store, run loop
+    from hyperloop.adapters.git_state import GitStateStore
+    from hyperloop.adapters.local import LocalRuntime
+    from hyperloop.domain.model import ActionStep, LoopStep, Process, RoleStep
+    from hyperloop.loop import Orchestrator
+
+    # Default process: loop(implementer, verifier) -> merge-pr
+    default_process = Process(
+        name="default",
+        intake=(),
+        pipeline=(
+            LoopStep(
+                steps=(
+                    RoleStep(role="implementer", on_pass=None, on_fail=None),
+                    RoleStep(role="verifier", on_pass=None, on_fail=None),
+                )
+            ),
+            ActionStep(action="merge-pr"),
+        ),
+    )
+
+    repo_path = Path.cwd()
+    state = GitStateStore(repo_path, specs_dir=cfg.specs_dir)
+    runtime = LocalRuntime(repo_path=str(repo_path))
+
+    orchestrator = Orchestrator(
+        state=state,
+        runtime=runtime,
+        process=default_process,
+        max_workers=cfg.max_workers,
+        max_rounds=cfg.max_rounds,
+    )
+
+    # 6. Recover and run
+    with console.status("[bold green]Recovering state...[/bold green]"):
+        orchestrator.recover()
+
+    console.print("[bold green]Starting orchestrator loop[/bold green]")
+    console.print()
+
+    reason = orchestrator.run_loop()
+
+    # 7. Final summary
+    console.print()
+    if "complete" in reason.lower():
+        console.print(Panel(f"[bold green]{reason}[/bold green]", title="Done"))
+    else:
+        console.print(Panel(f"[bold red]{reason}[/bold red]", title="Halted"))
+        sys.exit(1)