webagent-protocol 0.2.0__py3-none-any.whl

wap/server/mcp_endpoint.py

@@ -0,0 +1,305 @@
+"""Serve a WAPServer's capabilities as a standard MCP server (streamable HTTP) at ``/mcp``.
+
+This is what makes WAP an *extension* of the Model Context Protocol rather than
+a competitor: the same ``@wap.action`` functions are exposed twice,
+
+* as WAP capabilities (signed envelopes, proof-of-work, SSE) at ``/wap/v1/interact``, and
+* as ordinary MCP tools at ``/mcp``, usable by any MCP client with no WAP code.
+
+The MCP endpoint keeps WAP's guarantees where MCP has room for them:
+
+* every successful ``tools/call`` result carries the business's Ed25519-signed
+  reply in ``_meta["io.webagent/signed_reply"]``, verifiable against the key in
+  ``/.well-known/wap.json``;
+* calls are rate-limited per client IP with the server's policy;
+* proof-of-work can be required (``mcp_require_pow``): the client passes
+  ``_meta["io.webagent/pow"] = {"seed", "nonce"}`` and a failed call returns a
+  fresh challenge in ``_meta["io.webagent/challenge"]``;
+* multi-turn state continues via ``_meta["io.webagent/session_id"]``.
+
+Installed with the ``server`` extra (``pip install "webagent-protocol[server]"``).
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit
+
+import mcp_types as types
+from mcp.server.lowlevel import Server
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+from mcp.server.transport_security import TransportSecuritySettings
+from mcp.shared.exceptions import MCPError
+
+from .. import __version__
+from ..spec.models import (
+    WAP_VERSION,
+    WELL_KNOWN_PATH,
+    AgentMessage,
+    ErrorCode,
+    Role,
+    authority_host,
+    mcp_annotation_hints,
+)
+from .admission import AdmissionRequest
+from .app import WAPProtocolError
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from .app import WAPServer
+
+EXTENSION_ID = "io.webagent/wap"
+META_PREFIX = "io.webagent/"
+META_SIGNED_REPLY = META_PREFIX + "signed_reply"
+META_SESSION_ID = META_PREFIX + "session_id"
+META_POW = META_PREFIX + "pow"
+META_IDEMPOTENCY_KEY = META_PREFIX + "idempotency_key"
+META_CHALLENGE = META_PREFIX + "challenge"
+META_ERROR = META_PREFIX + "error"
+META_MANIFEST = META_PREFIX + "manifest_url"
+MCP_SESSION_OWNER = "mcp"
+INVALID_PARAMS = -32602
+
+
+def _protocol_error_result(exc: WAPProtocolError) -> types.CallToolResult:
+    extra: dict[str, Any] = {}
+    details = dict(exc.details or {})
+    challenge = details.pop("challenge", None)
+    if challenge is not None:
+        extra[META_CHALLENGE] = challenge
+    if details:
+        extra[META_PREFIX + "details"] = details
+    if exc.retry_after is not None:
+        extra[META_PREFIX + "retry_after"] = exc.retry_after
+    message = exc.message
+    if exc.code is ErrorCode.POW_REQUIRED:
+        message = (
+            f"this tool requires proof-of-work: solve _meta['{META_CHALLENGE}'] and resend with "
+            f"_meta['{META_POW}'] = {{'seed': ..., 'nonce': ...}}"
+        )
+    return _error_result(exc.code.value, message, extra)
+
+
+def _error_result(code: str, message: str, extra_meta: dict[str, Any] | None = None) -> types.CallToolResult:
+    return types.CallToolResult(
+        content=[types.TextContent(type="text", text=f"[{code}] {message}")],
+        is_error=True,
+        meta={META_ERROR: {"code": code, "message": message}, **(extra_meta or {})},
+    )
+
+
+class MCPEndpoint:
+    """Bridges one :class:`WAPServer` onto an MCP ``Server`` served over streamable HTTP."""
+
+    def __init__(self, server: WAPServer, path: str = "/mcp") -> None:
+        self.wap = server
+        self.path = path
+        self.mcp = Server(
+            server.name,
+            version=__version__,
+            description=server.description or None,
+            instructions=(
+                f"Tools published by {server.name} ({server.domain}) via the WebAgent Protocol. "
+                f"Results are signed; verify _meta['{META_SIGNED_REPLY}'] against the public key at "
+                f"{server.base_url}{WELL_KNOWN_PATH}."
+            ),
+            on_list_tools=self._list_tools,
+            on_call_tool=self._call_tool,
+        )
+        # Declared as an MCP extension (SEP-2133) so clients can detect WAP support at initialization.
+        self.mcp.extensions[EXTENSION_ID] = self.extension_settings()
+        self._manager: StreamableHTTPSessionManager | None = None
+
+    def extension_settings(self) -> dict[str, Any]:
+        return {
+            "wap_version": WAP_VERSION,
+            "manifest_url": self.wap.base_url + WELL_KNOWN_PATH,
+            "public_key": self.wap.public_key,
+            "pow_required": self.require_pow,
+            "signed_results": True,
+            "conversation_policy": self.wap.conversation_policy.as_dict(),
+        }
+
+    # ------------------------------------------------------------------ MCP handlers
+
+    def tools(self) -> list[types.Tool]:
+        tools = []
+        for action in self.wap.actions.values():
+            cap = action.capability
+            output = cap.output_schema if cap.output_schema and cap.output_schema.get("type") == "object" else None
+            tools.append(
+                types.Tool(
+                    name=cap.id,
+                    title=cap.name,
+                    description=cap.description or cap.name,
+                    input_schema=cap.input_schema,
+                    output_schema=output,
+                    annotations=types.ToolAnnotations(title=cap.name, **mcp_annotation_hints(cap)),
+                    meta={META_PREFIX + "requires_auth": cap.requires_auth, META_PREFIX + "effects": cap.effects},
+                )
+            )
+        return tools
+
+    async def _list_tools(self, ctx: Any, params: Any) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=self.tools())
+
+    @property
+    def require_pow(self) -> bool:
+        configured = self.wap.mcp_require_pow
+        return self.wap.require_pow if configured is None else configured
+
+    async def _call_tool(self, ctx: Any, params: types.CallToolRequestParams) -> types.CallToolResult:
+        server = self.wap
+        if params.name not in server.actions:
+            raise MCPError(INVALID_PARAMS, f"unknown tool {params.name!r}", {"available": sorted(server.actions)})
+        request = getattr(ctx, "request", None)
+        ip = request.client.host if request is not None and getattr(request, "client", None) else None
+        headers = request.headers if request is not None else {}
+        meta: dict[str, Any] = dict(params.meta or {})
+        solution = meta.get(META_POW) if isinstance(meta.get(META_POW), dict) else {}
+
+        try:
+            await server.limit_ip(ip)
+            principal = await server.authenticate(headers.get("authorization"))
+            decision, _ = await server.admit(
+                AdmissionRequest(
+                    client_ip=ip,
+                    agent_key=None,
+                    principal=principal,
+                    capability_id=params.name,
+                    transport="mcp",
+                    headers=dict(headers),
+                ),
+                pow_seed=str(solution["seed"]) if "seed" in solution else None,
+                pow_nonce=str(solution["nonce"]) if "nonce" in solution else None,
+            )
+        except WAPProtocolError as exc:
+            return _protocol_error_result(exc)
+
+        session_id = str(meta.get(META_SESSION_ID) or "mcp-" + uuid.uuid4().hex)
+        idempotency_key = meta.get(META_IDEMPOTENCY_KEY)
+        message = AgentMessage(
+            session_id=session_id,
+            role=Role.USER_AGENT,
+            capability_id=params.name,
+            structured_data=dict(params.arguments or {}),
+            idempotency_key=str(idempotency_key) if idempotency_key else None,
+        )
+        # Per-session loop guard only: an IP may be shared by many unrelated MCP users.
+        turn = server.open_turn(
+            message,
+            owner_key=MCP_SESSION_OWNER,
+            principal_key=None,
+            client_ip=ip,
+            principal=principal,
+            tier=decision.tier,
+            conversation_policy=decision.conversation_policy,
+        )
+        try:
+            await turn.open()
+            if turn.replay is not None:
+                return self._result(turn.replay, session_id, replayed=True)
+            assert turn.ctx is not None
+            text: list[str] = []
+            data: dict[str, Any] = {}
+            async for chunk in server.dispatch(turn.ctx):
+                if isinstance(chunk, str):
+                    text.append(chunk)
+                else:
+                    data.update(chunk)
+            reply = await turn.complete("".join(text), data or None)
+        except WAPProtocolError as exc:
+            await turn.fail(exc)
+            return _protocol_error_result(exc)
+        finally:
+            await turn.close()
+        return self._result(reply, session_id)
+
+    def _result(self, reply: AgentMessage, session_id: str, *, replayed: bool = False) -> types.CallToolResult:
+        data = reply.structured_data or {}
+        content = [types.TextContent(type="text", text=reply.content or json.dumps(data))]
+        if data and reply.content:
+            content.append(types.TextContent(type="text", text=json.dumps(data, ensure_ascii=False)))
+        meta = {
+            META_SIGNED_REPLY: reply.model_dump(mode="json"),
+            META_SESSION_ID: session_id,
+            META_MANIFEST: self.wap.base_url + WELL_KNOWN_PATH,
+        }
+        if replayed:
+            meta[META_PREFIX + "idempotent_replay"] = True
+        return types.CallToolResult(content=content, structured_content=data or None, meta=meta)
+
+    # ------------------------------------------------------------------ ASGI
+
+    def security_settings(self) -> TransportSecuritySettings:
+        hosts = {self.wap.domain, authority_host(self.wap.domain)}
+        base = urlsplit(self.wap.base_url)
+        hosts.update({base.netloc, base.hostname or ""})
+        allowed = sorted(h for h in hosts if h)
+        allowed += [f"{authority_host(h)}:*" for h in allowed if ":" not in h]
+        return TransportSecuritySettings(
+            enable_dns_rebinding_protection=True,
+            allowed_hosts=sorted(set(allowed)),
+            allowed_origins=sorted({f"{base.scheme}://{base.netloc}", f"https://{self.wap.domain}"}),
+        )
+
+    @asynccontextmanager
+    async def running(self) -> AsyncIterator[None]:
+        """Run the MCP session manager; entered from the host application's lifespan."""
+        self.mcp.extensions[EXTENSION_ID] = self.extension_settings()  # pick up config changed after mount
+        manager = StreamableHTTPSessionManager(
+            app=self.mcp, json_response=True, stateless=True, security_settings=self.security_settings()
+        )
+        async with manager.run():
+            self._manager = manager
+            try:
+                yield
+            finally:
+                self._manager = None
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if self._manager is None:
+            body = b'{"error":"MCP endpoint is not running; start the app with its ASGI lifespan enabled"}'
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 503,
+                    "headers": [(b"content-type", b"application/json"), (b"content-length", str(len(body)).encode())],
+                }
+            )
+            await send({"type": "http.response.body", "body": body})
+            return
+        await self._manager.handle_request(scope, receive, send)
+
+
+def mount_mcp(app: FastAPI, server: WAPServer, path: str = "/mcp") -> MCPEndpoint:
+    """Add the MCP endpoint to ``app`` and hook its session manager into the app lifespan."""
+    endpoint = MCPEndpoint(server, path)
+    app.router.add_route(path, endpoint, methods=["GET", "POST", "DELETE"], include_in_schema=False)
+    original = app.router.lifespan_context
+
+    @asynccontextmanager
+    async def lifespan(asgi_app: Any) -> AsyncIterator[Any]:
+        async with endpoint.running():
+            async with original(asgi_app) as state:
+                yield state
+
+    app.router.lifespan_context = lifespan
+    return endpoint
+
+
+__all__ = [
+    "EXTENSION_ID",
+    "META_CHALLENGE",
+    "META_IDEMPOTENCY_KEY",
+    "META_POW",
+    "META_SESSION_ID",
+    "META_SIGNED_REPLY",
+    "MCPEndpoint",
+    "mount_mcp",
+]

