agentforge-a2a 0.2.1__py3-none-any.whl

agentforge_a2a/__init__.py

@@ -0,0 +1,58 @@
+"""`agentforge-a2a` — A2A protocol support for AgentForge (feat-014).
+
+Public surface:
+
+- `agent_call(target, payload, *, peers, ...)` — outgoing A2A
+  client.
+- `discover_peer(peer)` — probe a peer's `/a2a/v1/info`.
+- `A2APeer` — per-peer config + runner.
+- `A2AServer(agent, ..., auth, endpoints)` — FastAPI server
+  exposing this agent as an A2A peer.
+- `A2ABridge.from_config(config, ...)` — orchestrator that
+  wires both halves from a config dict.
+- `BearerAuth` / `MutualTLSAuth` — client-side credential
+  builders. (Server-side bearer validation uses the canonical
+  `agentforge_core.contracts.auth.AuthPolicy`.)
+- `A2APeerInfo`, `A2AEndpointDescriptor` — discovery wire
+  shapes returned by `/a2a/v1/info`.
+"""
+
+from __future__ import annotations
+
+from agentforge_a2a.auth import BearerAuth, ClientAuth, MutualTLSAuth, build_outgoing_auth
+from agentforge_a2a.bridge import A2ABridge
+from agentforge_a2a.client import A2APeer, agent_call, agent_call_stream, discover_peer
+from agentforge_a2a.config import A2AConfig
+from agentforge_a2a.server import A2AServer
+from agentforge_a2a.values import (
+    A2AChunk,
+    A2AChunkKind,
+    A2AEndpointConfig,
+    A2AEndpointDescriptor,
+    A2AExposeConfig,
+    A2APeerConfig,
+    A2APeerInfo,
+    A2AResponse,
+)
+
+__all__ = [
+    "A2ABridge",
+    "A2AChunk",
+    "A2AChunkKind",
+    "A2AConfig",
+    "A2AEndpointConfig",
+    "A2AEndpointDescriptor",
+    "A2AExposeConfig",
+    "A2APeer",
+    "A2APeerConfig",
+    "A2APeerInfo",
+    "A2AResponse",
+    "A2AServer",
+    "BearerAuth",
+    "ClientAuth",
+    "MutualTLSAuth",
+    "agent_call",
+    "agent_call_stream",
+    "build_outgoing_auth",
+    "discover_peer",
+]

agentforge_a2a/_inmem_runner.py

@@ -0,0 +1,163 @@
+"""In-memory fakes implementing the A2A runner protocols (feat-014).
+
+`FakeA2AClientRunner` lets unit + integration tests run without
+spinning up an HTTP server. It records every call for later
+assertion and returns scripted responses.
+
+`FakeA2AServerRunner` is a tiny placeholder for the server-side
+runner — `A2AServer.serve()` against this runner becomes a
+no-op suitable for tests.
+
+Lives in `src/` (not `tests/`) so external packages can import
+the fakes for their own integration tests.
+"""
+
+from __future__ import annotations
+
+import ssl
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class _Call:
+    url: str
+    headers: dict[str, str]
+    json: dict[str, Any] | None
+    ssl_context: ssl.SSLContext | None
+    timeout_s: float
+
+
+class FakeA2AClientRunner:
+    """Records POSTs / GETs / streams and returns canned data."""
+
+    def __init__(
+        self,
+        *,
+        response: dict[str, Any] | None = None,
+        get_response: dict[str, Any] | None = None,
+        responses_stream: list[dict[str, Any]] | None = None,
+    ) -> None:
+        self._response: dict[str, Any] = response if response is not None else {}
+        self._get_response: dict[str, Any] | None = get_response
+        self._stream: list[dict[str, Any]] = list(responses_stream or [])
+        self._error: Exception | None = None
+        self.calls: list[_Call] = []
+        self.get_calls: list[_Call] = []
+        self.stream_calls: list[_Call] = []
+        self.closed = False
+
+    @classmethod
+    def with_response(cls, response: dict[str, Any]) -> FakeA2AClientRunner:
+        return cls(response=response)
+
+    def set_response(self, response: dict[str, Any]) -> None:
+        self._response = response
+
+    def set_get_response(self, response: dict[str, Any]) -> None:
+        self._get_response = response
+
+    def set_stream(self, chunks: list[dict[str, Any]]) -> None:
+        self._stream = list(chunks)
+
+    def set_error(self, error: Exception) -> None:
+        """Next `post()` (or `get()` / `post_stream()`) raises this."""
+        self._error = error
+
+    async def post(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any],
+        ssl_context: ssl.SSLContext | None,
+        timeout_s: float,
+    ) -> dict[str, Any]:
+        self.calls.append(
+            _Call(
+                url=url,
+                headers=dict(headers),
+                json=dict(json),
+                ssl_context=ssl_context,
+                timeout_s=timeout_s,
+            )
+        )
+        if self._error is not None:
+            err, self._error = self._error, None
+            raise err
+        return dict(self._response)
+
+    async def get(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        ssl_context: ssl.SSLContext | None,
+        timeout_s: float,
+    ) -> dict[str, Any]:
+        self.get_calls.append(
+            _Call(
+                url=url,
+                headers=dict(headers),
+                json=None,
+                ssl_context=ssl_context,
+                timeout_s=timeout_s,
+            )
+        )
+        if self._error is not None:
+            err, self._error = self._error, None
+            raise err
+        body = self._get_response if self._get_response is not None else self._response
+        return dict(body)
+
+    async def post_stream(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any],
+        ssl_context: ssl.SSLContext | None,
+        timeout_s: float,
+    ) -> AsyncIterator[dict[str, Any]]:
+        self.stream_calls.append(
+            _Call(
+                url=url,
+                headers=dict(headers),
+                json=dict(json),
+                ssl_context=ssl_context,
+                timeout_s=timeout_s,
+            )
+        )
+        if self._error is not None:
+            err, self._error = self._error, None
+            raise err
+        for chunk in self._stream:
+            yield dict(chunk)
+
+    async def close(self) -> None:
+        self.closed = True
+
+
+@dataclass
+class FakeA2AServerRunner:
+    """No-op server runner suitable for tests + the inline bridge."""
+
+    serving: bool = False
+    stop_called: bool = False
+    _events: list[str] = field(default_factory=list)
+
+    async def serve(self) -> None:
+        self.serving = True
+        self._events.append("serve")
+
+    async def stop(self) -> None:
+        self.serving = False
+        self.stop_called = True
+        self._events.append("stop")
+
+
+__all__ = [
+    "FakeA2AClientRunner",
+    "FakeA2AServerRunner",
+]

