graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/_project.py

@@ -0,0 +1,462 @@
+# Copyright 2026 Google LLC
+# Modifications Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Project manifest reader (``graph-agents-cli-manifest.yaml``) and prerequisite guards.
+
+The manifest fields are defined by the ProjectInfo model below. There is no legacy
+``pyproject.toml`` fallback: the manifest is the only project marker.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import click
+import yaml
+
+from graph_agents_cli._api_policy import ApiPolicyConfigError, manifest_policy_file_problem
+from graph_agents_cli._defaults import (
+    DEFAULT_AGENT_GUIDANCE_FILENAME,
+    DEFAULT_CD,
+    DEFAULT_MODEL_PROVIDER,
+    DEFAULT_MODELS,
+    DEFAULT_RUNTIME,
+    ENVIRONMENTS,
+    PROVIDER_KEY_VARS,
+    auth_policy_implemented_default,
+    default_secret_keys,
+    normalize_auth_policy,
+)
+
+MANIFEST_FILENAME = "graph-agents-cli-manifest.yaml"
+API_POLICY_FILENAME = "api-policy.yaml"
+
+# Exit code of a configuration error (0 ok, 1 refused or failed gate, 2 tool
+# failure, 3 configuration error).
+EXIT_CONFIG_ERROR = 3
+
+
+class ManifestError(click.ClickException):
+    """The project manifest cannot be read or has the wrong shape (exit 3)."""
+
+    exit_code = EXIT_CONFIG_ERROR
+
+
+class NotInProjectError(click.ClickException):
+    """The command needs a project and none encloses the working directory (exit 3)."""
+
+    exit_code = EXIT_CONFIG_ERROR
+
+
+@dataclass
+class SecretsConfig:
+    """The ``secrets:`` block: allow-listed Secret keys and their owner."""
+
+    keys: list[str] = field(default_factory=list)
+    owner: str = ""
+
+
+@dataclass
+class ApiPolicyConfig:
+    """The ``api_policy:`` block. ``policy_file`` is None when no policy is declared."""
+
+    policy_file: str | None = None
+
+
+@dataclass
+class ProjectConfig:
+    """Configuration read from ``graph-agents-cli-manifest.yaml``.
+
+    Every manifest key is an attribute. ``create_params`` is kept as the raw
+    dict (for ``generation_metadata``) and also exposed through typed
+    properties with the defaults of ``graph_agents_cli._defaults``.
+    """
+
+    project_name: str = ""
+    cli_version: str = ""
+    # The ``cli_build`` block as written (``scaffold.utils.build_record`` parses
+    # and validates it): the build that rendered the project. None when absent.
+    cli_build: Any = None
+    agent_directory: str = "app"
+    base_template: str = "langgraph"
+    generated_at: str = ""
+    language: str = "python"
+    create_params: dict[str, Any] = field(default_factory=dict)
+    environments: dict[str, dict[str, str]] = field(default_factory=dict)
+    secrets: SecretsConfig = field(default_factory=SecretsConfig)
+    api_policy: ApiPolicyConfig = field(default_factory=ApiPolicyConfig)
+    process: str | None = None
+    # True when the manifest still has the retired ``product_api:`` block;
+    # create/enhance/upgrade/lint stop with a migration message (exit 3).
+    has_legacy_product_api: bool = False
+
+    # -- manifest aliases -------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        """The manifest's ``name`` key (alias of ``project_name``)."""
+        return self.project_name
+
+    # -- create_params, typed ----------------------------------------------
+
+    @property
+    def deployment_target(self) -> str:
+        return str(self.create_params.get("deployment_target") or "none")
+
+    @property
+    def runtime(self) -> str:
+        return str(self.create_params.get("runtime") or DEFAULT_RUNTIME)
+
+    @property
+    def model_provider(self) -> str:
+        return str(self.create_params.get("model_provider") or DEFAULT_MODEL_PROVIDER)
+
+    @property
+    def model(self) -> str:
+        recorded = self.create_params.get("model")
+        if recorded:
+            return str(recorded)
+        return DEFAULT_MODELS.get(self.model_provider, "")
+
+    @property
+    def checkpointer(self) -> str:
+        recorded = self.create_params.get("checkpointer")
+        if recorded:
+            return str(recorded)
+        # A deployed project defaults to postgres; a local-only project to memory.
+        return "postgres" if self.deployment_target == "kubernetes" else "memory"
+
+    @property
+    def registry(self) -> str:
+        return str(self.create_params.get("registry") or "")
+
+    @property
+    def cd(self) -> str:
+        return str(self.create_params.get("cd") or DEFAULT_CD)
+
+    @property
+    def auth_policy(self) -> str:
+        """The recorded policy; the retired ``product-session`` reads as ``custom`` (with a warning)."""
+        return normalize_auth_policy(self.create_params.get("auth_policy"))
+
+    @property
+    def auth_policy_implemented(self) -> bool:
+        recorded = self.create_params.get("auth_policy_implemented")
+        if recorded is None:
+            return auth_policy_implemented_default(self.auth_policy)
+        return bool(recorded)
+
+    @property
+    def agent_guidance_filename(self) -> str:
+        return str(
+            self.create_params.get("agent_guidance_filename") or DEFAULT_AGENT_GUIDANCE_FILENAME
+        )
+
+    # -- convenience --------------------------------------------------------
+
+    @property
+    def secret_keys(self) -> list[str]:
+        return list(self.secrets.keys)
+
+    @property
+    def api_policy_file(self) -> str | None:
+        return self.api_policy.policy_file
+
+    def provider_key_var(self) -> str:
+        """The Secret key that carries the model provider's API key."""
+        return PROVIDER_KEY_VARS.get(self.model_provider, "MODEL_API_KEY")
+
+    def environment(self, env: str) -> tuple[str, str]:
+        """Return ``(context, namespace)`` for ``env``.
+
+        The manifest's ``environments:`` block wins. An environment the block
+        does not name but the CLI knows (dev, staging, prod) falls back to an
+        empty context (the current kube context) and the ``<name>-<env>``
+        namespace convention. Anything else is a usage error.
+        """
+        recorded = self.environments.get(env)
+        if recorded is not None:
+            context = str(recorded.get("context") or "")
+            namespace = str(recorded.get("namespace") or f"{self.project_name}-{env}")
+            return context, namespace
+        if env in ENVIRONMENTS:
+            return "", f"{self.project_name}-{env}"
+        known = ", ".join(sorted(set(self.environments) | set(ENVIRONMENTS)))
+        raise click.UsageError(
+            f"Unknown environment '{env}'. Known environments: {known}.\n"
+            f"  Add it under environments: in {MANIFEST_FILENAME}."
+        )
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Mapping[str, Any] | Any,
+        filename: str = MANIFEST_FILENAME,
+    ) -> ProjectConfig:
+        """Create a ProjectConfig from a raw manifest mapping."""
+        if not isinstance(data, Mapping):
+            raise ManifestError(f"malformed {filename}")
+
+        cfg = cls()
+        cfg.project_name = str(data.get("name") or cfg.project_name)
+        cfg.cli_version = str(data.get("cli_version") or cfg.cli_version)
+        cfg.cli_build = data.get("cli_build")
+        cfg.agent_directory = str(data.get("agent_directory") or cfg.agent_directory)
+        cfg.base_template = str(data.get("base_template") or cfg.base_template)
+        cfg.generated_at = str(data.get("generated_at") or cfg.generated_at)
+        cfg.language = str(data.get("language") or cfg.language)
+
+        create_params = data.get("create_params")
+        if create_params is None:
+            create_params = {}
+        elif not isinstance(create_params, Mapping):
+            raise ManifestError(f"malformed create_params in {filename}")
+        cfg.create_params = dict(create_params)
+
+        environments = data.get("environments") or {}
+        if not isinstance(environments, Mapping):
+            raise ManifestError(f"malformed environments in {filename}")
+        parsed_envs: dict[str, dict[str, str]] = {}
+        for env_name, env_data in environments.items():
+            if env_data is None:
+                env_data = {}
+            if not isinstance(env_data, Mapping):
+                raise ManifestError(f"malformed environments.{env_name} in {filename}")
+            parsed_envs[str(env_name)] = {
+                "context": str(env_data.get("context") or ""),
+                "namespace": str(env_data.get("namespace") or f"{cfg.project_name}-{env_name}"),
+            }
+        cfg.environments = parsed_envs
+
+        secrets = data.get("secrets") or {}
+        if not isinstance(secrets, Mapping):
+            raise ManifestError(f"malformed secrets in {filename}")
+        raw_keys = secrets.get("keys")
+        if isinstance(raw_keys, str):
+            raw_keys = [raw_keys]
+        keys = [str(k) for k in raw_keys] if raw_keys else []
+        if not keys:
+            # No recorded allow-list: the default follows the provider and runtime.
+            keys = default_secret_keys(cfg.model_provider, cfg.runtime, auth_policy=cfg.auth_policy)
+        cfg.secrets = SecretsConfig(keys=keys, owner=str(secrets.get("owner") or ""))
+
+        api_policy = data.get("api_policy") or {}
+        if not isinstance(api_policy, Mapping):
+            raise ManifestError(f"malformed api_policy in {filename}")
+        policy_file = api_policy.get("policy_file")
+        problem = manifest_policy_file_problem(policy_file, filename)
+        if problem:
+            raise ApiPolicyConfigError(problem)
+        cfg.api_policy = ApiPolicyConfig(policy_file=API_POLICY_FILENAME if policy_file else None)
+        cfg.has_legacy_product_api = "product_api" in data
+
+        process = data.get("process")
+        cfg.process = str(process) if process else None
+
+        return cfg
+
+
+def _read_project_config_from_manifest(manifest_path: Path) -> ProjectConfig:
+    """Read project configuration from a manifest file (unreadable or invalid YAML: exit 3)."""
+    try:
+        with open(manifest_path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as exc:
+        where = ""
+        mark = getattr(exc, "problem_mark", None)
+        if mark is not None:
+            where = f" (line {mark.line + 1}, column {mark.column + 1})"
+        problem = getattr(exc, "problem", None) or str(exc).splitlines()[0]
+        raise ManifestError(
+            f"{manifest_path} is not valid YAML{where}: {problem}.\n"
+            "  Fix the file, or restore it from version control."
+        ) from None
+    except (OSError, UnicodeDecodeError) as exc:
+        raise ManifestError(f"Cannot read {manifest_path}: {exc}") from None
+    if data is None:
+        data = {}
+    return ProjectConfig.from_dict(data, filename=manifest_path.name)
+
+
+def read_project_config(project_dir: str | None = None) -> ProjectConfig:
+    """Read project metadata from ``graph-agents-cli-manifest.yaml``.
+
+    Returns a default ``ProjectConfig`` when the directory holds no manifest.
+
+    Args:
+        project_dir: Directory containing the manifest. Defaults to the
+            current working directory.
+    """
+    root = Path(project_dir) if project_dir else Path.cwd()
+    manifest_path = root / MANIFEST_FILENAME
+    if manifest_path.exists():
+        return _read_project_config_from_manifest(manifest_path)
+    return ProjectConfig()
+
+
+def _parse_version(v: str) -> tuple[int, ...]:
+    """Parse a dotted numeric version into a comparable tuple.
+
+    Raises ``ValueError`` on non-numeric components (e.g. a ``0.0.0-dev``
+    source build), which callers treat as "version unknown, don't compare".
+    """
+    return tuple(int(x) for x in v.split("."))
+
+
+def scaffold_older_than(cfg: ProjectConfig, version: str) -> bool:
+    """True when the version that scaffolded ``cfg`` is older than ``version``.
+
+    Best-effort: returns False when the scaffold version is missing or
+    non-numeric, so callers fall back to generic guidance instead of guessing.
+    """
+    if not cfg.cli_version:
+        return False
+    try:
+        return _parse_version(cfg.cli_version) < _parse_version(version)
+    except ValueError:
+        return False
+
+
+def check_cli_version(cfg: ProjectConfig) -> None:
+    """Warn if the running CLI version differs from the one that scaffolded the project.
+
+    Emits a warning with upgrade guidance on a mismatch; never blocks execution.
+    """
+    cli_version = cfg.cli_version
+    if not cli_version:
+        return
+
+    from graph_agents_cli import __version__
+
+    try:
+        project_ver = _parse_version(cli_version)
+        cli_ver = _parse_version(__version__)
+    except ValueError:
+        return
+
+    if cli_ver < project_ver:
+        from graph_agents_cli.scaffold.utils.version import install_command
+
+        click.echo(
+            f"\n⚠️  Version mismatch: project was scaffolded with graph-agents-cli {cli_version},"
+            f" running {__version__}.\n"
+            f"   Upgrade the CLI: {install_command(version=cli_version)}\n",
+            err=True,
+        )
+    elif cli_ver > project_ver:
+        click.echo(
+            f"\n⚠️  Version mismatch: project was scaffolded with graph-agents-cli {cli_version},"
+            f" running {__version__}.\n"
+            "   Upgrade the project: graph-agents-cli scaffold upgrade\n",
+            err=True,
+        )
+
+
+def find_project_root(dir: Path | None = None) -> Path | None:
+    """Find the project root by walking up looking for the manifest."""
+    if dir is None:
+        dir = Path.cwd()
+    for parent in [dir, *dir.parents]:
+        if (parent / MANIFEST_FILENAME).exists():
+            return parent
+    return None
+
+
+def is_project_moved() -> bool:
+    """Check if the project has been moved by comparing the current path with .venv/bin/activate."""
+    root = find_project_root(Path.cwd())
+    if not root:
+        return False
+
+    venv_dir = root / ".venv"
+    # Support both Unix-style (bin) and Windows-style (Scripts) virtualenvs
+    activate_script = venv_dir / "bin" / "activate"
+    if not activate_script.exists():
+        activate_script = venv_dir / "Scripts" / "activate"
+
+    if not activate_script.exists():
+        return False
+
+    try:
+        with open(activate_script, encoding="utf-8") as f:
+            for line in f:
+                if line.startswith("VIRTUAL_ENV="):
+                    stored_path_str = line.split("=", 1)[1].strip().strip("'\"")
+                    stored_path = Path(stored_path_str).resolve()
+                    current_path = venv_dir.resolve()
+                    return stored_path != current_path
+    except Exception as e:
+        logging.warning(f"Error checking if project moved: {e}")
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Prerequisite guards, reusable checks for CLI commands
+# ---------------------------------------------------------------------------
+
+
+def chdir_project_root(dir: Path | None = None) -> None:
+    """Locate the project root relative to ``dir`` and chdir to it; raise if none."""
+    if dir is None:
+        dir = Path.cwd()
+    root = find_project_root(dir)
+    if not root:
+        raise NotInProjectError(
+            f"No {MANIFEST_FILENAME} found in the current directory or its parents.\n"
+            "  Run this command from your project root, or create a project first:\n"
+            "    graph-agents-cli create my-agent"
+        )
+    # Only announce the root when we actually move (i.e. run from a subdir).
+    if root.resolve() != Path.cwd().resolve():
+        click.echo(f"Using project root directory: {root}", err=True)
+    os.chdir(root)
+
+
+def require_agent_directory(cfg: ProjectConfig) -> None:
+    """Raise if the configured agent_directory doesn't exist. Assumes cwd is the project root."""
+    agent_path = Path(cfg.agent_directory)
+    if not agent_path.is_dir():
+        raise click.ClickException(
+            f"Agent directory '{cfg.agent_directory}' not found.\n"
+            "  Ensure you're in the project root and that the directory exists.\n"
+            f"  The agent_directory is configured in {MANIFEST_FILENAME}."
+        )
+
+
+def require_deployment_target(cfg: ProjectConfig) -> None:
+    """Raise a UsageError when the project has no deployment target (``none``)."""
+    if cfg.deployment_target in ("none", ""):
+        raise click.UsageError(
+            "No deployment target configured (deployment_target is 'none').\n"
+            f"  Set create_params.deployment_target in {MANIFEST_FILENAME},\n"
+            "  or add deployment support to your project:\n"
+            "    graph-agents-cli scaffold enhance --deployment-target kubernetes"
+        )
+
+
+def find_project_config(project_dir: Path | None = None) -> ProjectConfig | None:
+    """Read the manifest after resolving the project root from ``project_dir``.
+
+    Returns None when no project root is found.
+    """
+    project_root_dir = find_project_root(project_dir)
+    if project_root_dir is None:
+        return None
+    return read_project_config(str(project_root_dir))

graph_agents_cli/_remote.py

@@ -0,0 +1,220 @@
+# Copyright 2026 Google LLC
+# Modifications Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Request headers and URL classification for talking to a remote agent.
+
+Transport-neutral so every caller (``run``, ``eval generate``) agrees on which
+credentials a ``--url`` gets and where the chat or A2A surface lives.
+Credentials follow the project's auth policy:
+
+* ``--header 'Authorization: Bearer ...'`` or ``GRAPH_AGENTS_CLI_API_KEY``
+  for ``shared-bearer`` (and a JWT in the same header for ``jwt``);
+* ``--header 'Name: value'`` or ``--cookie name=value`` for a ``custom``
+  policy. The hidden ``--session-token`` option of ``run`` and ``eval`` is a
+  deprecated alias of ``--header 'X-Session-Token: ...'``: it still works, prints
+  a one-line deprecation warning, and is folded into the headers on entry.
+
+No cloud SDK is consulted; the CLI stores no credentials.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from typing import NamedTuple
+
+import click
+import httpx
+
+from graph_agents_cli import _http
+
+API_KEY_ENV = "GRAPH_AGENTS_CLI_API_KEY"
+SESSION_TOKEN_HEADER = "X-Session-Token"
+AGENT_CARD_PATH = "/.well-known/agent-card.json"
+
+RUN_MODES: tuple[str, ...] = ("chat", "a2a")
+DEFAULT_RUN_MODE = "chat"
+
+
+SESSION_TOKEN_DEPRECATION = (
+    "Warning: --session-token is deprecated and will be removed; "
+    "pass --header 'X-Session-Token: <token>' instead."
+)
+
+
+def deprecated_session_token(
+    _ctx: click.Context, _param: click.Parameter, value: str | None
+) -> str | None:
+    """Click callback of the hidden ``--session-token`` alias: warn once when it is used."""
+    if value:
+        click.echo(SESSION_TOKEN_DEPRECATION, err=True)
+    return value
+
+
+def fold_session_token(header: Sequence[str], session_token: str | None) -> tuple[str, ...]:
+    """``header`` plus the deprecated ``--session-token`` value as its ``X-Session-Token`` header.
+
+    Folding it into the ``--header`` values once, on entry, means everything
+    downstream (resume hints, extension overrides) only ever sees ``--header``.
+    """
+    if not session_token:
+        return tuple(header)
+    return (*header, f"{SESSION_TOKEN_HEADER}: {session_token}")
+
+
+def parse_header(value: str) -> tuple[str, str]:
+    """Parse one ``Key: Value`` header string."""
+    if ":" not in value:
+        raise click.BadParameter(f"Invalid header format (expected 'Key: Value'): {value}")
+    key, _, val = value.partition(":")
+    key = key.strip()
+    if not key:
+        raise click.BadParameter(f"Invalid header format (empty name): {value}")
+    return key, val.strip()
+
+
+def parse_cookie(value: str) -> tuple[str, str]:
+    """Parse one ``name=value`` cookie string."""
+    if "=" not in value:
+        raise click.BadParameter(f"Invalid cookie format (expected 'name=value'): {value}")
+    name, _, val = value.partition("=")
+    name = name.strip()
+    if not name:
+        raise click.BadParameter(f"Invalid cookie format (empty name): {value}")
+    return name, val.strip()
+
+
+def _has_header(headers: Mapping[str, str], name: str) -> bool:
+    lname = name.lower()
+    return any(k.lower() == lname for k in headers)
+
+
+def build_headers(
+    header: Sequence[str] = (),
+    cookie: Sequence[str] = (),
+    session_token: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Build the request headers for a chat or A2A call.
+
+    Precedence: explicit ``--header`` values are applied verbatim; ``--cookie``
+    pairs are folded into one ``Cookie`` header (appended to an explicit
+    ``Cookie`` header if one was given); ``--session-token`` becomes
+    ``X-Session-Token``; and when no ``Authorization`` header was supplied,
+    ``GRAPH_AGENTS_CLI_API_KEY`` from ``env`` (default ``os.environ``) becomes
+    ``Authorization: Bearer <key>``.
+    """
+    environ = os.environ if env is None else env
+    headers: dict[str, str] = {}
+    for raw in header:
+        key, val = parse_header(raw)
+        headers[key] = val
+
+    pairs = [parse_cookie(c) for c in cookie]
+    if pairs:
+        rendered = "; ".join(f"{k}={v}" for k, v in pairs)
+        existing_key = next((k for k in headers if k.lower() == "cookie"), None)
+        if existing_key is not None and headers[existing_key]:
+            headers[existing_key] = f"{headers[existing_key]}; {rendered}"
+        else:
+            headers[existing_key or "Cookie"] = rendered
+
+    if session_token:
+        headers[SESSION_TOKEN_HEADER] = session_token
+
+    if not _has_header(headers, "Authorization"):
+        api_key = environ.get(API_KEY_ENV, "")
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+    return headers
+
+
+class RemoteTarget(NamedTuple):
+    """Where a query goes: the chat base URL or the resolved A2A base URL."""
+
+    mode: str
+    base_url: str
+    # For ``a2a``: the base under which the agent card was found. ``None``
+    # for ``chat``.
+    a2a_base: str | None = None
+    card: dict | None = None
+
+
+def a2a_candidates(base_url: str, agent_directory: str | None) -> list[str]:
+    """A2A base URLs to probe for a card, in order.
+
+    The scaffolded app serves the card at ``/a2a/<agent_directory>``; the bare URL is tried second so a ``--url`` that already points
+    at the A2A base, or a spec-canonical root card, still works.
+    """
+    base = base_url.rstrip("/")
+    candidates: list[str] = []
+    if agent_directory:
+        candidates.append(f"{base}/a2a/{agent_directory}")
+    candidates.append(base)
+    return candidates
+
+
+def classify_url(
+    url: str,
+    *,
+    mode: str = DEFAULT_RUN_MODE,
+    agent_directory: str | None = None,
+    headers: Mapping[str, str] | None = None,
+    timeout: float = 30.0,
+) -> RemoteTarget:
+    """Resolve a ``--url`` into a :class:`RemoteTarget` for ``mode``.
+
+    ``chat`` needs no probing: the chat API lives at ``<url>/chat``. ``a2a``
+    probes ``<url>/a2a/<agent_directory>/.well-known/agent-card.json`` and then
+    ``<url>/.well-known/agent-card.json``; the first 200 wins.
+
+    Raises :class:`click.ClickException` when no card is found (listing each
+    probe) or :class:`click.BadParameter` for an unknown mode.
+    """
+    base = url.rstrip("/")
+    if mode == "chat":
+        return RemoteTarget(mode="chat", base_url=base)
+    if mode != "a2a":
+        raise click.BadParameter(f"Unknown mode {mode!r}; choose from {', '.join(RUN_MODES)}")
+
+    failures: list[tuple[str, str]] = []
+    for candidate in a2a_candidates(base, agent_directory):
+        card_url = f"{candidate}{AGENT_CARD_PATH}"
+        try:
+            resp = _http.get(card_url, headers=dict(headers or {}), timeout=timeout)
+        except httpx.TransportError as exc:
+            failures.append((card_url, f"unreachable: {exc}"))
+            continue
+        if resp.status_code == 200:
+            try:
+                card = resp.json()
+            except ValueError:
+                card = None
+            return RemoteTarget(
+                mode="a2a",
+                base_url=base,
+                a2a_base=candidate,
+                card=card if isinstance(card, dict) else None,
+            )
+        failures.append((card_url, f"HTTP {resp.status_code}: {resp.text[:200]}"))
+
+    detail = "\n".join(f"  {card_url}\n    {why}" for card_url, why in failures)
+    hint = ""
+    if base.endswith("/a2a"):
+        hint += "\n  Pass the base service URL without the '/a2a' suffix."
+    if any("HTTP 404" in why or "HTTP 405" in why for _, why in failures):
+        hint += "\n  If this agent only exposes the chat API, try --mode chat instead."
+    raise click.ClickException(f"Failed to fetch an A2A agent card:\n{detail}{hint}")