haru-cli 0.1.0__py3-none-any.whl

haru/__init__.py

@@ -0,0 +1 @@
+"""haru: a governed CLI for Amazon Bedrock agents built on the Strands Agents SDK."""

haru/__main__.py

@@ -0,0 +1,12 @@
+"""Module entry point for ``python -m haru`` and the ``haru`` console script."""
+
+from haru.cli import cli
+
+
+def main() -> None:
+    """Run the haru CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

haru/agents/__init__.py

@@ -0,0 +1,18 @@
+"""Agent factories and multi-agent orchestration."""
+
+from haru.agents.factory import build_agent, resolve_agent_parts
+from haru.agents.orchestration import (
+    build_graph,
+    build_supervisor,
+    build_swarm,
+    run_orchestration,
+)
+
+__all__ = [
+    "build_agent",
+    "build_graph",
+    "build_supervisor",
+    "build_swarm",
+    "resolve_agent_parts",
+    "run_orchestration",
+]

haru/agents/factory.py

@@ -0,0 +1,76 @@
+"""Strands agent factories built from typed configuration.
+
+Factories return fully-wired Strands agents: model, steering prompt, built-in
+tools, and MCP tools. Multi-agent orchestration composes these in
+``haru.agents.orchestration``.
+"""
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import boto3
+from strands import Agent
+from strands.models import BedrockModel
+from strands.session.session_manager import SessionManager
+from strands.tools.mcp import MCPClient
+
+from haru.config.schema import HaruConfig
+from haru.errors import ConfigError
+from haru.models.bedrock import build_model, get_model_config
+from haru.steering.prompts import DEFAULT_PROMPTS_ROOT, load_prompts, resolve_prompt
+from haru.tools.mcp import collect_tools
+
+
+def build_agent(  # noqa: PLR0913 - keyword-only wiring points, all optional
+    config: HaruConfig,
+    agent_name: str | None,
+    session: boto3.Session,
+    *,
+    prompts_root: Path | None = None,
+    mcp_clients: Mapping[str, MCPClient] | None = None,
+    session_manager: SessionManager | None = None,
+) -> Agent:
+    """Build the named agent from configuration (default model when unnamed).
+
+    Raises ConfigError for unknown agents, prompt references, or tools.
+    """
+    if agent_name is None:
+        model = build_model(get_model_config(config), session, guardrails=config.guardrails)
+        return Agent(model=model, session_manager=session_manager)
+    model, system_prompt, tools = resolve_agent_parts(
+        config, agent_name, session, prompts_root=prompts_root, mcp_clients=mcp_clients
+    )
+    return Agent(
+        model=model,
+        system_prompt=system_prompt,
+        tools=tools,
+        name=agent_name,
+        session_manager=session_manager,
+    )
+
+
+def resolve_agent_parts(
+    config: HaruConfig,
+    agent_name: str,
+    session: boto3.Session,
+    *,
+    prompts_root: Path | None = None,
+    mcp_clients: Mapping[str, MCPClient] | None = None,
+) -> tuple[BedrockModel, str | None, list[Any]]:
+    """Resolve an agent's model, steering prompt, and tool list from config."""
+    if config.agents is None or agent_name not in config.agents.agents:
+        available = ", ".join(sorted(config.agents.agents)) if config.agents else "none"
+        raise ConfigError(f"Unknown agent {agent_name!r}; configured agents: {available}")
+    agent_cfg = config.agents.agents[agent_name]
+    model = build_model(
+        get_model_config(config, agent_cfg.model), session, guardrails=config.guardrails
+    )
+
+    system_prompt: str | None = None
+    if agent_cfg.system_prompt_ref is not None:
+        root = prompts_root if prompts_root is not None else DEFAULT_PROMPTS_ROOT
+        system_prompt = resolve_prompt(agent_cfg.system_prompt_ref, load_prompts(root))
+
+    tools = collect_tools(agent_cfg, None, mcp_clients or {}, mcp_cfg=config.mcp)
+    return model, system_prompt, tools

haru/agents/orchestration.py

