hyperloop 0.3.0__tar.gz → 0.5.0__tar.gz

hyperloop-0.5.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.5.0 (2026-04-15)
+
+### Features
+
+- Make base_ref configurable via config file and HYPERLOOP_BASE_REF env var
+  ([`8efcc0f`](https://github.com/jsell-rh/hyperloop/commit/8efcc0f4292229525e4aa8831561982ad5384220))
+
+- Replace local base/ loading with kustomize-based prompt composition
+  ([`9644afb`](https://github.com/jsell-rh/hyperloop/commit/9644afb89a96eee564f997222d86201312bcb63e))
+
+
+## v0.4.0 (2026-04-15)
+
+
+## v0.3.0 (2026-04-15)
+
+
+## v0.2.0 (2026-04-15)
+
+
+## v0.1.1 (2026-04-15)
+
+
+## v0.1.0 (2026-04-15)
+
+- Initial Release

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperloop
-Version: 0.3.0
+Version: 0.5.0
 Summary: Orchestrator that walks tasks through composable process pipelines using AI agents
 Requires-Python: >=3.12
 Requires-Dist: pyyaml>=6.0.3
@@ -21,6 +21,7 @@ Walks tasks through composable process pipelines using AI agents. You write spec
 
 - Python 3.12+
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
+- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/) (`kustomize` on PATH) — resolves agent definitions at startup
 - `git`
 - `gh` CLI (optional, for GitHub PR operations)
 
@@ -222,6 +223,7 @@ All task state is tracked in git. Every commit includes `Spec-Ref` and `Task-Ref
 # .hyperloop.yaml
 
 overlay: .hyperloop/agents/    # local path or git URL to kustomization dir
+base_ref: github.com/jsell-rh/hyperloop//base?ref=v1.0.0  # kustomize remote base (env: HYPERLOOP_BASE_REF)
 
 target:
   repo: owner/repo                 # GitHub repo (default: inferred from git remote)

{hyperloop-0.3.0 → hyperloop-0.5.0}/README.md

@@ -6,6 +6,7 @@ Walks tasks through composable process pipelines using AI agents. You write spec
 
 - Python 3.12+
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
+- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/) (`kustomize` on PATH) — resolves agent definitions at startup
 - `git`
 - `gh` CLI (optional, for GitHub PR operations)
 
@@ -207,6 +208,7 @@ All task state is tracked in git. Every commit includes `Spec-Ref` and `Task-Ref
 # .hyperloop.yaml
 
 overlay: .hyperloop/agents/    # local path or git URL to kustomization dir
+base_ref: github.com/jsell-rh/hyperloop//base?ref=v1.0.0  # kustomize remote base (env: HYPERLOOP_BASE_REF)
 
 target:
   repo: owner/repo                 # GitHub repo (default: inferred from git remote)

{hyperloop-0.3.0 → hyperloop-0.5.0}/base/implementer.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: implementer
+metadata:
+  name: implementer
 prompt: |
   You are a worker agent implementing a task.
 

hyperloop-0.5.0/base/kustomization.yaml

@@ -0,0 +1,7 @@
+resources:
+  - process.yaml
+  - implementer.yaml
+  - verifier.yaml
+  - process-improver.yaml
+  - rebase-resolver.yaml
+  - pm.yaml

{hyperloop-0.3.0 → hyperloop-0.5.0}/base/pm.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: pm
+metadata:
+  name: pm
 prompt: |
   You are a product manager creating tasks from specs.
 

{hyperloop-0.3.0 → hyperloop-0.5.0}/base/process-improver.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: process-improver
+metadata:
+  name: process-improver
 prompt: |
   You improve the development process based on review findings.
 

{hyperloop-0.3.0 → hyperloop-0.5.0}/base/process.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Process
-name: default
+metadata:
+  name: default
 
 intake:
   - role: pm

{hyperloop-0.3.0 → hyperloop-0.5.0}/base/rebase-resolver.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: rebase-resolver
+metadata:
+  name: rebase-resolver
 prompt: |
   You resolve merge conflicts on a worker branch.
 

{hyperloop-0.3.0 → hyperloop-0.5.0}/base/verifier.yaml

@@ -1,5 +1,7 @@
+apiVersion: hyperloop.io/v1
 kind: Agent
-name: verifier
+metadata:
+  name: verifier
 prompt: |
   You are a code reviewer verifying a task implementation.
 

{hyperloop-0.3.0 → hyperloop-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hyperloop"
-version = "0.3.0"
+version = "0.5.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.5.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.5.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.5.0}/src/hyperloop/cli.py

@@ -54,6 +54,7 @@ def _config_table(cfg: Config) -> Table:
     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("base_ref", cfg.base_ref)
     table.add_row("runtime", cfg.runtime)
     table.add_row("max_workers", str(cfg.max_workers))
     table.add_row("auto_merge", str(cfg.auto_merge))
@@ -66,6 +67,28 @@ def _config_table(cfg: Config) -> Table:
     return table
 
 
+def _make_composer(cfg: object, state: object) -> object:
+    """Construct a PromptComposer via kustomize build.
+
+    Runs ``kustomize build`` on the configured overlay (or the default
+    hyperloop base if no overlay is set).
+
+    Args:
+        cfg: Config object with an ``overlay`` attribute.
+        state: StateStore instance for reading process overlays at spawn time.
+
+    Returns:
+        A PromptComposer with resolved templates.
+    """
+    from hyperloop.compose import PromptComposer, check_kustomize_available
+
+    check_kustomize_available()
+
+    overlay = getattr(cfg, "overlay", None)
+    base_ref = getattr(cfg, "base_ref", "github.com/jsell-rh/hyperloop//base?ref=main")
+    return PromptComposer.from_kustomize(overlay, state, base_ref=base_ref)  # type: ignore[arg-type]
+
+
 @app.command()
 def run(
     path: Path = typer.Option(
@@ -143,6 +166,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 +187,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 agent definitions via kustomize build
+    composer = _make_composer(cfg, 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 +224,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.5.0/src/hyperloop/compose.py

@@ -0,0 +1,288 @@
+"""Prompt composition — kustomize-resolved templates + runtime context.
+
+Three layers composed at spawn time:
+1. Base + project overlay via kustomize (resolved at startup)
+2. Process overlay from specs/prompts/{role}-overlay.yaml (injected at spawn time)
+3. Task context: spec content, findings, traceability refs (spec_ref, task_id)
+
+The orchestrator runs ``kustomize build`` at startup to resolve layers 1+2 into
+AgentTemplate objects. Layer 3 (process overlay + task context) is injected at
+spawn time because it changes during the loop.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+import yaml
+
+if TYPE_CHECKING:
+    from hyperloop.ports.state import StateStore
+
+logger = logging.getLogger(__name__)
+
+HYPERLOOP_BASE_REF = "github.com/jsell-rh/hyperloop//base?ref=main"
+
+
+@dataclass(frozen=True)
+class AgentTemplate:
+    """A resolved agent definition from kustomize build."""
+
+    name: str
+    prompt: str
+    annotations: dict[str, str]
+
+
+class PromptComposer:
+    """Composes agent prompts from kustomize-resolved templates + runtime context."""
+
+    def __init__(self, templates: dict[str, AgentTemplate], state: StateStore) -> None:
+        """
+        Args:
+            templates: role name -> resolved agent definition (from kustomize build).
+            state: StateStore for reading process overlays and spec files at spawn time.
+        """
+        self._templates = templates
+        self._state = state
+
+    @classmethod
+    def from_kustomize(
+        cls,
+        overlay: str | None,
+        state: StateStore,
+        base_ref: str = HYPERLOOP_BASE_REF,
+    ) -> PromptComposer:
+        """Resolve templates via kustomize build, then construct.
+
+        Args:
+            overlay: Path or git URL to a kustomization directory. If None,
+                     a temporary kustomization referencing the hyperloop base
+                     is created and built.
+            state: StateStore for reading process overlays at spawn time.
+            base_ref: Kustomize remote resource for the base definitions.
+                      Configurable via .hyperloop.yaml or HYPERLOOP_BASE_REF env var.
+
+        Returns:
+            A PromptComposer with resolved templates.
+
+        Raises:
+            RuntimeError: If kustomize build fails.
+        """
+        raw_yaml = _kustomize_build(overlay, base_ref=base_ref)
+        templates = _parse_multi_doc(raw_yaml)
+        return cls(templates, state)
+
+    def compose(
+        self,
+        role: str,
+        task_id: str,
+        spec_ref: str,
+        findings: str,
+    ) -> str:
+        """Compose the full prompt for a worker.
+
+        Layers:
+        1. Resolved template prompt (from kustomize, includes base + project overlay)
+        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 resolved template.
+        """
+        if role not in self._templates:
+            msg = f"Unknown role '{role}': no agent template resolved for this role"
+            raise ValueError(msg)
+
+        template = self._templates[role]
+        prompt = template.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()
+
+
+def _kustomize_build(overlay: str | None, base_ref: str = HYPERLOOP_BASE_REF) -> str:
+    """Run ``kustomize build`` and return the raw YAML output.
+
+    Args:
+        overlay: Path or git URL to a kustomization directory.
+                 If None, builds from a temporary kustomization that
+                 references the hyperloop base.
+        base_ref: Kustomize remote resource for the base definitions.
+
+    Returns:
+        The multi-document YAML output from kustomize build.
+
+    Raises:
+        RuntimeError: If kustomize build exits non-zero.
+    """
+    if overlay is not None:
+        return _run_kustomize(overlay)
+
+    # No overlay — build a temp kustomization referencing the base
+    with tempfile.TemporaryDirectory() as tmp:
+        kustomization = Path(tmp) / "kustomization.yaml"
+        kustomization.write_text(f"resources:\n  - {base_ref}\n")
+        return _run_kustomize(tmp)
+
+
+def _run_kustomize(target: str) -> str:
+    """Execute ``kustomize build <target>`` and return stdout.
+
+    Raises:
+        RuntimeError: If the command fails.
+    """
+    result = subprocess.run(
+        ["kustomize", "build", target],
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    if result.returncode != 0:
+        msg = f"kustomize build failed (exit {result.returncode}): {result.stderr.strip()}"
+        raise RuntimeError(msg)
+    return result.stdout
+
+
+def _extract_name(doc: dict[str, object]) -> str:
+    """Extract the resource name from a YAML document.
+
+    Supports both kustomize-style ``metadata.name`` and legacy top-level
+    ``name`` for backward compatibility.
+    """
+    metadata = doc.get("metadata")
+    if isinstance(metadata, dict) and "name" in metadata:
+        return str(metadata["name"])
+    return str(doc.get("name", ""))
+
+
+def _parse_multi_doc(raw: str) -> dict[str, AgentTemplate]:
+    """Parse multi-document YAML output into AgentTemplate objects.
+
+    Only documents with ``kind: Agent`` are extracted. Process definitions
+    and other kinds are ignored for prompt composition purposes.
+
+    Args:
+        raw: Multi-document YAML string from kustomize build.
+
+    Returns:
+        A dict mapping agent name -> AgentTemplate.
+    """
+    templates: dict[str, AgentTemplate] = {}
+    for doc in yaml.safe_load_all(raw):
+        if not isinstance(doc, dict):
+            continue
+        if doc.get("kind") != "Agent":
+            continue
+        name = _extract_name(doc)
+        prompt = doc.get("prompt", "")
+        annotations = doc.get("annotations", {})
+        if not isinstance(annotations, dict):
+            annotations = {}
+        templates[name] = AgentTemplate(
+            name=name,
+            prompt=str(prompt),
+            annotations={str(k): str(v) for k, v in annotations.items()},
+        )
+    return templates
+
+
+def check_kustomize_available() -> None:
+    """Check that kustomize is on PATH.
+
+    Raises:
+        SystemExit: If kustomize is not found.
+    """
+    if shutil.which("kustomize") is None:
+        msg = (
+            "Error: kustomize CLI not found. "
+            "Install it: https://kubectl.docs.kubernetes.io/installation/kustomize/"
+        )
+        raise SystemExit(msg)
+
+
+def load_templates_from_dir(base_dir: str | Path) -> dict[str, AgentTemplate]:
+    """Load agent templates directly from a directory of YAML files.
+
+    This is used for testing and as a fallback when kustomize is not available.
+    It reads all ``*.yaml`` files in ``base_dir`` and extracts Agent definitions.
+
+    Args:
+        base_dir: Path to the directory containing base agent YAML files.
+
+    Returns:
+        A dict mapping agent name -> AgentTemplate.
+    """
+    templates: dict[str, AgentTemplate] = {}
+    base_path = Path(base_dir)
+    for yaml_file in base_path.glob("*.yaml"):
+        if yaml_file.name == "kustomization.yaml":
+            continue
+        with open(yaml_file) as f:
+            doc = yaml.safe_load(f)
+        if doc and doc.get("kind") == "Agent" and "prompt" in doc:
+            name = _extract_name(doc)
+            annotations = doc.get("annotations", {})
+            if not isinstance(annotations, dict):
+                annotations = {}
+            templates[name] = AgentTemplate(
+                name=name,
+                prompt=doc["prompt"],
+                annotations={str(k): str(v) for k, v in annotations.items()},
+            )
+    return templates

{hyperloop-0.3.0 → hyperloop-0.5.0}/src/hyperloop/config.py

@@ -6,11 +6,14 @@ returns a frozen Config dataclass. CLI arguments can override file values.
 
 from __future__ import annotations
 
+import os
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, cast
 
 import yaml
 
+DEFAULT_BASE_REF = "github.com/jsell-rh/hyperloop//base?ref=main"
+
 if TYPE_CHECKING:
     from pathlib import Path
 
@@ -27,6 +30,7 @@ class Config:
     base_branch: str  # default: "main"
     specs_dir: str  # default: "specs"
     overlay: str | None  # path or git URL to kustomization dir
+    base_ref: str  # kustomize remote base ref (env: HYPERLOOP_BASE_REF)
     runtime: str  # "local" (v1 only)
     max_workers: int  # default: 6
     auto_merge: bool  # default: True
@@ -44,6 +48,7 @@ def _defaults() -> dict[str, object]:
         "base_branch": "main",
         "specs_dir": "specs",
         "overlay": None,
+        "base_ref": os.environ.get("HYPERLOOP_BASE_REF", DEFAULT_BASE_REF),
         "runtime": "local",
         "max_workers": 6,
         "auto_merge": True,
@@ -63,7 +68,7 @@ def _flatten_yaml(raw: dict[str, object]) -> dict[str, object]:
     flat: dict[str, object] = {}
 
     # Top-level scalars
-    for key in ("overlay", "poll_interval", "max_rounds", "max_rebase_attempts"):
+    for key in ("overlay", "base_ref", "poll_interval", "max_rounds", "max_rebase_attempts"):
         if key in raw:
             flat[key] = raw[key]
 
@@ -150,6 +155,7 @@ def load_config(
         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]
+        base_ref=str(values["base_ref"]),
         runtime=str(values["runtime"]),
         max_workers=int(values["max_workers"]),  # type: ignore[arg-type]
         auto_merge=bool(values["auto_merge"]),