PyPI - haru-cli - Versions diffs - 0.1.0__py3-none-any.whl - Mend

haru-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

haru/__init__.py +1 -0
haru/__main__.py +12 -0
haru/agents/__init__.py +18 -0
haru/agents/factory.py +76 -0
haru/agents/orchestration.py +169 -0
haru/auth/__init__.py +14 -0
haru/auth/cache.py +82 -0
haru/auth/pkce.py +21 -0
haru/auth/session.py +95 -0
haru/auth/sso.py +206 -0
haru/cli.py +20 -0
haru/commands/__init__.py +1 -0
haru/commands/chat.py +102 -0
haru/commands/login.py +34 -0
haru/commands/run.py +60 -0
haru/commands/session.py +36 -0
haru/commands/streaming.py +34 -0
haru/config/__init__.py +6 -0
haru/config/loader.py +163 -0
haru/config/schema.py +261 -0
haru/errors.py +25 -0
haru/models/__init__.py +5 -0
haru/models/bedrock.py +77 -0
haru/observability/__init__.py +6 -0
haru/observability/guardrails.py +36 -0
haru/observability/telemetry.py +34 -0
haru/sessions/__init__.py +5 -0
haru/sessions/manager.py +70 -0
haru/steering/__init__.py +5 -0
haru/steering/prompts.py +42 -0
haru/tools/__init__.py +12 -0
haru/tools/mcp.py +137 -0
haru/tools/registry.py +41 -0
haru_cli-0.1.0.dist-info/METADATA +120 -0
haru_cli-0.1.0.dist-info/RECORD +38 -0
haru_cli-0.1.0.dist-info/WHEEL +4 -0
haru_cli-0.1.0.dist-info/entry_points.txt +2 -0
haru_cli-0.1.0.dist-info/licenses/LICENSE +202 -0

haru/auth/sso.py ADDED Viewed