wap/server/mcp_import.py

@@ -0,0 +1,122 @@
+"""Publish an existing MCP server's tools on the open web through WAP.
+
+If you already have an MCP server, one call makes its tools discoverable at
+``/.well-known/wap.json``, with signed replies, proof-of-work and rate limits::
+
+    from mcp.server.mcpserver import MCPServer
+    from wap.server import WAPServer
+
+    tools = MCPServer("inventory")
+
+    @tools.tool()
+    def check_stock(sku: str) -> dict: ...
+
+    wap = WAPServer(name="Acme", domain="acme.example", private_key=KEY)
+    wap.include_mcp(tools)          # imported when the app starts
+    app = wap.create_app()
+
+``source`` is anything the MCP SDK's ``Client`` accepts: an in-process server
+object, a streamable-HTTP URL, or ``StdioServerParameters`` for a subprocess.
+Installed with the ``server`` extra.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING, Any
+
+from mcp.client.client import Client
+
+from ..spec.models import Capability, ErrorCode
+from .app import ActionContext, ActionResult, WAPProtocolError
+
+if TYPE_CHECKING:
+    from .app import WAPServer
+
+_INVALID = re.compile(r"[^a-z0-9_.-]+")
+
+
+def capability_id_for(tool_name: str, prefix: str = "") -> str:
+    """Map an MCP tool name onto WAP's capability-id grammar (``^[a-z][a-z0-9_.-]{0,63}$``)."""
+    ident = _INVALID.sub("_", (prefix + tool_name).lower()).strip("_") or "tool"
+    if not ident[0].isalpha():
+        ident = "t_" + ident
+    return ident[:64]
+
+
+def _text_of(content: list[Any]) -> str:
+    return "\n".join(block.text for block in content if getattr(block, "type", None) == "text")
+
+
+class MCPToolSource:
+    """A live connection to an MCP server whose tools are re-published as WAP capabilities."""
+
+    def __init__(self, source: Any, *, prefix: str = "", include: set[str] | None = None) -> None:
+        self.source = source
+        self.prefix = prefix
+        self.include = include
+        self.client: Client | None = None
+        self._stack: AsyncExitStack | None = None
+        self.capability_ids: list[str] = []
+
+    async def connect(self) -> Client:
+        if self.client is None:
+            stack = AsyncExitStack()
+            self.client = await stack.enter_async_context(Client(self.source))
+            self._stack = stack
+        return self.client
+
+    async def aclose(self) -> None:
+        if self._stack is not None:
+            await self._stack.aclose()
+        self._stack = None
+        self.client = None
+
+    async def register(self, wap: WAPServer) -> list[str]:
+        """List the source's tools and add each one to ``wap`` as a capability."""
+        client = await self.connect()
+        registered = []
+        for tool in (await client.list_tools()).tools:
+            if self.include is not None and tool.name not in self.include:
+                continue
+            capability_id = capability_id_for(tool.name, self.prefix)
+            if capability_id in wap.actions:
+                continue
+            schema = dict(tool.input_schema or {"type": "object", "properties": {}})
+            schema.setdefault("type", "object")
+            output = tool.output_schema if tool.output_schema and tool.output_schema.get("type") == "object" else None
+            capability = Capability(
+                id=capability_id,
+                name=(tool.title or tool.name)[:128],
+                description=(tool.description or "")[:4096],
+                input_schema=schema,
+                output_schema=output,
+            )
+            wap.add_capability(capability, self._handler(tool.name))
+            registered.append(capability_id)
+        self.capability_ids = registered
+        return registered
+
+    def _handler(self, tool_name: str) -> Any:
+        async def call(payload: dict[str, Any], ctx: ActionContext) -> ActionResult:
+            if self.client is None:
+                raise WAPProtocolError(ErrorCode.ACTION_FAILED, "the upstream MCP server is not connected")
+            result = await self.client.call_tool(tool_name, payload)
+            text = _text_of(list(result.content or []))
+            if result.is_error:
+                raise WAPProtocolError(ErrorCode.ACTION_FAILED, text or f"MCP tool {tool_name!r} failed")
+            data = result.structured_content
+            if data is None:
+                # Tools without an output schema (e.g. ``-> dict``) return their result only as JSON text.
+                try:
+                    data = json.loads(text)
+                except ValueError:
+                    data = None
+            return ActionResult(content=text, data=dict(data) if isinstance(data, dict) else None)
+
+        return call
+
+
+__all__ = ["MCPToolSource", "capability_id_for"]

