hyperloop 0.2.0__tar.gz → 0.4.0__tar.gz

{hyperloop-0.2.0 → hyperloop-0.4.0}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 <!-- version list -->
 
+## v0.4.0 (2026-04-15)
+
+
+## v0.3.0 (2026-04-15)
+
+
 ## v0.2.0 (2026-04-15)
 
 

{hyperloop-0.2.0 → hyperloop-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperloop
-Version: 0.2.0
+Version: 0.4.0
 Summary: Orchestrator that walks tasks through composable process pipelines using AI agents
 Requires-Python: >=3.12
 Requires-Dist: pyyaml>=6.0.3

{hyperloop-0.2.0 → hyperloop-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hyperloop"
-version = "0.2.0"
+version = "0.4.0"
 description = "Orchestrator that walks tasks through composable process pipelines using AI agents"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -58,6 +58,9 @@ reportMissingTypeStubs = false
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+markers = [
+    "slow: end-to-end integration tests (real git repos, subprocesses)",
+]
 
 [tool.semantic_release]
 commit_parser = "conventional"

{hyperloop-0.2.0 → hyperloop-0.4.0}/src/hyperloop/adapters/git_state.py

@@ -200,6 +200,12 @@ class GitStateStore:
         """Record a last-run marker."""
         self._epochs[key] = value
 
+    def list_files(self, pattern: str) -> list[str]:
+        """List file paths matching a glob pattern relative to the repo root."""
+        return sorted(
+            str(p.relative_to(self._repo)) for p in self._repo.glob(pattern) if p.is_file()
+        )
+
     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

{hyperloop-0.2.0 → hyperloop-0.4.0}/src/hyperloop/adapters/local.py

@@ -56,8 +56,10 @@ class LocalRuntime:
         # Ensure the parent directory exists
         os.makedirs(self._worktree_base, exist_ok=True)
 
-        # Create the git worktree on a new branch
-        subprocess.run(
+        # Create the git worktree — reuse existing branch if it survived
+        # a previous pipeline step, otherwise create a new one.
+        env = _clean_git_env()
+        result = subprocess.run(
             [
                 "git",
                 "-C",
@@ -65,14 +67,29 @@ class LocalRuntime:
                 "worktree",
                 "add",
                 worktree_path,
-                "-b",
                 branch,
-                "HEAD",
             ],
-            check=True,
             capture_output=True,
-            env=_clean_git_env(),
+            env=env,
         )
+        if result.returncode != 0:
+            # Branch doesn't exist yet — create it
+            subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    self._repo_path,
+                    "worktree",
+                    "add",
+                    worktree_path,
+                    "-b",
+                    branch,
+                    "HEAD",
+                ],
+                check=True,
+                capture_output=True,
+                env=env,
+            )
 
         # Write the prompt file
         prompt_path = os.path.join(worktree_path, "prompt.md")
@@ -120,7 +137,10 @@ class LocalRuntime:
         return "failed"
 
     def reap(self, handle: WorkerHandle) -> WorkerResult:
-        """Read the result file, clean up worktree and branch, return WorkerResult."""
+        """Read the result file, clean up worktree, return WorkerResult.
+
+        Preserves the branch so later pipeline steps (e.g. merge-pr) can use it.
+        """
         task_id = handle.task_id
         worktree_path = self._worktrees.get(task_id)
 
@@ -152,6 +172,7 @@ class LocalRuntime:
 
         branch = self._get_worktree_branch(worktree_path)
         self._cleanup_worktree(task_id, worktree_path, branch)
+        self._delete_branch(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."""
@@ -229,7 +250,7 @@ class LocalRuntime:
             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 the worktree directory. Preserves the branch for later pipeline steps."""
         # Remove from internal tracking
         self._processes.pop(task_id, None)
         self._worktrees.pop(task_id, None)
@@ -264,10 +285,11 @@ class LocalRuntime:
                 env=env,
             )
 
-        # Delete the branch
+    def _delete_branch(self, branch: str | None) -> None:
+        """Delete a branch from the repo (best-effort, used by cancel)."""
         if branch:
             subprocess.run(
                 ["git", "-C", self._repo_path, "branch", "-D", branch],
                 capture_output=True,
-                env=env,
+                env=_clean_git_env(),
             )

hyperloop-0.4.0/src/hyperloop/adapters/serial.py

@@ -0,0 +1,50 @@
+"""SubprocessSerialRunner — runs serial agents via CLI subprocess on trunk.
+
+Used for PM intake and process-improver. Blocks until the agent completes.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+
+logger = logging.getLogger(__name__)
+
+
+class SubprocessSerialRunner:
+    """Run a serial agent as a subprocess in the repo directory."""
+
+    _DEFAULT_CMD = "claude --dangerously-skip-permissions"
+
+    def __init__(self, repo_path: str, command: str = _DEFAULT_CMD) -> None:
+        self._repo_path = repo_path
+        self._command = command
+
+    def run(self, role: str, prompt: str) -> bool:
+        """Execute a serial agent with the given prompt. Blocks until complete."""
+        logger.info("Running serial agent: %s", role)
+
+        try:
+            result = subprocess.run(
+                self._command.split(),
+                input=prompt,
+                capture_output=True,
+                text=True,
+                cwd=self._repo_path,
+                timeout=600,
+            )
+            if result.returncode != 0:
+                logger.warning(
+                    "Serial agent %s failed (exit %d): %s",
+                    role,
+                    result.returncode,
+                    result.stderr[:500],
+                )
+                return False
+
+            logger.info("Serial agent %s completed successfully", role)
+            return True
+
+        except subprocess.TimeoutExpired:
+            logger.warning("Serial agent %s timed out after 600s", role)
+            return False

{hyperloop-0.2.0 → hyperloop-0.4.0}/src/hyperloop/cli.py

@@ -7,6 +7,7 @@ the orchestrator, and runs the loop with rich status output.
 from __future__ import annotations
 
 import sys
+from importlib.metadata import version as pkg_version
 from pathlib import Path
 
 import typer
@@ -23,8 +24,23 @@ app = typer.Typer(
 console = Console()
 
 
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"hyperloop {pkg_version('hyperloop')}")
+        raise typer.Exit()
+
+
 @app.callback()
-def main() -> None:
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
     """AI agent orchestrator for composable process pipelines."""
 
 
@@ -50,6 +66,37 @@ def _config_table(cfg: Config) -> Table:
     return table
 
 
+def _make_composer(state: object) -> object | None:
+    """Construct a PromptComposer using the base/ directory.
+
+    Tries two locations:
+    1. Development: relative to this file (src/hyperloop/../../base)
+    2. Installed package: via importlib.resources
+
+    Returns None if base/ directory cannot be found.
+    """
+    from hyperloop.compose import PromptComposer
+
+    # Development path: relative to this source file
+    dev_base = Path(__file__).resolve().parent.parent.parent / "base"
+    if dev_base.is_dir():
+        return PromptComposer(base_dir=dev_base, state=state)  # type: ignore[arg-type]
+
+    # Installed package: try importlib.resources
+    try:
+        import importlib.resources as pkg_resources
+
+        ref = pkg_resources.files("hyperloop").joinpath("../../base")
+        base_path = Path(str(ref))
+        if base_path.is_dir():
+            return PromptComposer(base_dir=base_path, state=state)  # type: ignore[arg-type]
+    except (ImportError, TypeError, FileNotFoundError):
+        pass
+
+    console.print("[dim]Warning: base/ directory not found — prompts will be empty.[/dim]")
+    return None
+
+
 @app.command()
 def run(
     path: Path = typer.Option(
@@ -127,6 +174,7 @@ def run(
     # 5. Construct runtime and state store, run loop
     from hyperloop.adapters.git_state import GitStateStore
     from hyperloop.adapters.local import LocalRuntime
+    from hyperloop.adapters.serial import SubprocessSerialRunner
     from hyperloop.domain.model import ActionStep, LoopStep, Process, RoleStep
     from hyperloop.loop import Orchestrator
 
@@ -147,6 +195,36 @@ def run(
 
     state = GitStateStore(repo_path, specs_dir=cfg.specs_dir)
     runtime = LocalRuntime(repo_path=str(repo_path))
+    serial_runner = SubprocessSerialRunner(repo_path=str(repo_path))
+
+    # Resolve base/ directory for agent prompt definitions
+    composer = _make_composer(state)
+
+    def _on_cycle(summary: dict[str, object]) -> None:
+        """Print a rich status line after each orchestrator cycle."""
+        cycle = summary.get("cycle", "?")
+        tasks = summary.get("tasks", {})
+        workers = summary.get("workers", 0)
+        halt = summary.get("halt_reason")
+
+        if isinstance(tasks, dict):
+            total = tasks.get("total", 0)
+            done = tasks.get("complete", 0)
+            in_prog = tasks.get("in_progress", 0)
+            failed = tasks.get("failed", 0)
+            task_str = (
+                f"[dim]{total} total[/dim]  "
+                f"[green]{done} done[/green]  "
+                f"[yellow]{in_prog} active[/yellow]  "
+                f"[red]{failed} failed[/red]"
+            )
+        else:
+            task_str = "[dim]unknown[/dim]"
+
+        status = f"[bold]cycle {cycle}[/bold]  tasks: {task_str}  workers: {workers}"
+        if halt:
+            status += f"  [bold]{halt}[/bold]"
+        console.print(status)
 
     orchestrator = Orchestrator(
         state=state,
@@ -154,6 +232,10 @@ def run(
         process=default_process,
         max_workers=cfg.max_workers,
         max_rounds=cfg.max_rounds,
+        composer=composer,
+        serial_runner=serial_runner,
+        poll_interval=cfg.poll_interval,
+        on_cycle=_on_cycle,
     )
 
     # 6. Recover and run

{hyperloop-0.2.0 → hyperloop-0.4.0}/src/hyperloop/loop.py

@@ -1,13 +1,14 @@
 """Orchestrator loop — wires decide, pipeline, state store, and runtime.
 
 Runs the serial section from the spec: reap finished workers, check for halt,
-run stubs for process-improver/intake, poll gates, merge PRs, decide what to
-spawn, update state, spawn workers, and check convergence.
+run process-improver/intake, poll gates, merge PRs, decide what to spawn,
+update state, spawn workers, and check convergence.
 """
 
 from __future__ import annotations
 
 import logging
+import time
 from typing import TYPE_CHECKING
 
 from hyperloop.domain.decide import decide
@@ -37,10 +38,13 @@ from hyperloop.domain.pipeline import (
 )
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from hyperloop.compose import PromptComposer
     from hyperloop.domain.model import PipelineStep, Process, Task, WorkerResult
     from hyperloop.ports.pr import PRPort
     from hyperloop.ports.runtime import Runtime
+    from hyperloop.ports.serial import SerialRunner
     from hyperloop.ports.state import StateStore
 
 logger = logging.getLogger(__name__)
@@ -53,8 +57,8 @@ class Orchestrator:
     Each cycle follows the spec's serial section order:
       1. Reap finished workers
       2. Halt if any task failed
-      3. Process-improver (stub)
-      4. Intake (stub)
+      3. Process-improver (serial on trunk)
+      4. Intake (serial on trunk)
       5. Poll gates
       6. Merge ready PRs
       7. Decide what to spawn (via decide())
@@ -71,6 +75,10 @@ class Orchestrator:
         max_rounds: int = 50,
         pr_manager: PRPort | None = None,
         composer: PromptComposer | None = None,
+        repo_path: str | None = None,
+        poll_interval: float = 30.0,
+        on_cycle: Callable[[dict[str, object]], None] | None = None,
+        serial_runner: SerialRunner | None = None,
     ) -> None:
         self._state = state
         self._runtime = runtime
@@ -79,16 +87,22 @@ class Orchestrator:
         self._max_rounds = max_rounds
         self._pr_manager = pr_manager
         self._composer = composer
+        self._repo_path = repo_path
+        self._poll_interval = poll_interval
+        self._on_cycle = on_cycle
+        self._serial_runner = serial_runner
 
         # Active worker tracking: task_id -> (handle, pipeline_position)
         self._workers: dict[str, tuple[WorkerHandle, PipelinePosition]] = {}
 
     def run_loop(self, max_cycles: int = 1000) -> str:
         """Run the orchestrator loop until halt or max_cycles. Returns halt reason."""
-        for _ in range(max_cycles):
-            reason = self.run_cycle()
+        for cycle_num in range(max_cycles):
+            reason = self.run_cycle(cycle_num=cycle_num + 1)
             if reason is not None:
                 return reason
+            if self._poll_interval > 0:
+                time.sleep(self._poll_interval)
         return "max_cycles exhausted"
 
     def recover(self) -> None:
@@ -121,7 +135,7 @@ class Orchestrator:
                 task.phase,
             )
 
-    def run_cycle(self) -> str | None:
+    def run_cycle(self, cycle_num: int = 0) -> str | None:
         """Run one serial section cycle.
 
         Returns a halt reason string if the loop should stop, or None to continue.
@@ -131,6 +145,16 @@ class Orchestrator:
         # Cache world snapshot once per cycle — augmented with worker state
         world = self._build_world()
 
+        # ---- 0. Early exit on zero tasks -------------------------------------
+        if not world.tasks and not self._workers:
+            # Try intake first — it may create tasks from new specs
+            self._run_intake()
+            world = self._build_world()
+            if not world.tasks and not self._workers:
+                reason = "no tasks found — nothing to do"
+                self._notify_cycle(cycle_num, world, reason=reason)
+                return reason
+
         # ---- 1. Reap finished workers ----------------------------------------
         reaped_results: dict[str, WorkerResult] = {}
         had_failures_this_cycle = False
@@ -208,12 +232,12 @@ class Orchestrator:
             self._state.commit("orchestrator: halt")
             return halt_reason
 
-        # ---- 3. Process-improver (stub) --------------------------------------
+        # ---- 3. Process-improver ------------------------------------------------
         if had_failures_this_cycle:
-            logger.info("process-improver: stub — would run on trunk with this cycle's findings")
+            self._run_process_improver(reaped_results)
 
-        # ---- 4. Intake (stub) ------------------------------------------------
-        logger.debug("intake: stub — would run if configured and new specs exist")
+        # ---- 4. Intake ----------------------------------------------------------
+        self._run_intake()
 
         # ---- 5. Poll gates ---------------------------------------------------
         self._poll_gates(executor, to_spawn)
@@ -275,14 +299,18 @@ class Orchestrator:
         # ---- Check convergence -----------------------------------------------
         all_tasks = self._state.get_world().tasks
         if not all_tasks:
+            self._notify_cycle(cycle_num, world)
             return None
 
         all_complete = all(t.status == TaskStatus.COMPLETE for t in all_tasks.values())
         no_workers = len(self._workers) == 0
 
         if all_complete and no_workers:
-            return "all tasks complete"
+            reason = "all tasks complete"
+            self._notify_cycle(cycle_num, world, reason=reason)
+            return reason
 
+        self._notify_cycle(cycle_num, world)
         return None
 
     # -----------------------------------------------------------------------
@@ -382,9 +410,13 @@ class Orchestrator:
         """Merge worker branch into base branch locally (no PR)."""
         import subprocess
 
+        git_cmd = ["git"]
+        if self._repo_path is not None:
+            git_cmd = ["git", "-C", self._repo_path]
+
         try:
             subprocess.run(
-                ["git", "merge", branch, "--no-edit", "-m", f"merge: {task_id}"],
+                [*git_cmd, "merge", branch, "--no-edit", "-m", f"merge: {task_id}"],
                 check=True,
                 capture_output=True,
             )
@@ -393,9 +425,87 @@ class Orchestrator:
             logger.info("Local merge of %s into base branch", task_id)
         except subprocess.CalledProcessError:
             logger.warning("Local merge conflict for task %s, marking NEEDS_REBASE", task_id)
-            subprocess.run(["git", "merge", "--abort"], capture_output=True, check=False)
+            subprocess.run([*git_cmd, "merge", "--abort"], capture_output=True, check=False)
             self._state.transition_task(task_id, TaskStatus.NEEDS_REBASE, phase=Phase("merge-pr"))
 
+    # -----------------------------------------------------------------------
+    # Serial agents (PM intake + process-improver)
+    # -----------------------------------------------------------------------
+
+    def _unprocessed_specs(self) -> list[str]:
+        """Return spec file paths that have no corresponding task.
+
+        Scans specs/*.md (excluding subdirectories like tasks/, reviews/,
+        prompts/) and checks whether any existing task references each spec
+        via its spec_ref field.
+        """
+        all_specs = self._state.list_files("specs/*.md")
+        world = self._state.get_world()
+        covered_refs = {task.spec_ref for task in world.tasks.values()}
+        return [s for s in all_specs if s not in covered_refs]
+
+    def _collect_cycle_findings(self, reaped_results: dict[str, WorkerResult]) -> str:
+        """Collect findings from all failed results this cycle into a single string."""
+        sections: list[str] = []
+        for task_id, result in reaped_results.items():
+            if result.verdict in (Verdict.FAIL, Verdict.ERROR, Verdict.TIMEOUT):
+                sections.append(f"### {task_id}\n{result.detail}")
+        return "\n\n".join(sections)
+
+    def _run_intake(self) -> None:
+        """Run PM intake if there are unprocessed specs and a serial runner + composer."""
+        if self._serial_runner is None or self._composer is None:
+            logger.debug("intake: no serial_runner or composer — skipping")
+            return
+
+        unprocessed = self._unprocessed_specs()
+        if not unprocessed:
+            logger.debug("intake: no unprocessed specs — skipping")
+            return
+
+        logger.info("intake: %d unprocessed spec(s), running PM", len(unprocessed))
+
+        spec_list = "\n".join(f"- {s}" for s in unprocessed)
+        prompt = self._composer.compose(
+            role="pm",
+            task_id="intake",
+            spec_ref="specs/",
+            findings="",
+        )
+        prompt += f"\n## Specs to Process\n{spec_list}\n"
+
+        success = self._serial_runner.run("pm", prompt)
+        if success:
+            logger.info("intake: PM completed successfully")
+        else:
+            logger.warning("intake: PM agent failed")
+
+    def _run_process_improver(self, reaped_results: dict[str, WorkerResult]) -> None:
+        """Run process-improver with findings from failed results this cycle."""
+        if self._serial_runner is None or self._composer is None:
+            logger.info("process-improver: no serial_runner or composer — skipping")
+            return
+
+        findings_text = self._collect_cycle_findings(reaped_results)
+        if not findings_text:
+            logger.debug("process-improver: no failure findings this cycle — skipping")
+            return
+
+        logger.info("process-improver: running with this cycle's findings")
+
+        prompt = self._composer.compose(
+            role="process-improver",
+            task_id="process-improvement",
+            spec_ref="specs/prompts",
+            findings=findings_text,
+        )
+
+        success = self._serial_runner.run("process-improver", prompt)
+        if success:
+            logger.info("process-improver: completed successfully")
+        else:
+            logger.warning("process-improver: agent failed")
+
     # -----------------------------------------------------------------------
     # World building
     # -----------------------------------------------------------------------
@@ -417,6 +527,37 @@ class Orchestrator:
             epoch=base_world.epoch,
         )
 