agentforge_a2a/_runner.py

@@ -0,0 +1,242 @@
+"""Internal A2A runner protocols (feat-014).
+
+`A2AClientRunner` is the thin slice of httpx we depend on for
+outgoing calls; `A2AServerRunner` wraps the uvicorn lifecycle
+for the embedded server. Tests inject fakes so the unit suite
+doesn't need a real network socket.
+
+Production runners (`_HTTPXClientRunner`, `_UvicornServerRunner`)
+are exercised by the `@pytest.mark.live` integration tests in
+`tests/integration/` (feat-014 v0.2 follow-up). Their bodies
+stay under ``# pragma: no cover`` because the unit suite uses
+the fakes in `_inmem_runner.py`; coverage of the real transport
+lives in the live job.
+"""
+
+from __future__ import annotations
+
+import ssl
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    import httpx
+    import uvicorn
+    from fastapi import FastAPI
+
+
+class A2AClientRunner(Protocol):
+    """Subset of `httpx.AsyncClient` we depend on for outgoing
+    A2A calls. Tests inject a fake; production builds a real
+    `httpx.AsyncClient` via `_HTTPXClientRunner`."""
+
+    async def post(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any],
+        ssl_context: ssl.SSLContext | None,
+        timeout_s: float,
+    ) -> dict[str, Any]: ...
+
+    async def get(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        ssl_context: ssl.SSLContext | None,
+        timeout_s: float,
+    ) -> dict[str, Any]: ...
+
+    def post_stream(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any],
+        ssl_context: ssl.SSLContext | None,
+        timeout_s: float,
+    ) -> AsyncIterator[dict[str, Any]]: ...
+
+    async def close(self) -> None: ...
+
+
+class A2AServerRunner(Protocol):
+    """Subset of `uvicorn.Server` we depend on. Tests inject a
+    fake; production builds a real uvicorn server via
+    `_UvicornServerRunner`."""
+
+    async def serve(self) -> None: ...
+
+    async def stop(self) -> None: ...
+
+
+_HTTP_UNAUTHORIZED = 401
+_HTTP_FORBIDDEN = 403
+_SSE_DATA_PREFIX = "data: "
+
+
+class _HTTPXClientRunner:  # pragma: no cover — exercised only with `-m live`
+    """Production `A2AClientRunner` — wraps `httpx.AsyncClient`.
+
+    The client is allocated lazily on the first call so
+    instantiation stays cheap and the constructor stays sync.
+    `close()` shuts the underlying httpx client down.
+    """
+
+    def __init__(self) -> None:
+        self._client: httpx.AsyncClient | None = None
+
+    def _ensure_client(self, ssl_context: ssl.SSLContext | None) -> httpx.AsyncClient:
+        if self._client is None:
+            import httpx  # noqa: PLC0415
+
+            verify: ssl.SSLContext | bool = ssl_context if ssl_context is not None else True
+            self._client = httpx.AsyncClient(verify=verify)
+        return self._client
+
+    async def post(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any],
+        ssl_context: ssl.SSLContext | None,
+        timeout_s: float,
+    ) -> dict[str, Any]:
+        from agentforge_core.production.exceptions import (  # noqa: PLC0415
+            A2AAuthError,
+            A2ACallError,
+        )
+
+        client = self._ensure_client(ssl_context)
+        response = await client.post(url, headers=headers, json=json, timeout=timeout_s)
+        if response.status_code in (_HTTP_UNAUTHORIZED, _HTTP_FORBIDDEN):
+            raise A2AAuthError(
+                f"a2a peer rejected credentials ({response.status_code}): {response.text!r}"
+            )
+        if response.status_code >= 400:  # noqa: PLR2004
+            raise A2ACallError(f"a2a peer returned HTTP {response.status_code}: {response.text!r}")
+        parsed: dict[str, Any] = response.json()
+        return parsed
+
+    async def get(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        ssl_context: ssl.SSLContext | None,
+        timeout_s: float,
+    ) -> dict[str, Any]:
+        from agentforge_core.production.exceptions import (  # noqa: PLC0415
+            A2AAuthError,
+            A2ACallError,
+        )
+
+        client = self._ensure_client(ssl_context)
+        response = await client.get(url, headers=headers, timeout=timeout_s)
+        if response.status_code in (_HTTP_UNAUTHORIZED, _HTTP_FORBIDDEN):
+            raise A2AAuthError(
+                f"a2a peer rejected credentials ({response.status_code}): {response.text!r}"
+            )
+        if response.status_code >= 400:  # noqa: PLR2004
+            raise A2ACallError(f"a2a peer returned HTTP {response.status_code}: {response.text!r}")
+        parsed: dict[str, Any] = response.json()
+        return parsed
+
+    async def post_stream(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any],
+        ssl_context: ssl.SSLContext | None,
+        timeout_s: float,
+    ) -> AsyncIterator[dict[str, Any]]:
+        import json as _json  # noqa: PLC0415
+
+        from agentforge_core.production.exceptions import (  # noqa: PLC0415
+            A2AAuthError,
+            A2ACallError,
+        )
+
+        client = self._ensure_client(ssl_context)
+        stream_headers = dict(headers)
+        stream_headers.setdefault("Accept", "text/event-stream")
+        async with client.stream(
+            "POST", url, headers=stream_headers, json=json, timeout=timeout_s
+        ) as response:
+            if response.status_code in (_HTTP_UNAUTHORIZED, _HTTP_FORBIDDEN):
+                await response.aread()
+                raise A2AAuthError(
+                    f"a2a peer rejected credentials ({response.status_code}): {response.text!r}"
+                )
+            if response.status_code >= 400:  # noqa: PLR2004
+                await response.aread()
+                raise A2ACallError(
+                    f"a2a peer returned HTTP {response.status_code}: {response.text!r}"
+                )
+            async for line in response.aiter_lines():
+                if not line or not line.startswith(_SSE_DATA_PREFIX):
+                    continue
+                payload = line[len(_SSE_DATA_PREFIX) :]
+                try:
+                    parsed: dict[str, Any] = _json.loads(payload)
+                except _json.JSONDecodeError as exc:
+                    raise A2ACallError(
+                        f"a2a peer streamed an unparseable SSE frame: {payload!r}"
+                    ) from exc
+                yield parsed
+
+    async def close(self) -> None:
+        if self._client is None:
+            return
+        client, self._client = self._client, None
+        await client.aclose()
+
+
+class _UvicornServerRunner:  # pragma: no cover — exercised only with `-m live`
+    """Production `A2AServerRunner` — wraps `uvicorn.Server`.
+
+    `serve()` blocks until either an external signal sets
+    `should_exit = True` or `stop()` is called from another
+    task. `stop()` is idempotent.
+    """
+
+    def __init__(
+        self,
+        app: FastAPI,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 8080,
+        log_level: str = "info",
+    ) -> None:
+        self._app = app
+        self._host = host
+        self._port = port
+        self._log_level = log_level
+        self._server: uvicorn.Server | None = None
+
+    async def serve(self) -> None:
+        import uvicorn  # noqa: PLC0415
+
+        config = uvicorn.Config(
+            self._app, host=self._host, port=self._port, log_level=self._log_level
+        )
+        self._server = uvicorn.Server(config)
+        try:
+            await self._server.serve()
+        finally:
+            self._server = None
+
+    async def stop(self) -> None:
+        if self._server is None:
+            return
+        self._server.should_exit = True
+
+
+__all__ = [
+    "A2AClientRunner",
+    "A2AServerRunner",
+]