@@ -0,0 +1,206 @@
+"""OAuth 2.0 Authorization Code + PKCE login against IAM Identity Center.
+Implements the same flow ``aws sso login`` uses by default since AWS CLI
+v2.22.0: register a public OIDC client, open the browser to the authorize
+endpoint, capture the code on a 127.0.0.1 loopback listener, and exchange it
+with ``CreateToken``. Only loopback redirect URIs are accepted.
+"""
+import secrets
+import time
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any, cast
+from urllib.parse import parse_qs, urlencode, urlsplit
+import boto3
+from botocore.exceptions import ClientError
+from haru.auth.pkce import generate_pkce_pair
+from haru.config.schema import AuthConfig
+from haru.errors import AuthError
+_LOOPBACK_HOST = "127.0.0.1"
+_CALLBACK_PATH = "/oauth/callback"
+_AUTHORIZE_SCOPES = "sso:account:access"
+_CALLBACK_RESPONSE = (
+    b"<html><body><p>Sign-in complete. You can close this window and return to haru.</p>"
+    b"</body></html>"
+)
+@dataclass(frozen=True)
+class ClientRegistration:
+    """A registered public OIDC client."""
+    client_id: str
+    client_secret: str
+    expires_at: datetime
+@dataclass(frozen=True)
+class SsoToken:
+    """An SSO access token plus the registration needed to refresh it."""
+    access_token: str
+    refresh_token: str | None
+    expires_at: datetime
+    registration: ClientRegistration
+def register_client(
+    oidc: Any, client_name: str, start_url: str, redirect_uri: str
+) -> ClientRegistration:
+    """Register a public OIDC client for the authorization-code + PKCE flow."""
+    host = urlsplit(redirect_uri).hostname
+    if host != _LOOPBACK_HOST:
+        raise AuthError(f"Redirect URI must be a {_LOOPBACK_HOST} loopback address, got {host!r}")
+    try:
+        response = oidc.register_client(
+            clientName=client_name,
+            clientType="public",
+            scopes=[_AUTHORIZE_SCOPES],
+            redirectUris=[redirect_uri],
+            issuerUrl=start_url,
+            grantTypes=["authorization_code", "refresh_token"],
+        )
+    except ClientError as exc:
+        raise AuthError(f"OIDC client registration failed: {exc}") from exc
+    return ClientRegistration(
+        client_id=response["clientId"],
+        client_secret=response["clientSecret"],
+        expires_at=datetime.fromtimestamp(response["clientSecretExpiresAt"], tz=UTC),
+    )
+def build_authorize_url(
+    region: str, client_id: str, redirect_uri: str, state: str, code_challenge: str
+) -> str:
+    """Build the IAM Identity Center authorize URL for the PKCE flow."""
+    query = urlencode(
+        {
+            "response_type": "code",
+            "client_id": client_id,
+            "redirect_uri": redirect_uri,
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "scopes": _AUTHORIZE_SCOPES,
+        }
+    )
+    return f"https://oidc.{region}.amazonaws.com/authorize?{query}"
+def exchange_code(
+    oidc: Any, registration: ClientRegistration, code: str, verifier: str, redirect_uri: str
+) -> SsoToken:
+    """Exchange an authorization code (plus PKCE verifier) for an SSO token."""
+    try:
+        response = oidc.create_token(
+            clientId=registration.client_id,
+            clientSecret=registration.client_secret,
+            grantType="authorization_code",
+            code=code,
+            codeVerifier=verifier,
+            redirectUri=redirect_uri,
+        )
+    except ClientError as exc:
+        raise AuthError(f"Token exchange failed: {exc}") from exc
+    return SsoToken(
+        access_token=response["accessToken"],
+        refresh_token=response.get("refreshToken"),
+        expires_at=datetime.now(UTC) + timedelta(seconds=response["expiresIn"]),
+        registration=registration,
+    )
+def run_login(
+    config: AuthConfig,
+    *,
+    oidc: Any | None = None,
+    opener: Callable[[str], object] | None = None,
+    timeout_seconds: float = 300.0,
+) -> SsoToken:
+    """Run the interactive browser login and return the resulting SSO token.
+    Orchestrates client registration, PKCE pair generation, opening the
+    authorize URL, capturing the code on a loopback listener (validating the
+    ``state`` parameter), and the CreateToken exchange.
+    """
+    sso = config.sso
+    if oidc is None:
+        oidc = boto3.Session().client("sso-oidc", region_name=sso.sso_region)
+    open_url = opener if opener is not None else webbrowser.open
+    server = _start_loopback_server(sso.callback_port)
+    try:
+        port = server.server_address[1]
+        redirect_uri = f"http://{_LOOPBACK_HOST}:{port}{_CALLBACK_PATH}"
+        registration = register_client(oidc, sso.client_name, sso.start_url, redirect_uri)
+        verifier, challenge = generate_pkce_pair()
+        state = secrets.token_urlsafe(32)
+        open_url(
+            build_authorize_url(
+                sso.sso_region, registration.client_id, redirect_uri, state, challenge
+            )
+        )
+        code, returned_state = _await_callback(server, timeout_seconds)
+        if not secrets.compare_digest(returned_state, state):
+            raise AuthError("State mismatch in OAuth callback; aborting login")
+        return exchange_code(oidc, registration, code, verifier, redirect_uri)
+    finally:
+        server.server_close()
+class _CallbackServer(HTTPServer):
+    """Loopback HTTP server that records the OAuth callback query parameters."""
+    callback_params: dict[str, list[str]] | None = None
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """Handles the single OAuth redirect request on the loopback listener."""
+    def do_GET(self) -> None:
+        parsed = urlsplit(self.path)
+        if parsed.path != _CALLBACK_PATH:
+            self.send_error(404)
+            return
+        server = cast(_CallbackServer, self.server)
+        server.callback_params = parse_qs(parsed.query)
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        self.wfile.write(_CALLBACK_RESPONSE)
+    def log_message(self, format: str, *args: object) -> None:
+        """Silence default request logging; callback URLs must never be logged."""
+def _start_loopback_server(port: int) -> _CallbackServer:
+    """Bind the loopback callback server (port 0 selects an ephemeral port)."""
+    try:
+        return _CallbackServer((_LOOPBACK_HOST, port), _CallbackHandler)
+    except OSError as exc:
+        raise AuthError(f"Could not bind loopback callback port {port}: {exc}") from exc
+def _await_callback(server: _CallbackServer, timeout_seconds: float) -> tuple[str, str]:
+    """Wait for the OAuth redirect and return its ``(code, state)`` pair."""
+    deadline = time.monotonic() + timeout_seconds
+    server.timeout = 1.0
+    while server.callback_params is None:
+        if time.monotonic() >= deadline:
+            raise AuthError("Timed out waiting for the browser sign-in to complete")
+        server.handle_request()
+    params = server.callback_params
+    if "error" in params:
+        raise AuthError(f"Authorization failed: {params['error'][0]}")
+    codes = params.get("code")
+    states = params.get("state")
+    if not codes or not states:
+        raise AuthError("OAuth callback is missing the code or state parameter")
+    return codes[0], states[0]