+    # -----------------------------------------------------------------------
+    # Cycle notification
+    # -----------------------------------------------------------------------
+
+    def _notify_cycle(
+        self,
+        cycle_num: int,
+        world: World,
+        reason: str | None = None,
+    ) -> None:
+        """Invoke the on_cycle callback with a summary of this cycle."""
+        if self._on_cycle is None:
+            return
+
+        tasks = world.tasks
+        summary: dict[str, object] = {
+            "cycle": cycle_num,
+            "tasks": {
+                "total": len(tasks),
+                "not_started": sum(1 for t in tasks.values() if t.status == TaskStatus.NOT_STARTED),
+                "in_progress": sum(1 for t in tasks.values() if t.status == TaskStatus.IN_PROGRESS),
+                "complete": sum(1 for t in tasks.values() if t.status == TaskStatus.COMPLETE),
+                "failed": sum(1 for t in tasks.values() if t.status == TaskStatus.FAILED),
+            },
+            "workers": len(self._workers),
+        }
+        if reason is not None:
+            summary["halt_reason"] = reason
+
+        self._on_cycle(summary)
+
     # -----------------------------------------------------------------------
     # Prompt composition
     # -----------------------------------------------------------------------

hyperloop-0.4.0/src/hyperloop/ports/serial.py