@@ -0,0 +1,169 @@
+"""Multi-agent orchestration: supervisor (agents-as-tools), swarm, and graph.
+
+Each pattern is wired from the ``orchestration`` section of the agents
+configuration; the agent loop, handoffs, and graph execution are delegated
+entirely to Strands.
+"""
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import boto3
+from strands import Agent, tool
+from strands.multiagent import GraphBuilder, Swarm
+from strands.multiagent.graph import Graph
+from strands.tools.mcp import MCPClient
+
+from haru.agents.factory import build_agent, resolve_agent_parts
+from haru.auth.session import build_boto3_session
+from haru.config.schema import AgentsConfig, HaruConfig, OrchestrationConfig
+from haru.errors import ConfigError
+
+SUPERVISOR_AGENT_NAME = "supervisor"
+
+
+def build_supervisor(
+    config: HaruConfig,
+    session: boto3.Session,
+    *,
+    prompts_root: Path | None = None,
+    mcp_clients: Mapping[str, MCPClient] | None = None,
+) -> Agent:
+    """Build the supervisor agent with every other agent exposed as a tool."""
+    agents_cfg = _require_agents(config)
+    if SUPERVISOR_AGENT_NAME not in agents_cfg.agents:
+        raise ConfigError(
+            f"Supervisor orchestration requires an agent named {SUPERVISOR_AGENT_NAME!r}"
+        )
+    model, system_prompt, tools = resolve_agent_parts(
+        config, SUPERVISOR_AGENT_NAME, session, prompts_root=prompts_root, mcp_clients=mcp_clients
+    )
+    worker_tools = [
+        _agent_as_tool(
+            name,
+            build_agent(config, name, session, prompts_root=prompts_root, mcp_clients=mcp_clients),
+        )
+        for name in sorted(agents_cfg.agents)
+        if name != SUPERVISOR_AGENT_NAME
+    ]
+    return Agent(
+        model=model,
+        system_prompt=system_prompt,
+        tools=[*tools, *worker_tools],
+        name=SUPERVISOR_AGENT_NAME,
+    )
+
+
+def build_swarm(
+    config: HaruConfig,
+    session: boto3.Session,
+    *,
+    prompts_root: Path | None = None,
+    mcp_clients: Mapping[str, MCPClient] | None = None,
+) -> Swarm:
+    """Build a Swarm over the configured member agents."""
+    orchestration = _require_orchestration(config)
+    if orchestration.swarm is None:
+        raise ConfigError("Swarm orchestration requested but no swarm section is configured")
+    members = [
+        build_agent(config, name, session, prompts_root=prompts_root, mcp_clients=mcp_clients)
+        for name in orchestration.swarm.members
+    ]
+    return Swarm(
+        members,
+        max_handoffs=orchestration.swarm.max_handoffs,
+        execution_timeout=float(orchestration.swarm.execution_timeout_seconds),
+    )
+
+
+def build_graph(
+    config: HaruConfig,
+    session: boto3.Session,
+    *,
+    prompts_root: Path | None = None,
+    mcp_clients: Mapping[str, MCPClient] | None = None,
+) -> Graph:
+    """Build a Graph from the configured nodes and edges via GraphBuilder."""
+    orchestration = _require_orchestration(config)
+    if orchestration.graph is None:
+        raise ConfigError("Graph orchestration requested but no graph section is configured")
+    builder = GraphBuilder()
+    for node in orchestration.graph.nodes:
+        builder.add_node(
+            build_agent(
+                config, node.agent, session, prompts_root=prompts_root, mcp_clients=mcp_clients
+            ),
+            node.id,
+        )
+    for edge in orchestration.graph.edges:
+        builder.add_edge(edge.source, edge.target)
+    return builder.build()
+
+
+def run_orchestration(  # noqa: PLR0913 - three keyword-only injection points for tests/callers
+    config: HaruConfig,
+    prompt: str,
+    pattern: str | None = None,
+    *,
+    session: boto3.Session | None = None,
+    prompts_root: Path | None = None,
+    mcp_clients: Mapping[str, MCPClient] | None = None,
+) -> str:
+    """Run ``prompt`` through the requested (or default) orchestration pattern."""
+    orchestration = _require_agents(config).orchestration
+    selected = pattern if pattern is not None else _default_pattern(orchestration)
+    if session is None:
+        session = build_boto3_session(config.auth)
+
+    if selected == "supervisor":
+        supervisor = build_supervisor(
+            config, session, prompts_root=prompts_root, mcp_clients=mcp_clients
+        )
+        return str(supervisor(prompt))
+    if selected == "swarm":
+        swarm = build_swarm(config, session, prompts_root=prompts_root, mcp_clients=mcp_clients)
+        return _final_text(swarm(prompt))
+    if selected == "graph":
+        graph = build_graph(config, session, prompts_root=prompts_root, mcp_clients=mcp_clients)
+        return _final_text(graph(prompt))
+    raise ConfigError(f"Unknown orchestration pattern {selected!r}")
+
+
+def _default_pattern(orchestration: OrchestrationConfig | None) -> str:
+    return orchestration.default_pattern if orchestration is not None else "supervisor"
+
+
+def _agent_as_tool(name: str, agent: Agent) -> Any:
+    """Expose ``agent`` as a tool the supervisor can delegate tasks to."""
+
+    @tool(name=name, description=f"Delegate a task to the {name} specialist agent.")
+    def delegate(task: str) -> str:
+        """Send a task to the specialist agent and return its answer."""
+        return str(agent(task))
+
+    return delegate
+
+
+def _final_text(result: Any) -> str:
+    """Extract the final node's text from a swarm or graph result."""
+    order = getattr(result, "node_history", None) or getattr(result, "execution_order", None)
+    if order:
+        node_id = getattr(order[-1], "node_id", order[-1])
+        node_result = result.results.get(node_id)
+        if node_result is not None:
+            return str(node_result.result)
+    return "\n".join(str(node.result) for node in result.results.values())
+
+
+def _require_agents(config: HaruConfig) -> AgentsConfig:
+    if config.agents is None:
+        raise ConfigError("Orchestration requires an agents section in configuration")
+    return config.agents
+
+
+def _require_orchestration(config: HaruConfig) -> OrchestrationConfig:
+    orchestration = _require_agents(config).orchestration
+    if orchestration is None:
+        raise ConfigError("No orchestration section configured")
+    return orchestration