agentforge_a2a/auth.py

@@ -0,0 +1,92 @@
+"""Client-side credential providers for A2A (feat-014).
+
+`agent_call` resolves per-peer auth config to one of the two
+built-in `ClientAuth` shapes:
+
+- `BearerAuth(token)` — attaches ``Authorization: Bearer
+  <token>`` to outgoing requests.
+- `MutualTLSAuth(cert_path, key_path)` — builds an
+  `ssl.SSLContext` the httpx client passes to the peer.
+
+`build_outgoing_auth(config)` accepts the dict form found in
+YAML (`{type: bearer, token: ...}` / `{type: mtls, cert: ...,
+key: ...}`) and returns the corresponding `ClientAuth`.
+"""
+
+from __future__ import annotations
+
+import ssl
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from agentforge_core.production.exceptions import ModuleError
+
+
+@dataclass(frozen=True)
+class ClientAuth:
+    """Resolved client-side credentials for an A2A peer.
+
+    `headers` is merged into the outgoing request headers;
+    `ssl_context` is passed to the httpx client when present.
+    """
+
+    headers: dict[str, str] = field(default_factory=dict)
+    ssl_context: ssl.SSLContext | None = None
+
+
+def BearerAuth(token: str) -> ClientAuth:  # noqa: N802 — factory-named like a class
+    """Bearer-token credentials. Returns a `ClientAuth` ready to
+    use with `agent_call`."""
+    return ClientAuth(headers={"Authorization": f"Bearer {token}"})
+
+
+def MutualTLSAuth(  # noqa: N802 — factory-named like a class
+    cert_path: str | Path,
+    key_path: str | Path,
+    *,
+    ca_path: str | Path | None = None,
+) -> ClientAuth:
+    """mTLS credentials. Builds an `ssl.SSLContext` loading the
+    client cert + key (and an optional CA bundle)."""
+    ctx = ssl.create_default_context(
+        purpose=ssl.Purpose.SERVER_AUTH,
+        cafile=str(ca_path) if ca_path is not None else None,
+    )
+    ctx.load_cert_chain(certfile=str(cert_path), keyfile=str(key_path))
+    return ClientAuth(ssl_context=ctx)
+
+
+def build_outgoing_auth(config: dict[str, Any]) -> ClientAuth:
+    """Resolve a per-peer auth dict to a `ClientAuth`.
+
+    Accepted shapes:
+      - ``{}`` — no auth.
+      - ``{type: "bearer", token: "..."}``.
+      - ``{type: "mtls", cert: "/path", key: "/path",
+            ca: "/path" (optional)}``.
+    """
+    if not config:
+        return ClientAuth()
+    auth_type = config.get("type", "")
+    if auth_type == "bearer":
+        token = config.get("token", "")
+        if not token:
+            raise ModuleError("bearer auth requires a non-empty 'token'")
+        return BearerAuth(token)
+    if auth_type == "mtls":
+        cert = config.get("cert", "")
+        key = config.get("key", "")
+        ca = config.get("ca")
+        if not cert or not key:
+            raise ModuleError("mtls auth requires both 'cert' and 'key' paths")
+        return MutualTLSAuth(cert, key, ca_path=ca)
+    raise ModuleError(f"unknown a2a auth type: {auth_type!r}")
+
+
+__all__ = [
+    "BearerAuth",
+    "ClientAuth",
+    "MutualTLSAuth",
+    "build_outgoing_auth",
+]

