hyperloop 0.3.0__tar.gz → 0.4.0__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperloop
-Version: 0.3.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.3.0 → hyperloop-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hyperloop"
-version = "0.3.0"
+version = "0.4.0"
 description = "Orchestrator that walks tasks through composable process pipelines using AI agents"
 readme = "README.md"
 requires-python = ">=3.12"

{hyperloop-0.3.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.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.3.0 → hyperloop-0.4.0}/src/hyperloop/cli.py

@@ -66,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(
@@ -143,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
 
@@ -163,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,
@@ -170,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.3.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())
@@ -72,6 +76,9 @@ class Orchestrator:
         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
@@ -81,16 +88,21 @@ class Orchestrator:
         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:
@@ -123,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.
@@ -133,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
@@ -210,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)
@@ -277,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
 
     # -----------------------------------------------------------------------
@@ -402,6 +428,84 @@ class Orchestrator:
             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
     # -----------------------------------------------------------------------
@@ -423,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.3.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

{hyperloop-0.3.0 → hyperloop-0.4.0}/tests/fakes/state.py

@@ -104,6 +104,16 @@ class InMemoryStateStore:
         """Record a last-run marker."""
         self._epochs[key] = value
 
+    def list_files(self, pattern: str) -> list[str]:
+        """List file paths matching a glob pattern against in-memory files.
+
+        Uses PurePosixPath.match to respect directory boundaries (``*`` does
+        not cross ``/``), consistent with pathlib.Path.glob behaviour.
+        """
+        from pathlib import PurePosixPath
+
+        return sorted(p for p in self._files if PurePosixPath(p).match(pattern))
+
     def read_file(self, path: str) -> str | None:
         """Read a file from the in-memory filesystem. Returns None if not found."""
         return self._files.get(path)

{hyperloop-0.3.0 → hyperloop-0.4.0}/tests/test_e2e.py

@@ -255,6 +255,7 @@ class TestSingleTaskCompletesE2E:
             process=E2E_PIPELINE,
             max_workers=2,
             max_rounds=10,
+            poll_interval=0,
         )
 
         reason = orch.run_loop(max_cycles=MAX_CYCLES)
@@ -322,6 +323,7 @@ fi
             process=E2E_PIPELINE,
             max_workers=2,
             max_rounds=10,
+            poll_interval=0,
         )
 
         reason = orch.run_loop(max_cycles=MAX_CYCLES)
@@ -363,6 +365,7 @@ class TestTwoTasksRunInParallelE2E:
             process=E2E_PIPELINE,
             max_workers=4,
             max_rounds=10,
+            poll_interval=0,
         )
 
         reason = orch.run_loop(max_cycles=MAX_CYCLES)
@@ -411,6 +414,7 @@ class TestLocalMergeLandsCodeOnBaseBranch:
             max_workers=2,
             max_rounds=10,
             repo_path=str(repo),
+            poll_interval=0,
         )
 
         reason = orch.run_loop(max_cycles=MAX_CYCLES)
@@ -485,6 +489,7 @@ class TestPRFlowWithFakePRManager:
             max_workers=2,
             max_rounds=10,
             pr_manager=pr_manager,
+            poll_interval=0,
         )
 
         reason = orch.run_loop(max_cycles=MAX_CYCLES)
@@ -560,6 +565,7 @@ class TestGateBlocksUntilLgtm:
             max_workers=2,
             max_rounds=10,
             pr_manager=pr_manager,
+            poll_interval=0,
         )
 
         # Run enough cycles for implementer + verifier to complete, reaching the gate