avp-cli 0.1.0__py3-none-any.whl

avp_cli/agent_install.py

@@ -0,0 +1,331 @@
+"""Install agents into the library at `~/.avp/agents/<name>/`.
+
+Two sources, same result (a self-contained install + a generated manifest the
+CLI drives):
+
+- **Release** (`install_release`): download the prebuilt artifacts from a GitHub
+  release over HTTPS (no `gh`, no auth for a public repo). Binary agents (goose)
+  get an extracted executable; Python agents (claude-code) get a managed `venv/`
+  built from the release's wheels. This is the normal path.
+- **Local** (`install_local_binary` / `install_local_python`): point the CLI at a
+  locally built binary or wheel set, no release needed. This is the contributor
+  loop for testing your own agent or a new version before cutting a release
+  (`make build-agents` produces the artifacts; see avp-cli/README.md).
+
+Each install writes `avp-conformance.json` (command → the installed artifact,
+`cwd: "."` → the install dir) and `installed.json` (provenance). `agents.py`
+prefers these over the in-repo dev fallback.
+
+Release installs fetch over plain HTTPS (the GitHub REST API + asset URLs via
+stdlib urllib): a public repo needs no `gh` and no auth; a `GH_TOKEN` /
+`GITHUB_TOKEN` in the environment is used only for private repos or API rate
+limits. Python agents additionally need `uv` (for the venv). The unpublished
+in-repo wheels (e.g. `avp`) ship on the release and are installed by file path, so
+PyPI's unrelated `avp` package is never pulled; third-party deps (claude-agent-sdk)
+still come from PyPI.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from avp_cli import paths
+from avp_cli.agents import AGENT_SOURCES, AgentSource
+
+# Override for forks / testing; defaults to the canonical repo.
+RELEASE_REPO = os.environ.get("AVP_AGENT_REPO", "portofcontext/agent-voyager-project")
+
+
+class InstallError(Exception):
+    """An agent could not be installed (bad artifact, missing tool, no release)."""
+
+
+@dataclass(frozen=True)
+class InstallResult:
+    name: str
+    version: str
+    kind: str  # "binary" | "python"
+    source: str  # "local" | "release"
+    install_dir: Path
+    command: list[str]
+
+
+def current_target() -> str:
+    """The Rust target triple for selecting a binary release asset (mac/linux)."""
+    machine = platform.machine().lower()
+    arch = {"x86_64": "x86_64", "amd64": "x86_64", "arm64": "aarch64", "aarch64": "aarch64"}.get(
+        machine
+    )
+    if arch is None:
+        raise InstallError(f"unsupported architecture {platform.machine()!r}")
+    system = platform.system()
+    if system == "Darwin":
+        return f"{arch}-apple-darwin"
+    if system == "Linux":
+        return f"{arch}-unknown-linux-gnu"
+    raise InstallError(f"unsupported platform {system!r} (prebuilt agents are macOS/Linux only)")
+
+
+def install(
+    name: str,
+    *,
+    version: str | None = None,
+    binary: str | Path | None = None,
+    wheels: list[str | Path] | None = None,
+    force: bool = False,
+) -> InstallResult:
+    """Install a known agent. With `binary`/`wheels`, install locally; else from a release."""
+    source = AGENT_SOURCES.get(name)
+    if source is None:
+        raise InstallError(f"unknown agent {name!r}; known: {', '.join(AGENT_SOURCES)}")
+    if binary is not None:
+        if source.kind != "binary":
+            raise InstallError(
+                f"{name} is a {source.kind} agent; --binary applies to binary agents"
+            )
+        return install_local_binary(source, binary, force=force)
+    if wheels:
+        if source.kind != "python":
+            raise InstallError(f"{name} is a {source.kind} agent; --wheel applies to python agents")
+        return install_local_python(source, wheels, force=force)
+    return install_release(source, version=version, force=force)
+
+
+def install_release(
+    source: AgentSource, *, version: str | None = None, force: bool = False
+) -> InstallResult:
+    """Download a release's artifacts over HTTPS and install them.
+
+    No `gh` and no auth for a public repo: assets are fetched from the GitHub
+    REST API + their download URLs via stdlib urllib. A `GH_TOKEN` / `GITHUB_TOKEN`
+    in the environment is used if present (private repos, API rate limits).
+    """
+    tag, resolved, assets = _resolve_release(source, version)
+    by_name = {a["name"]: a["browser_download_url"] for a in assets}
+    with tempfile.TemporaryDirectory() as tmp:
+        tmpdir = Path(tmp)
+        if source.kind == "binary":
+            target = current_target()
+            asset = f"{source.binary_name}-{target}.tar.gz"
+            url = by_name.get(asset)
+            if url is None:
+                have = ", ".join(by_name) or "none"
+                raise InstallError(f"release {tag} has no asset {asset!r} (assets: {have})")
+            archive = tmpdir / asset
+            _download(url, archive)
+            binary = _extract_binary(archive, source.binary_name or "", tmpdir)
+            return install_local_binary(
+                source, binary, version=resolved, force=force, origin="release", target=target
+            )
+        wheels = []
+        for name, url in by_name.items():
+            if name.endswith(".whl"):
+                dest = tmpdir / name
+                _download(url, dest)
+                wheels.append(dest)
+        if not wheels:
+            raise InstallError(f"release {tag} carried no .whl assets")
+        return install_local_python(source, wheels, version=resolved, force=force, origin="release")
+
+
+def install_local_binary(
+    source: AgentSource,
+    binary: str | Path,
+    *,
+    version: str = "local",
+    force: bool = False,
+    origin: str = "local",
+    target: str | None = None,
+) -> InstallResult:
+    """Install a prebuilt binary agent from a local file."""
+    binary = Path(binary)
+    if not binary.is_file():
+        raise InstallError(f"binary not found: {binary}")
+    d = _prepare_dir(source.name, force=force)
+    dest = d / "bin" / (source.binary_name or binary.name)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(binary, dest)
+    dest.chmod(0o755)
+    command = [str(dest)]
+    _finalize(d, source, command, version=version, kind="binary", origin=origin, target=target)
+    return InstallResult(source.name, version, "binary", origin, d, command)
+
+
+def install_local_python(
+    source: AgentSource,
+    wheels: list[str | Path],
+    *,
+    version: str = "local",
+    force: bool = False,
+    origin: str = "local",
+) -> InstallResult:
+    """Install a Python agent into a managed venv from a local wheel set."""
+    uv = shutil.which("uv")
+    if uv is None:
+        raise InstallError(
+            "installing a Python agent needs `uv` on PATH (https://docs.astral.sh/uv/)"
+        )
+    paths_ = [Path(w) for w in wheels]
+    missing = [w for w in paths_ if not w.is_file()]
+    if missing:
+        raise InstallError("wheel(s) not found: " + ", ".join(str(w) for w in missing))
+
+    d = _prepare_dir(source.name, force=force)
+    venv = d / "venv"
+    _run([uv, "venv", str(venv)], "create the venv")
+    py = venv / "bin" / "python"
+    # Install the wheels by FILE PATH (not by dist name). This pins `avp` to our
+    # in-repo wheel so the index is never consulted for it: there is an unrelated
+    # `avp` on PyPI, and resolving by name would let uv pick that (higher-version)
+    # package instead. The agent's third-party deps (claude-agent-sdk) still
+    # resolve from PyPI normally.
+    _run(
+        [uv, "pip", "install", "--python", str(py), *[str(w) for w in paths_]],
+        "install the agent wheels",
+    )
+    command = [str(py), "-m", source.module or ""]
+    _finalize(d, source, command, version=version, kind="python", origin=origin)
+    return InstallResult(source.name, version, "python", origin, d, command)
+
+
+def uninstall(name: str) -> bool:
+    """Remove an installed agent. Returns False if it wasn't installed."""
+    d = paths.agents_dir() / name
+    if not d.exists():
+        return False
+    shutil.rmtree(d)
+    return True
+
+
+def installed_info(name: str) -> dict | None:
+    """The provenance record for an installed agent, or None."""
+    p = paths.agents_dir() / name / "installed.json"
+    if not p.is_file():
+        return None
+    try:
+        return json.loads(p.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+# ── internals ─────────────────────────────────────────────────────────────────
+
+
+def _prepare_dir(name: str, *, force: bool) -> Path:
+    d = paths.agents_dir() / name
+    if d.exists():
+        if not force:
+            raise InstallError(
+                f"agent {name!r} is already installed at {d}; pass --force to reinstall"
+            )
+        shutil.rmtree(d)
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _finalize(
+    d: Path,
+    source: AgentSource,
+    command: list[str],
+    *,
+    version: str,
+    kind: str,
+    origin: str,
+    target: str | None = None,
+) -> None:
+    """Write the generated manifest + provenance record."""
+    manifest = {
+        "command": command,
+        "cwd": ".",
+        "env": {},
+        "description": f"{source.name} ({origin} {kind} agent)",
+    }
+    (d / "avp-conformance.json").write_text(json.dumps(manifest, indent=2) + "\n")
+    record = {
+        "name": source.name,
+        "version": version,
+        "kind": kind,
+        "source": origin,
+        "installed_at": datetime.now(UTC).isoformat(timespec="seconds"),
+        "command": command,
+    }
+    if target:
+        record["target"] = target
+    (d / "installed.json").write_text(json.dumps(record, indent=2) + "\n")
+
+
+def _resolve_release(source: AgentSource, version: str | None) -> tuple[str, str, list[dict]]:
+    """Return (tag, version, assets) for the requested (or newest) release."""
+    if version:
+        tag = f"{source.tag_prefix}-v{version}"
+        rel = _api(f"/releases/tags/{tag}")
+        return tag, version, rel.get("assets", [])
+    prefix = f"{source.tag_prefix}-v"
+    for rel in _api("/releases?per_page=100"):  # the API returns newest first
+        tag = rel.get("tag_name", "")
+        if tag.startswith(prefix):
+            return tag, tag[len(prefix) :], rel.get("assets", [])
+    raise InstallError(
+        f"no releases for {source.name} (tag prefix {prefix!r}) in {RELEASE_REPO}; "
+        "pass --version, or build + install locally with --binary / --wheel"
+    )
+
+
+def _auth_headers() -> dict[str, str]:
+    headers = {"User-Agent": "avp-cli", "Accept": "application/vnd.github+json"}
+    token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
+    if token:  # only needed for private repos / API rate limits; public needs none
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def _api(path: str):
+    url = f"https://api.github.com/repos/{RELEASE_REPO}{path}"
+    req = urllib.request.Request(url, headers=_auth_headers())
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.load(resp)
+    except urllib.error.HTTPError as exc:
+        raise InstallError(f"GitHub API {exc.code} ({exc.reason}) for {url}") from exc
+    except (urllib.error.URLError, TimeoutError) as exc:
+        raise InstallError(f"network error reaching GitHub: {exc}") from exc
+
+
+def _download(url: str, dest: Path) -> None:
+    req = urllib.request.Request(url, headers=_auth_headers())
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp, dest.open("wb") as f:
+            shutil.copyfileobj(resp, f)
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise InstallError(f"failed to download {url}: {exc}") from exc
+
+
+def _extract_binary(archive: Path, binary_name: str, dest: Path) -> Path:
+    with tarfile.open(archive) as tar:
+        tar.extractall(dest)  # trusted: our own release artifact
+    for p in dest.rglob(binary_name):
+        if p.is_file():
+            return p
+    raise InstallError(f"{archive.name} did not contain {binary_name!r}")
+
+
+def _run(cmd: list[str], what: str) -> str:
+    try:
+        result = subprocess.run(cmd, check=True, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise InstallError(f"could not run {cmd[0]!r}: {exc}") from exc
+    except subprocess.CalledProcessError as exc:
+        tail = "\n".join((exc.stderr or exc.stdout or "").strip().splitlines()[-5:])
+        raise InstallError(f"failed to {what}:\n{tail or '(no output)'}") from exc
+    return result.stdout

avp_cli/agent_manifest.py

@@ -0,0 +1,73 @@
+"""How the CLI invokes an installed agent (the `avp-conformance.json` shape).
+
+An agent ships an `avp-conformance.json` manifest describing how to spawn it.
+The supervisor (this CLI) reads that file to run the agent, on the host for
+`describe`/`list` and inside a sandbox for `eval`/`run` (the `container` block).
+This is a deployment contract the supervisor owns; the conformance harness keeps
+its own copy for the same file, since spawning agents is a deployment concern and
+the shared `avp` wire-types package deliberately stays out of it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from avp.envelope import _STRICT
+
+
+class ContainerSpec(BaseModel):
+    """How a supervisor installs and runs this agent inside a Linux sandbox.
+
+    `install` steps are Dockerfile RUN shell strings executed at image-build
+    time (network available); `command` is the in-sandbox argv prefix honoring
+    the same run contract as the host `command`.
+    """
+
+    model_config = _STRICT
+
+    install: list[str] = Field(
+        default_factory=list,
+        description="Image-build RUN steps that install a Linux build of the agent.",
+    )
+    command: list[str] = Field(
+        min_length=1,
+        description="Argv list used to run the agent inside the sandbox.",
+    )
+    env: dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables the agent requires inside the sandbox.",
+    )
+
+
+class AgentManifest(BaseModel):
+    """How the CLI spawns the agent subprocess.
+
+    `cwd` is resolved relative to the manifest file's location, not the CLI's
+    working directory. Resolution is the caller's responsibility; this model
+    only validates shape.
+    """
+
+    model_config = _STRICT
+
+    command: list[str] = Field(
+        min_length=1,
+        description="Argv list used to spawn the agent subprocess.",
+    )
+    cwd: Path = Field(
+        default=Path("."),
+        description="Working directory, relative to the manifest's location.",
+    )
+    env: dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables passed to the subprocess.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Human-readable label for CLI output.",
+    )
+    container: ContainerSpec | None = Field(
+        default=None,
+        description="Optional: how to install and run this agent inside a sandbox.",
+    )

avp_cli/agents.py

@@ -0,0 +1,258 @@
+"""The agents an eval can run against: Goose and Claude Code.
+
+Each is just its `avp-conformance.json` manifest, the same one the conformance
+harness drives. An agent can come from one of three places, tried in order by
+`resolve_agent`:
+
+1. **An explicit manifest path** (`--agent path/to/avp-conformance.json`) for
+   any third-party agent, no code change.
+2. **An installed agent** under `~/.avp/agents/<name>/` (a prebuilt artifact laid
+   down by `avp agent install`). This is the normal path once published.
+3. **The in-repo dev fallback** (`agents/<name>/<lang>/avp-conformance.json`),
+   used only when running from a source checkout. Its manifest builds the agent
+   from source (`cargo run` / `uv run`), so it's slow and needs the toolchain.
+
+`AGENT_SOURCES` describes, per known agent, how it's distributed (a prebuilt
+binary vs. a Python wheel set) and where its dev-fallback manifest lives; the
+installer (`avp_cli.agent_install`) consumes it. `preflight` reports why an
+agent can't run *on the host* (the `describe` path); actual runs happen inside
+a sandbox, where `container_recipe` supplies the Linux install + run recipe
+(from the manifest's `container` block, or built in here for known agents).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from avp_cli import paths
+from avp_cli.agent import load_manifest
+from avp_cli.agent_manifest import AgentManifest
+from avp_cli.images import ContainerRecipe
+
+
+@dataclass(frozen=True)
+class AgentSource:
+    """How a known agent is distributed and how the CLI installs / falls back to it.
+
+    `kind` selects the install mechanism: `"binary"` (a prebuilt executable
+    extracted to `bin/`) or `"python"` (a wheel set installed into a managed
+    `venv/`). `tag_prefix` is the GitHub release tag stem (`agent-goose` →
+    `agent-goose-v0.0.1`). `dev_manifest` is the in-repo manifest used only from
+    a source checkout.
+    """
+
+    name: str
+    kind: str  # "binary" | "python"
+    tag_prefix: str
+    dev_manifest: str
+    # The release version whose Linux artifacts the container recipe installs.
+    # Pinned so the derived image is content-addressed; bump with releases.
+    container_version: str = ""
+    # binary agents
+    binary_name: str | None = None
+    # python agents: `python -m <module>`, install `dist` (pulls third-party
+    # deps from PyPI), with `wheel_dists` the unpublished in-repo wheels shipped
+    # on the release (resolved via --find-links so PyPI's unrelated `avp` isn't).
+    module: str | None = None
+    dist: str | None = None
+    wheel_dists: tuple[str, ...] = field(default_factory=tuple)
+
+
+AGENT_SOURCES: dict[str, AgentSource] = {
+    "goose": AgentSource(
+        name="goose",
+        kind="binary",
+        tag_prefix="agent-goose",
+        dev_manifest="agents/avp-goose/rust/avp-conformance.json",
+        container_version="0.0.3",
+        binary_name="avp-goose-conformance",
+    ),
+    "claude-code": AgentSource(
+        name="claude-code",
+        kind="python",
+        tag_prefix="agent-claude-code",
+        dev_manifest="agents/avp-claude-agent-sdk/python/avp-conformance.json",
+        # 0.0.4: the wire wheel was renamed avp -> agent-voyager-project, so the
+        # bundled wheel filename changed; this release carries the new names.
+        container_version="0.0.4",
+        module="avp_claude_agent_sdk.conformance",
+        dist="avp-claude-agent-sdk",
+        # The conformance entrypoint also imports avp_conformance (load_commission
+        # / load_built_in), which pulls the wire types + typer; ship all the
+        # in-repo wheels. `agent-voyager-project` is the renamed `avp` dist.
+        wheel_dists=("agent-voyager-project", "avp-conformance", "avp-claude-agent-sdk"),
+    ),
+}
+
+_RELEASE_DL = "https://github.com/portofcontext/agent-voyager-project/releases/download"
+
+
+def _builtin_recipe(source: AgentSource) -> ContainerRecipe:
+    """The container recipe for an in-tree agent, pinned to `container_version`.
+
+    Install steps run at image-build time (full network); `$(uname -m)` picks
+    the asset for the image's arch (aarch64 on Apple Silicon, x86_64 on amd64),
+    matching the release's `-unknown-linux-gnu` artifact names.
+    """
+    tag = f"{source.tag_prefix}-v{source.container_version}"
+    if source.kind == "binary":
+        asset = f"{source.binary_name}-$(uname -m)-unknown-linux-gnu.tar.gz"
+        return ContainerRecipe(
+            install=(
+                "apt-get update && apt-get install -y --no-install-recommends "
+                "curl ca-certificates && rm -rf /var/lib/apt/lists/*",
+                f"curl -fsSL {_RELEASE_DL}/{tag}/{asset} | tar -xz -C /usr/local/bin "
+                f"&& chmod +x /usr/local/bin/{source.binary_name}",
+            ),
+            command=(source.binary_name or source.name,),
+        )
+    # Python agent: the in-repo wheels come off the GitHub release (they are not
+    # on PyPI); third-party deps resolve from PyPI at build time. Node ships the
+    # `claude` CLI the agent shells out to. Assumes a python base image (the
+    # default env image is one); a wrong base fails loudly in the build log.
+    version = "0.1.0"  # wheel version on the release
+    wheels = " ".join(
+        f"{_RELEASE_DL}/{tag}/{d.replace('-', '_')}-{version}-py3-none-any.whl"
+        for d in source.wheel_dists
+    )
+    return ContainerRecipe(
+        install=(
+            "apt-get update && apt-get install -y --no-install-recommends "
+            "nodejs npm ca-certificates && rm -rf /var/lib/apt/lists/*",
+            "npm install -g @anthropic-ai/claude-code",
+            f"pip install --no-cache-dir {wheels}",
+        ),
+        command=("python", "-m", source.module or ""),
+        # The claude CLI refuses bypassPermissions as root (the container's
+        # default user) unless it's told it is already inside a sandbox. It is.
+        env=(("IS_SANDBOX", "1"),),
+    )
+
+
+class NoContainerRecipe(Exception):
+    """The agent can't run: no `container` block and no built-in recipe."""
+
+
+def container_recipe(agent: ResolvedAgent) -> ContainerRecipe:
+    """How `agent` gets into and runs inside a sandbox image.
+
+    A manifest's `container` block wins (third-party agents describe
+    themselves); known agents fall back to the built-in pinned recipe. An
+    agent with neither cannot run (runs are always sandboxed)."""
+    spec = agent.manifest.container
+    if spec is not None:
+        return ContainerRecipe(
+            install=tuple(spec.install),
+            command=tuple(spec.command),
+            env=tuple(spec.env.items()),
+        )
+    source = AGENT_SOURCES.get(agent.name)
+    if source is not None and source.container_version:
+        return _builtin_recipe(source)
+    raise NoContainerRecipe(
+        f"agent '{agent.name}' has no container recipe: runs execute in a Linux "
+        "sandbox, so its manifest needs a `container` block "
+        '({"install": ["<RUN step>", ...], "command": ["<argv>", ...]}).'
+    )
+
+
+DEFAULT_AGENT = "claude-code"
+
+
+def _repo_root() -> Path:
+    # .../avp-cli/src/avp_cli/agents.py -> repo root
+    return Path(__file__).resolve().parents[3]
+
+
+@dataclass(frozen=True)
+class ResolvedAgent:
+    name: str
+    manifest: AgentManifest
+    manifest_cwd: Path
+
+
+def known_agents() -> list[str]:
+    return list(AGENT_SOURCES)
+
+
+def installed_manifest_path(name: str) -> Path:
+    """Where an installed agent's generated manifest lives (may not exist)."""
+    return paths.agents_dir() / name / "avp-conformance.json"
+
+
+def is_installed(name: str) -> bool:
+    return installed_manifest_path(name).is_file()
+
+
+def has_dev_fallback(name: str) -> bool:
+    """True if a known agent's in-repo manifest exists (running from a checkout)."""
+    src = AGENT_SOURCES.get(name)
+    return src is not None and (_repo_root() / src.dev_manifest).is_file()
+
+
+def resolve_agent(spec: str) -> ResolvedAgent:
+    """Resolve a known agent name or a manifest path to a runnable agent."""
+    if spec in AGENT_SOURCES:
+        return _resolve_known(spec)
+    # Arbitrary third-party agent: spec is a path to its manifest.
+    path = Path(spec)
+    if not path.is_file():
+        raise SystemExit(f"agent manifest not found: {path}")
+    manifest, cwd = load_manifest(path)
+    return ResolvedAgent(name=path.parent.name or spec, manifest=manifest, manifest_cwd=cwd)
+
+
+def _resolve_known(name: str) -> ResolvedAgent:
+    """Installed agent first, then the in-repo dev fallback."""
+    installed = installed_manifest_path(name)
+    if installed.is_file():
+        manifest, cwd = load_manifest(installed)
+        return ResolvedAgent(name=name, manifest=manifest, manifest_cwd=cwd)
+    dev = _repo_root() / AGENT_SOURCES[name].dev_manifest
+    if dev.is_file():
+        manifest, cwd = load_manifest(dev)
+        return ResolvedAgent(name=name, manifest=manifest, manifest_cwd=cwd)
+    raise SystemExit(
+        f"agent '{name}' is not installed and no in-repo copy was found.\n"
+        f"  install it:             avp agent install {name}\n"
+        f"  or point at a manifest: --agent <path/to/avp-conformance.json>"
+    )
+
+
+def preflight(name: str) -> str | None:
+    """Return why `name` can't run here, or None if its prerequisites are present.
+
+    An installed agent is a self-contained artifact, so its only prerequisites
+    are runtime ones (e.g. the `claude` CLI the Claude agent shells out to). The
+    in-repo dev fallback builds from source, so it additionally needs the build
+    toolchain. The API key is checked separately by the CLI; every agent needs it.
+    """
+    if is_installed(name):
+        return _installed_preflight(name)
+    if name == "goose":
+        if shutil.which("cargo") is None:
+            return (
+                "cargo not on PATH (the in-repo Goose agent builds via cargo; "
+                "or run `avp agent install goose` for the prebuilt binary)"
+            )
+        return None
+    if name == "claude-code":
+        if importlib.util.find_spec("claude_agent_sdk") is None:
+            return (
+                "claude-agent-sdk not installed (pip install claude-agent-sdk, "
+                "or run `avp agent install claude-code`)"
+            )
+        if shutil.which("claude") is None:
+            return "the `claude` CLI is not on PATH"
+        return None
+    return None  # custom manifest: trust the caller
+
+
+def _installed_preflight(name: str) -> str | None:
+    """Runtime prerequisites for an already-installed agent."""
+    if name == "claude-code" and shutil.which("claude") is None:
+        return "the `claude` CLI is not on PATH (the Claude agent shells out to it)"
+    return None