haru/cli.py ADDED Viewed

@@ -0,0 +1,20 @@
+"""Click command group for the haru CLI."""
+import click
+from haru.commands.chat import chat
+from haru.commands.login import login
+from haru.commands.run import run
+from haru.commands.session import session
+@click.group()
+@click.version_option(package_name="haru-cli", prog_name="haru")
+def cli() -> None:
+    """haru: a governed CLI for Amazon Bedrock agents."""
+cli.add_command(chat)
+cli.add_command(login)
+cli.add_command(run)
+cli.add_command(session)

haru/commands/__init__.py ADDED Viewed

	@@ -0,0 +1 @@
1	+ """Click command implementations for the haru CLI."""

haru/commands/chat.py ADDED Viewed

@@ -0,0 +1,102 @@
+"""The ``haru chat`` command: an interactive streaming REPL."""
+from collections.abc import Callable
+from pathlib import Path
+import click
+from rich.console import Console
+from haru.agents.factory import build_agent
+from haru.auth.session import build_boto3_session
+from haru.commands.streaming import collect_response, surface_guardrail
+from haru.config import load_config
+from haru.config.schema import HaruConfig
+from haru.errors import HaruError
+from haru.observability.telemetry import configure_telemetry
+from haru.sessions.manager import build_session_manager
+from haru.tools.mcp import started_mcp_clients
+_EXIT_WORDS = frozenset({"exit", "quit"})
+def run_chat(  # noqa: PLR0913 - keyword-only wiring points, all optional
+    config: HaruConfig,
+    agent_name: str | None,
+    *,
+    console: Console,
+    read_input: Callable[[str], str] = input,
+    prompts_root: Path | None = None,
+    session_id: str | None = None,
+) -> None:
+    """Run the interactive chat loop until the user exits."""
+    session = build_boto3_session(config.auth)
+    session_manager = (
+        build_session_manager(config, session_id, boto_session=session)
+        if session_id is not None
+        else None
+    )
+    with started_mcp_clients(config.mcp) as mcp_clients:
+        agent = build_agent(
+            config,
+            agent_name,
+            session,
+            prompts_root=prompts_root,
+            mcp_clients=mcp_clients,
+            session_manager=session_manager,
+        )
+        console.print("haru chat - type 'exit' or press Ctrl-D to leave.")
+        while True:
+            try:
+                line = read_input("you> ").strip()
+            except (EOFError, KeyboardInterrupt):
+                console.print("\nGoodbye.")
+                return
+            if not line:
+                continue
+            if line.lower() in _EXIT_WORDS:
+                console.print("Goodbye.")
+                return
+            try:
+                result = collect_response(
+                    agent,
+                    line,
+                    lambda text: console.print(text, end="", markup=False, highlight=False),
+                )
+            except KeyboardInterrupt:
+                console.print("\n[interrupted]")
+                continue
+            console.print()
+            surface_guardrail(result, console)
+@click.command()
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to haru.yaml (default: config/haru.yaml).",
+)
+@click.option("--agent", "agent_name", default=None, help="Agent name from configuration.")
+@click.option(
+    "--session-id",
+    "session_id",
+    default=None,
+    help="Persist and restore this conversation under the given session id.",
+)
+def chat(config_path: Path | None, agent_name: str | None, session_id: str | None) -> None:
+    """Chat interactively with a Bedrock agent (streaming)."""
+    console = Console()
+    try:
+        config = load_config(config_path)
+        configure_telemetry(config.observability)
+        prompts_root = config_path.parent / "prompts" if config_path is not None else None
+        run_chat(
+            config,
+            agent_name,
+            console=console,
+            prompts_root=prompts_root,
+            session_id=session_id,
+        )
+    except HaruError as exc:
+        raise click.ClickException(str(exc)) from exc