@@ -0,0 +1,24 @@
+"""SerialRunner port — interface for running serial agents on trunk.
+
+PM and process-improver run serially on trunk during the orchestrator's
+serial section.  They are not pipeline workers — they block the loop
+until they complete.
+
+Implementations: SubprocessSerialRunner (CLI subprocess),
+                 FakeSerialRunner (in-memory for tests).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class SerialRunner(Protocol):
+    """Run an agent serially on trunk. Blocks until complete."""
+
+    def run(self, role: str, prompt: str) -> bool:
+        """Execute a serial agent with the given prompt.
+
+        Returns True on success, False on failure.
+        """
+        ...

{hyperloop-0.2.0 → hyperloop-0.4.0}/src/hyperloop/ports/state.py

@@ -52,6 +52,10 @@ class StateStore(Protocol):
         """Record a last-run marker."""
         ...
 
+    def list_files(self, pattern: str) -> list[str]:
+        """List file paths matching a glob pattern relative to the repo root."""
+        ...
+
     def read_file(self, path: str) -> str | None:
         """Read a file from trunk. Returns None if the file does not exist."""
         ...

hyperloop-0.4.0/tests/fakes/serial.py

@@ -0,0 +1,47 @@
+"""FakeSerialRunner — in-memory implementation of the SerialRunner port.
+
+Records invocations for test assertions. Optionally runs a callback
+to simulate side effects (e.g. creating task files in the state store).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@dataclass(frozen=True)
+class SerialRunRecord:
+    """Record of a serial agent invocation."""
+
+    role: str
+    prompt: str
+
+
+class FakeSerialRunner:
+    """In-memory implementation of the SerialRunner port."""
+
+    def __init__(self) -> None:
+        self.runs: list[SerialRunRecord] = []
+        self._callbacks: dict[str, Callable[[str], bool]] = {}
+        self._default_success: bool = True
+
+    def set_callback(self, role: str, callback: Callable[[str], bool]) -> None:
+        """Register a callback for a role. Called with the prompt, returns success."""
+        self._callbacks[role] = callback
+
+    def set_default_success(self, success: bool) -> None:
+        """Set the default return value when no callback is registered."""
+        self._default_success = success
+
+    # -- SerialRunner protocol -------------------------------------------------
+
+    def run(self, role: str, prompt: str) -> bool:
+        """Record the invocation and optionally execute a callback."""
+        self.runs.append(SerialRunRecord(role=role, prompt=prompt))
+        if role in self._callbacks:
+            return self._callbacks[role](prompt)
+        return self._default_success