haru/auth/__init__.py

@@ -0,0 +1,14 @@
+"""IAM Identity Center authentication: PKCE login, token cache, boto3 sessions."""
+
+from haru.auth.cache import read_token_cache, write_token_cache
+from haru.auth.pkce import generate_pkce_pair
+from haru.auth.session import build_boto3_session
+from haru.auth.sso import run_login
+
+__all__ = [
+    "build_boto3_session",
+    "generate_pkce_pair",
+    "read_token_cache",
+    "run_login",
+    "write_token_cache",
+]

haru/auth/cache.py

@@ -0,0 +1,82 @@
+"""Botocore-compatible SSO token cache under ``~/.aws/sso/cache``.
+
+The cache file name is the SHA-1 of the start URL, and the JSON schema matches
+what botocore's ``SSOTokenProvider`` reads, so boto3 tooling can consume and
+refresh the same cache. Files are written with 0600 permissions.
+"""
+
+import hashlib
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+
+from haru.auth.sso import ClientRegistration, SsoToken
+from haru.errors import AuthError
+
+_DEFAULT_CACHE_DIR = Path("~") / ".aws" / "sso" / "cache"
+_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def cache_path(start_url: str, cache_dir: Path | None = None) -> Path:
+    """Return the cache file path for ``start_url`` (SHA-1 hex name, .json)."""
+    directory = cache_dir if cache_dir is not None else _DEFAULT_CACHE_DIR.expanduser()
+    digest = hashlib.sha1(start_url.encode("utf-8"), usedforsecurity=False).hexdigest()
+    return directory / f"{digest}.json"
+
+
+def write_token_cache(
+    token: SsoToken, start_url: str, region: str, cache_dir: Path | None = None
+) -> Path:
+    """Write ``token`` to the botocore-compatible cache and return the path."""
+    path = cache_path(start_url, cache_dir)
+    payload: dict[str, str] = {
+        "startUrl": start_url,
+        "region": region,
+        "accessToken": token.access_token,
+        "expiresAt": _format_timestamp(token.expires_at),
+        "clientId": token.registration.client_id,
+        "clientSecret": token.registration.client_secret,
+        "registrationExpiresAt": _format_timestamp(token.registration.expires_at),
+    }
+    if token.refresh_token is not None:
+        payload["refreshToken"] = token.refresh_token
+
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle)
+    path.chmod(0o600)
+    return path
+
+
+def read_token_cache(start_url: str, cache_dir: Path | None = None) -> SsoToken | None:
+    """Read the cached token for ``start_url``; return None when absent."""
+    path = cache_path(start_url, cache_dir)
+    if not path.is_file():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        registration = ClientRegistration(
+            client_id=payload["clientId"],
+            client_secret=payload["clientSecret"],
+            expires_at=_parse_timestamp(payload["registrationExpiresAt"]),
+        )
+        return SsoToken(
+            access_token=payload["accessToken"],
+            refresh_token=payload.get("refreshToken"),
+            expires_at=_parse_timestamp(payload["expiresAt"]),
+            registration=registration,
+        )
+    except (json.JSONDecodeError, KeyError, ValueError) as exc:
+        raise AuthError(f"Corrupt SSO token cache at {path}; run 'haru login'") from exc
+
+
+def _format_timestamp(value: datetime) -> str:
+    """Format a datetime as the UTC timestamp string botocore expects."""
+    return value.astimezone(UTC).strftime(_TIMESTAMP_FORMAT)
+
+
+def _parse_timestamp(value: str) -> datetime:
+    """Parse a botocore UTC timestamp string."""
+    return datetime.strptime(value, _TIMESTAMP_FORMAT).replace(tzinfo=UTC)