wap/server/middleware.py

@@ -0,0 +1,111 @@
+"""Attach WAP to existing applications.
+
+* :func:`inject_routes` is what :meth:`WAPServer.mount` uses for FastAPI apps:
+  it adds the discovery, challenge and interaction routes and stamps every
+  WAP response with ``X-WAP-Version``.
+* :class:`WAPDiscoveryMiddleware` is a dependency-light pure ASGI middleware
+  for *any* ASGI framework (Starlette, Django, Quart, Litestar...). It serves
+  ``/.well-known/wap.json`` (and the legacy ``/.well-known/agent.json``) in front of the wrapped application, so a site
+  can publish its manifest without routing changes.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ..spec.crypto import canonical_json
+from ..spec.models import HEADER_SIGNATURE, HEADER_VERSION, WAP_VERSION, WELL_KNOWN_PATHS, ErrorResponse
+from .app import WAPProtocolError
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from .app import WAPServer
+
+Scope = dict[str, Any]
+ASGIApp = Any
+
+
+class WAPDiscoveryMiddleware:
+    """Serve the signed manifest at the well-known paths in front of any ASGI app."""
+
+    def __init__(self, app: ASGIApp, server: WAPServer) -> None:
+        self.app = app
+        self.server = server
+
+    async def __call__(self, scope: Scope, receive: Any, send: Any) -> None:
+        if scope["type"] == "http" and scope.get("path") in WELL_KNOWN_PATHS:
+            method = scope.get("method", "GET")
+            if method in ("GET", "HEAD"):
+                await self._serve_manifest(scope, send, head=method == "HEAD")
+                return
+            if method == "OPTIONS":
+                await self._send(
+                    send,
+                    204,
+                    b"",
+                    {
+                        "Allow": "GET, HEAD, OPTIONS",
+                        "Access-Control-Allow-Origin": "*",
+                        "Access-Control-Allow-Methods": "GET, HEAD, OPTIONS",
+                    },
+                )
+                return
+            await self._send(send, 405, b"", {"Allow": "GET, HEAD, OPTIONS"})
+            return
+        await self.app(scope, receive, send)
+
+    async def _serve_manifest(self, scope: Scope, send: Any, head: bool) -> None:
+        client = scope.get("client")
+        ip = client[0] if client else None
+        try:
+            await self.server.limit_ip(ip)
+        except WAPProtocolError as exc:
+            body = canonical_json(
+                ErrorResponse.build(exc.code, exc.message, retry_after=exc.retry_after).model_dump(
+                    mode="json", exclude_none=True
+                )
+            )
+            headers = {
+                "Content-Type": "application/json",
+                **exc.headers,
+                HEADER_SIGNATURE: self.server.signer.sign(body),
+            }
+            await self._send(send, 429, body, headers)
+            return
+        manifest = self.server.manifest()
+        body = canonical_json(manifest.model_dump(mode="json"))
+        headers = {
+            "Content-Type": "application/json",
+            "Cache-Control": "public, max-age=300",
+            "Access-Control-Allow-Origin": "*",
+            "ETag": f'"{manifest.signature[:32]}"',
+            HEADER_SIGNATURE: self.server.signer.sign(body),
+        }
+        await self._send(send, 200, b"" if head else body, headers, content_length=len(body))
+
+    @staticmethod
+    async def _send(
+        send: Any, status: int, body: bytes, headers: dict[str, str], content_length: int | None = None
+    ) -> None:
+        raw_headers = [(k.lower().encode("latin-1"), v.encode("latin-1")) for k, v in headers.items()]
+        raw_headers.append((HEADER_VERSION.lower().encode(), WAP_VERSION.encode()))
+        raw_headers.append((b"content-length", str(len(body) if content_length is None else content_length).encode()))
+        await send({"type": "http.response.start", "status": status, "headers": raw_headers})
+        await send({"type": "http.response.body", "body": body})
+
+
+def inject_routes(app: FastAPI, server: WAPServer) -> None:
+    """Register WAP endpoints on ``app`` and expose the server as ``app.state.wap_server``."""
+    from .router import build_router
+
+    existing = getattr(app.state, "wap_server", None)
+    if existing is not None and existing is not server:
+        raise RuntimeError("a different WAPServer is already mounted on this application")
+    if existing is server:
+        return
+    app.include_router(build_router(server))
+    app.state.wap_server = server
+
+
+__all__ = ["WAPDiscoveryMiddleware", "inject_routes"]

wap/server/observability.py

@@ -0,0 +1,102 @@
+"""Ready-made observers for ``WAPServer(observer=...)``.
+
+A WAP server reports what happens to each request as ``observer(event, attributes)``:
+
+========================== ==========================================================
+``request.completed``      ``capability``, ``tier``, ``duration_ms``
+``request.failed``         ``code``, ``capability``, ``tier`` (the action raised)
+``request.rejected``       ``code`` (``rate_limited``, ``pow_invalid``, ``loop_detected``,
+                           ``forbidden``, ...), plus ``scope``/``tier``/``reason`` when known
+``request.idempotent_replay`` ``capability``
+``pow.issued``             ``difficulty``
+========================== ==========================================================
+
+Use :class:`LoggingObserver` for structured logs, :class:`MetricsObserver` for
+in-process counters and latency percentiles (e.g. to export to Prometheus or
+OpenTelemetry), or :func:`combine` to send events to several observers. Any
+callable with the same signature works; observer errors are logged and never
+affect requests.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import threading
+from collections import Counter, defaultdict, deque
+from collections.abc import Callable
+from typing import Any
+
+Observer = Callable[[str, dict[str, Any]], None]
+
+
+class LoggingObserver:
+    """Emit one structured log line (JSON attributes) per event."""
+
+    def __init__(self, logger: logging.Logger | None = None, level: int = logging.INFO) -> None:
+        self.logger = logger or logging.getLogger("wap.events")
+        self.level = level
+
+    def __call__(self, event: str, attributes: dict[str, Any]) -> None:
+        level = logging.WARNING if event == "request.rejected" else self.level
+        self.logger.log(level, "%s %s", event, json.dumps(attributes, default=str, sort_keys=True))
+
+
+class MetricsObserver:
+    """Thread-safe counters by (event, code/tier/capability) plus latency percentiles per capability."""
+
+    def __init__(self, max_samples: int = 10_000) -> None:
+        self._lock = threading.Lock()
+        self.counters: Counter[tuple[str, str]] = Counter()
+        self._latency: dict[str, deque[float]] = defaultdict(lambda: deque(maxlen=max_samples))
+
+    def __call__(self, event: str, attributes: dict[str, Any]) -> None:
+        label = str(attributes.get("code") or attributes.get("capability") or attributes.get("difficulty") or "")
+        with self._lock:
+            self.counters[(event, label)] += 1
+            if event == "request.completed" and "duration_ms" in attributes:
+                self._latency[str(attributes.get("capability"))].append(float(attributes["duration_ms"]))
+
+    def count(self, event: str, label: str | None = None) -> int:
+        with self._lock:
+            if label is not None:
+                return self.counters[(event, label)]
+            return sum(v for (e, _), v in self.counters.items() if e == event)
+
+    def percentile(self, capability: str, q: float) -> float | None:
+        with self._lock:
+            samples = sorted(self._latency.get(capability, ()))
+        if not samples:
+            return None
+        # Nearest-rank method.
+        rank = max(1, math.ceil(q / 100 * len(samples)))
+        return samples[min(rank, len(samples)) - 1]
+
+    def snapshot(self) -> dict[str, Any]:
+        """A JSON-friendly view, e.g. for a ``/metrics`` endpoint of your own."""
+        with self._lock:
+            counters = {f"{event}{{{label}}}" if label else event: n for (event, label), n in self.counters.items()}
+            capabilities = list(self._latency)
+        return {
+            "counters": counters,
+            "latency_ms": {
+                cap: {q: self.percentile(cap, float(q[1:])) for q in ("p50", "p95", "p99")} for cap in capabilities
+            },
+        }
+
+
+def combine(*observers: Observer) -> Observer:
+    """Fan one event out to several observers."""
+
+    def observe(event: str, attributes: dict[str, Any]) -> None:
+        for observer in observers:
+            try:
+                observer(event, attributes)
+            except Exception:  # noqa: BLE001 - one failing sink must not starve the others
+                logging.getLogger("wap.server").exception("observer %r failed for %r", observer, event)
+
+    return observe
+
+
+__all__ = ["LoggingObserver", "MetricsObserver", "Observer", "combine"]