haru/commands/login.py ADDED Viewed

@@ -0,0 +1,34 @@
+"""The ``haru login`` command: interactive IAM Identity Center sign-in."""
+import webbrowser
+from pathlib import Path
+import click
+from haru.auth.cache import write_token_cache
+from haru.auth.sso import run_login
+from haru.config import load_config
+@click.command()
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to haru.yaml (default: config/haru.yaml).",
+)
+def login(config_path: Path | None) -> None:
+    """Sign in to AWS IAM Identity Center via the browser (PKCE)."""
+    config = load_config(config_path, with_includes=False)
+    auth = config.auth
+    def _open(url: str) -> None:
+        click.echo("Complete sign-in in your browser:")
+        click.echo(url)
+        if auth.sso.browser:
+            webbrowser.open(url)
+    token = run_login(auth, opener=_open)
+    path = write_token_cache(token, auth.sso.start_url, auth.sso.sso_region)
+    click.echo(f"Login successful. Token cached at {path}.")

haru/commands/run.py ADDED Viewed

@@ -0,0 +1,60 @@
+"""The ``haru run`` command: one-shot prompt execution."""
+from pathlib import Path
+import click
+from rich.console import Console
+from haru.agents.factory import build_agent
+from haru.auth.session import build_boto3_session
+from haru.commands.streaming import collect_response, surface_guardrail
+from haru.config import load_config
+from haru.config.schema import HaruConfig
+from haru.errors import HaruError
+from haru.observability.telemetry import configure_telemetry
+from haru.tools.mcp import started_mcp_clients
+def run_prompt(
+    config: HaruConfig,
+    prompt: str,
+    agent_name: str | None = None,
+    *,
+    console: Console | None = None,
+    prompts_root: Path | None = None,
+) -> str:
+    """Execute ``prompt`` once and return the full response text.
+    Guardrail interventions are surfaced on ``console`` (stderr by default).
+    """
+    session = build_boto3_session(config.auth)
+    with started_mcp_clients(config.mcp) as mcp_clients:
+        agent = build_agent(
+            config, agent_name, session, prompts_root=prompts_root, mcp_clients=mcp_clients
+        )
+        chunks: list[str] = []
+        result = collect_response(agent, prompt, chunks.append)
+    surface_guardrail(result, console if console is not None else Console(stderr=True))
+    return "".join(chunks)
+@click.command()
+@click.argument("prompt")
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to haru.yaml (default: config/haru.yaml).",
+)
+@click.option("--agent", "agent_name", default=None, help="Agent name from configuration.")
+def run(prompt: str, config_path: Path | None, agent_name: str | None) -> None:
+    """Run a single prompt and print the answer."""
+    try:
+        config = load_config(config_path)
+        configure_telemetry(config.observability)
+        prompts_root = config_path.parent / "prompts" if config_path is not None else None
+        answer = run_prompt(config, prompt, agent_name, prompts_root=prompts_root)
+    except HaruError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(answer)

haru/commands/session.py ADDED Viewed

@@ -0,0 +1,36 @@
+"""The ``haru session`` command group: inspect persisted conversations."""
+from pathlib import Path
+import click
+from haru.config import load_config
+from haru.errors import HaruError
+from haru.sessions.manager import list_sessions
+@click.group()
+def session() -> None:
+    """Manage persisted chat sessions."""
+@session.command(name="list")
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to haru.yaml (default: config/haru.yaml).",
+)
+def list_command(config_path: Path | None) -> None:
+    """List stored session ids."""
+    try:
+        config = load_config(config_path, with_includes=False) if config_path else None
+        session_ids = list_sessions(config)
+    except HaruError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if not session_ids:
+        click.echo("No stored sessions.")
+        return
+    for session_id in session_ids:
+        click.echo(session_id)