haru/auth/pkce.py

@@ -0,0 +1,21 @@
+"""RFC 7636 PKCE helpers for the IAM Identity Center login flow."""
+
+import base64
+import hashlib
+import secrets
+
+
+def generate_pkce_pair() -> tuple[str, str]:
+    """Return a ``(code_verifier, code_challenge)`` pair using the S256 method.
+
+    The verifier is 32 random bytes encoded as unpadded URL-safe base64; the
+    challenge is the unpadded URL-safe base64 SHA-256 of the verifier.
+    """
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode("ascii")
+    return verifier, code_challenge_from(verifier)
+
+
+def code_challenge_from(verifier: str) -> str:
+    """Derive the S256 code challenge for ``verifier`` (RFC 7636, section 4.2)."""
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")

haru/auth/session.py

@@ -0,0 +1,95 @@
+"""Construct boto3 sessions from the cached SSO token, refreshing when needed."""
+
+import os
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import boto3
+from botocore.exceptions import (
+    ClientError,
+    SSOTokenLoadError,
+    TokenRetrievalError,
+    UnauthorizedSSOTokenError,
+)
+
+from haru.auth.cache import read_token_cache, write_token_cache
+from haru.auth.sso import SsoToken
+from haru.config.schema import AuthConfig
+from haru.errors import AuthExpiredError, ConfigError
+
+_REFRESH_WINDOW = timedelta(minutes=15)
+_RELOGIN_HINT = "run 'haru login'"
+
+
+def build_boto3_session(
+    config: AuthConfig,
+    *,
+    oidc: Any | None = None,
+    sso_client: Any | None = None,
+    cache_dir: Path | None = None,
+) -> boto3.Session:
+    """Build a boto3 session with role credentials from the cached SSO token.
+
+    Refreshes the access token via the ``refresh_token`` grant when it is
+    within the refresh window. Raises AuthExpiredError whenever a fresh
+    interactive login is required.
+    """
+    sso = config.sso
+    token = read_token_cache(sso.start_url, cache_dir=cache_dir)
+    if token is None:
+        raise AuthExpiredError(f"No cached SSO token; {_RELOGIN_HINT}")
+    if token.expires_at <= datetime.now(UTC) + _REFRESH_WINDOW:
+        token = _refresh_token(config, token, oidc=oidc, cache_dir=cache_dir)
+
+    account_id = os.environ.get(sso.account_id_env)
+    if account_id is None:
+        raise ConfigError(
+            f"Environment variable {sso.account_id_env!r} must hold the target AWS account id"
+        )
+    if sso_client is None:
+        sso_client = boto3.Session().client("sso", region_name=sso.sso_region)
+    try:
+        response = sso_client.get_role_credentials(
+            roleName=sso.role_name, accountId=account_id, accessToken=token.access_token
+        )
+    except (ClientError, SSOTokenLoadError, UnauthorizedSSOTokenError, TokenRetrievalError) as exc:
+        raise AuthExpiredError(f"SSO credentials rejected; {_RELOGIN_HINT}") from exc
+
+    credentials = response["roleCredentials"]
+    return boto3.Session(
+        aws_access_key_id=credentials["accessKeyId"],
+        aws_secret_access_key=credentials["secretAccessKey"],
+        aws_session_token=credentials["sessionToken"],
+        region_name=config.bedrock_region,
+    )
+
+
+def _refresh_token(
+    config: AuthConfig, token: SsoToken, *, oidc: Any | None, cache_dir: Path | None
+) -> SsoToken:
+    """Refresh an expiring token via the ``refresh_token`` grant and re-cache it."""
+    sso = config.sso
+    now = datetime.now(UTC)
+    if token.refresh_token is None or token.registration.expires_at <= now:
+        raise AuthExpiredError(f"SSO token expired and cannot be refreshed; {_RELOGIN_HINT}")
+    if oidc is None:
+        oidc = boto3.Session().client("sso-oidc", region_name=sso.sso_region)
+    try:
+        response = oidc.create_token(
+            clientId=token.registration.client_id,
+            clientSecret=token.registration.client_secret,
+            grantType="refresh_token",
+            refreshToken=token.refresh_token,
+        )
+    except ClientError as exc:
+        raise AuthExpiredError(f"SSO token refresh failed; {_RELOGIN_HINT}") from exc
+
+    refreshed = SsoToken(
+        access_token=response["accessToken"],
+        refresh_token=response.get("refreshToken", token.refresh_token),
+        expires_at=now + timedelta(seconds=response["expiresIn"]),
+        registration=token.registration,
+    )
+    write_token_cache(refreshed, sso.start_url, sso.sso_region, cache_dir=cache_dir)
+    return refreshed