agentforge_a2a/bridge.py

@@ -0,0 +1,148 @@
+"""`A2ABridge` — orchestrates A2A clients + an optional server
+(feat-014).
+
+Loaded by feat-010's resolver from
+`modules.protocols[a2a].config:`. Mirrors `MCPBridge`'s shape:
+
+- `from_config(config_dict, *, agent, auth, client_runner,
+  server_runner)` builds peers + an optional server from a
+  validated `A2AConfig`.
+- `peers` is a dict of `{name -> A2APeer}` ready for
+  `agent_call(...)`.
+- `server` is an `A2AServer | None`; when present, `start()`
+  schedules it as an asyncio task and `close()` cancels.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import Any, ClassVar
+
+from agentforge.agent import Agent
+from agentforge_core.contracts.auth import AuthPolicy
+
+from agentforge_a2a._runner import A2AClientRunner, A2AServerRunner
+from agentforge_a2a.client import A2APeer, discover_peer
+from agentforge_a2a.config import A2AConfig
+from agentforge_a2a.server import A2AServer
+from agentforge_a2a.values import A2APeerInfo
+
+
+class A2ABridge:
+    """Top-level orchestrator for a2a clients + server.
+
+    The bridge does NOT own the `Agent` instance — callers pass
+    it explicitly when they want a server side. Without an
+    agent, `from_config` builds the client side only (peers
+    available; `server is None`).
+    """
+
+    config_schema: ClassVar[type[A2AConfig]] = A2AConfig
+    """Picked up by feat-012's `validate_module_configs` so
+    `agentforge config validate` enforces the A2A schema."""
+
+    def __init__(
+        self,
+        *,
+        peers: dict[str, A2APeer],
+        server: A2AServer | None = None,
+    ) -> None:
+        self._peers = dict(peers)
+        self._server = server
+        self._serve_task: asyncio.Task[None] | None = None
+        self._peer_info: dict[str, A2APeerInfo] = {}
+
+    @property
+    def peers(self) -> dict[str, A2APeer]:
+        return dict(self._peers)
+
+    @property
+    def server(self) -> A2AServer | None:
+        return self._server
+
+    @property
+    def peer_info(self) -> dict[str, A2APeerInfo]:
+        """Cached `A2APeerInfo` keyed by peer name (populated by
+        `discover_all()` — empty until then)."""
+        return dict(self._peer_info)
+
+    @classmethod
+    def from_config(
+        cls,
+        config: dict[str, Any],
+        *,
+        agent: Agent | None = None,
+        auth: AuthPolicy | None = None,
+        client_runner: A2AClientRunner,
+        server_runner: A2AServerRunner | None = None,
+    ) -> A2ABridge:
+        """Build a bridge from a validated A2A config dict.
+
+        Args:
+            config: Raw ``{peers: [...], expose: {...}}`` dict.
+                The chunk-5 schema (`A2AConfig`) validates this.
+            agent: Required when ``config.expose.enabled`` is
+                True. The server side wraps it.
+            auth: Required when ``config.expose.enabled`` is
+                True. The server validates incoming bearers
+                against this policy.
+            client_runner: Shared `A2AClientRunner` for all
+                peers. Pass a `FakeA2AClientRunner` in tests.
+            server_runner: Optional `A2AServerRunner` injected
+                into the server's lifecycle.
+        """
+        validated = A2AConfig.model_validate(config)
+        peers = {pc.name: A2APeer.from_config(pc, runner=client_runner) for pc in validated.peers}
+        server: A2AServer | None = None
+        if validated.expose is not None and validated.expose.enabled:
+            if agent is None or auth is None:
+                msg = (
+                    "A2A expose.enabled=True requires both an Agent and an "
+                    "AuthPolicy to be supplied to A2ABridge.from_config."
+                )
+                raise ValueError(msg)
+            server = A2AServer(
+                agent=agent,
+                auth=auth,
+                endpoints=[e.name for e in validated.expose.endpoints],
+                endpoint_descriptors=list(validated.expose.endpoints),
+                host=validated.expose.host,
+                port=validated.expose.port,
+                runner=server_runner,
+            )
+        return cls(peers=peers, server=server)
+
+    async def discover_all(self, *, timeout_s: float = 10.0) -> dict[str, A2APeerInfo]:
+        """Probe every configured peer's `/a2a/v1/info` endpoint
+        and cache the result on `self.peer_info`.
+
+        Re-callable — replaces the cached entry per peer. Caller-
+        driven: never invoked automatically by `start()`.
+        """
+        fresh: dict[str, A2APeerInfo] = {}
+        for name, peer in self._peers.items():
+            fresh[name] = await discover_peer(peer, timeout_s=timeout_s)
+        self._peer_info = fresh
+        return dict(self._peer_info)
+
+    async def start(self) -> None:
+        """Launch the server (if any) in the background. Idempotent."""
+        if self._server is None or self._serve_task is not None:
+            return
+        self._serve_task = asyncio.create_task(self._server.serve())
+
+    async def close(self) -> None:
+        """Stop the server (if running) and drain peers."""
+        if self._server is not None:
+            await self._server.stop()
+        if self._serve_task is not None and not self._serve_task.done():
+            self._serve_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._serve_task
+            self._serve_task = None
+        for peer in self._peers.values():
+            await peer.runner.close()
+
+
+__all__ = ["A2ABridge"]