haru/commands/streaming.py ADDED Viewed

@@ -0,0 +1,34 @@
+"""Shared streaming helpers for the chat and run commands."""
+import asyncio
+from collections.abc import Callable
+from typing import Any
+from rich.console import Console
+_GUARDRAIL_STOPS = frozenset({"guardrail_intervened", "content_filtered"})
+def collect_response(agent: Any, prompt: str, on_text: Callable[[str], None]) -> Any:
+    """Stream a response, forwarding text chunks to ``on_text``.
+    Returns the final AgentResult (or None if the stream produced no result
+    event). Delegates the agent loop entirely to Strands.
+    """
+    async def _consume() -> Any:
+        result: Any = None
+        async for event in agent.stream_async(prompt):
+            if "data" in event:
+                on_text(event["data"])
+            if "result" in event:
+                result = event["result"]
+        return result
+    return asyncio.run(_consume())
+def surface_guardrail(result: Any, console: Console) -> None:
+    """Print a warning when the response was blocked or redacted by guardrails."""
+    if result is not None and getattr(result, "stop_reason", None) in _GUARDRAIL_STOPS:
+        console.print("[bold yellow]Guardrail intervened: the response was blocked or redacted.[/]")

haru/config/__init__.py ADDED Viewed

@@ -0,0 +1,6 @@
+"""Declarative YAML configuration loading for haru-cli."""
+from haru.config.loader import load_config, load_includes, resolve_env
+from haru.config.schema import HaruConfig
+__all__ = ["HaruConfig", "load_config", "load_includes", "resolve_env"]

haru/config/loader.py ADDED Viewed

@@ -0,0 +1,163 @@
+"""Load and validate layered YAML configuration.
+The loader enforces three invariants before any value reaches typed models:
+1. No inline secrets: keys named ``secret``, ``password``, or ``token`` must
+   hold environment references (``${env:VAR}`` or ``${VAR}``), never values.
+2. Environment references resolve at load time; a missing variable fails fast.
+3. Every document validates into the frozen schema, rejecting unknown keys.
+"""
+import os
+import re
+from pathlib import Path
+from typing import Any
+import yaml
+from pydantic import BaseModel, ValidationError
+from haru.config.schema import (
+    AgentsConfig,
+    GuardrailsFile,
+    HaruConfig,
+    LoggingFile,
+    MCPConfig,
+    ModelsConfig,
+)
+from haru.errors import ConfigError
+DEFAULT_CONFIG_PATH = Path("config") / "haru.yaml"
+_ENV_PATTERN = re.compile(r"\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}|\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+_ENV_REFERENCE = re.compile(r"^\$\{(?:env:)?[A-Za-z_][A-Za-z0-9_]*\}$")
+_SECRET_KEY_NAMES = frozenset({"secret", "password", "token"})
+def resolve_env(value: str) -> str:
+    """Expand ``${env:VAR}`` and ``${VAR}`` references from the environment.
+    Raises ConfigError if a referenced variable is not set.
+    """
+    def _replace(match: re.Match[str]) -> str:
+        name = match.group(1) or match.group(2)
+        resolved = os.environ.get(name)
+        if resolved is None:
+            raise ConfigError(f"Environment variable {name!r} referenced in configuration is unset")
+        return resolved
+    return _ENV_PATTERN.sub(_replace, value)
+def load_config(path: Path | None = None, *, with_includes: bool = True) -> HaruConfig:
+    """Load the full configuration from ``path`` (default ``config/haru.yaml``).
+    Parses the base document, then resolves every declared include relative to
+    the base file's directory. Pass ``with_includes=False`` to load only the
+    base document (commands that need just the ``app``/``auth`` sections).
+    Raises ConfigError on any missing file, malformed YAML, inline secret,
+    unset environment reference, or schema violation.
+    """
+    config_path = path if path is not None else DEFAULT_CONFIG_PATH
+    base = _validate(HaruConfig, _load_yaml(config_path), config_path)
+    if not with_includes:
+        return base
+    config = load_includes(base, config_path.parent)
+    _check_cross_references(config)
+    return config
+def load_includes(base: HaruConfig, root: Path) -> HaruConfig:
+    """Return ``base`` with every declared include file loaded and validated.
+    Include paths are resolved relative to ``root``. Raises ConfigError with
+    the offending path when an include is missing or invalid.
+    """
+    includes = base.includes
+    if includes is None:
+        return base
+    updates: dict[str, Any] = {}
+    if includes.models is not None:
+        source = root / includes.models
+        updates["models"] = _validate(ModelsConfig, _load_yaml(source), source)
+    if includes.agents is not None:
+        source = root / includes.agents
+        updates["agents"] = _validate(AgentsConfig, _load_yaml(source), source)
+    if includes.mcp is not None:
+        source = root / includes.mcp
+        updates["mcp"] = _validate(MCPConfig, _load_yaml(source), source)
+    if includes.guardrails is not None:
+        source = root / includes.guardrails
+        updates["guardrails"] = _validate(GuardrailsFile, _load_yaml(source), source).guardrails
+    if includes.logging is not None:
+        source = root / includes.logging
+        logging_file = _validate(LoggingFile, _load_yaml(source), source)
+        updates["logging"] = logging_file.logging
+        updates["observability"] = logging_file.observability
+    return base.model_copy(update=updates)
+def _load_yaml(path: Path) -> dict[str, Any]:
+    """Read a YAML mapping, reject inline secrets, and resolve env references."""
+    if not path.is_file():
+        raise ConfigError(f"Missing configuration file: {path}")
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"Malformed YAML in {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"Top-level YAML in {path} must be a mapping")
+    _reject_inline_secrets(data, source=path)
+    resolved: dict[str, Any] = _resolve_tree(data)
+    return resolved
+def _resolve_tree(node: Any) -> Any:
+    """Recursively expand environment references in every string value."""
+    if isinstance(node, str):
+        return resolve_env(node)
+    if isinstance(node, dict):
+        return {key: _resolve_tree(value) for key, value in node.items()}
+    if isinstance(node, list):
+        return [_resolve_tree(item) for item in node]
+    return node
+def _reject_inline_secrets(node: Any, *, source: Path, key_path: str = "") -> None:
+    """Fail if a secret-named key holds anything but an environment reference."""
+    if isinstance(node, dict):
+        for key, value in node.items():
+            child = f"{key_path}.{key}" if key_path else str(key)
+            if str(key).lower() in _SECRET_KEY_NAMES and not (
+                isinstance(value, str) and _ENV_REFERENCE.match(value)
+            ):
+                raise ConfigError(
+                    f"Inline secret at {child!r} in {source}: use an environment"
+                    " reference such as ${env:VAR} instead"
+                )
+            _reject_inline_secrets(value, source=source, key_path=child)
+    elif isinstance(node, list):
+        for index, item in enumerate(node):
+            _reject_inline_secrets(item, source=source, key_path=f"{key_path}[{index}]")
+def _validate[ModelT: BaseModel](model: type[ModelT], data: dict[str, Any], source: Path) -> ModelT:
+    """Validate ``data`` into ``model``, converting pydantic errors to ConfigError."""
+    try:
+        return model.model_validate(data)
+    except ValidationError as exc:
+        raise ConfigError(f"Invalid configuration in {source}: {exc}") from exc
+def _check_cross_references(config: HaruConfig) -> None:
+    """Validate references that span include files (agents -> models/MCP)."""
+    if config.agents is None:
+        return
+    for name, agent in config.agents.agents.items():
+        if config.models is not None and agent.model not in config.models.models:
+            raise ConfigError(f"Agent {name!r} references unknown model {agent.model!r}")
+        if config.mcp is not None:
+            for server in agent.mcp_servers:
+                if server not in config.mcp.mcp_servers:
+                    raise ConfigError(f"Agent {name!r} references unknown MCP server {server!r}")