agentrust-py 0.0.3__py3-none-any.whl

agentrust_sdk/client.py

@@ -0,0 +1,790 @@
+"""
+AgentTrust client — sync and async, tier-gated, backed by httpx.
+
+Key features added per CRITIC_AUDIT_REPORT.md:
+  - Centralized config (SDK_CONFIG) for all tunables
+  - Exponential-backoff retry via tenacity (AGENTRUST_RETRY_ATTEMPTS)
+  - Configurable failure mode: open | closed | queue (AGENTRUST_FAILURE_MODE)
+  - Kill-switch: AGENTRUST_ENABLED=false → no-op ValidateResponse
+  - Version negotiation headers (X-AgentTrust-SDK-Version)
+  - OpenTelemetry spans when opentelemetry-sdk is installed (optional)
+  - AGENTRUST_TIMEOUT_SEC, AGENTRUST_RETRY_BACKOFF env vars
+  - Webhook dispatcher integration (Team tier and above)
+    Attach a WebhookDispatcher to receive POST notifications after each
+    validate() call. Set AGENTRUST_WEBHOOK_URL for zero-code setup.
+"""
+from __future__ import annotations
+
+import logging
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .auth import KeyInfo, resolve_key
+from .config import SDK_CONFIG
+from .models import ValidateRequest, ValidateResponse
+from .tiers import Capability, Tier, is_allowed, UPGRADE_MESSAGES
+
+logger = logging.getLogger(__name__)
+
+_VALIDATE_PATH = "/v1/runtime/validate"
+
+# ---------------------------------------------------------------------------
+# Optional OpenTelemetry — soft dependency; no error if not installed
+# ---------------------------------------------------------------------------
+
+try:
+    from opentelemetry import trace as _otel_trace
+    from opentelemetry import metrics as _otel_metrics
+    _tracer = _otel_trace.get_tracer("agentrust.sdk")
+    _meter = _otel_metrics.get_meter("agentrust.sdk")
+    _validation_latency = _meter.create_histogram(
+        "agentrust.validation_latency_ms",
+        description="AgentTrust validate() round-trip latency in milliseconds",
+        unit="ms",
+    )
+    _validation_counter = _meter.create_counter(
+        "agentrust.validations_total",
+        description="Total number of AgentTrust validation calls",
+    )
+    _HAS_OTEL = True
+except ImportError:
+    _HAS_OTEL = False
+    _tracer = None  # type: ignore[assignment]
+
+# ---------------------------------------------------------------------------
+# Optional tenacity — soft dependency for retry/backoff
+# ---------------------------------------------------------------------------
+
+try:
+    from tenacity import (
+        retry,
+        retry_if_exception_type,
+        stop_after_attempt,
+        wait_exponential,
+    )
+    _HAS_TENACITY = True
+except ImportError:
+    _HAS_TENACITY = False
+
+# ---------------------------------------------------------------------------
+# Capabilities required per request field
+# ---------------------------------------------------------------------------
+
+_FIELD_CAPABILITIES: dict[str, Capability] = {
+    "confidence":  Capability.CONFIDENCE_ENGINE,
+    "risk":        Capability.RISK_SCORING,
+    "decision":    Capability.AUTO_DECISION,
+    "policy":      Capability.BUILTIN_POLICY_PACKS,
+    "trust_chain": Capability.TRUST_CHAIN,
+    "audit":       Capability.LOCAL_AUDIT,
+}
+
+
+def _build_gateway_payload(req: ValidateRequest) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "agent_id": req.agent_id,
+        "framework": req.framework,
+        "version": req.version,
+        "parent_envelope_id": req.parent_envelope_id,
+        "request": {
+            "user": req.user,
+            "input": req.input,
+            "session_id": req.session_id,
+            "metadata": req.metadata,
+        },
+        "execution": {
+            "model": req.model,
+            "tools_called": [t.model_dump() for t in req.tools_called],
+            "latency_ms": req.latency_ms,
+            "tokens": req.tokens,
+        },
+        "output": req.output,
+        # Version negotiation (P1 — version skew detection)
+        "sdk_version": SDK_CONFIG.sdk_version,
+        "sdk_min_gateway_version": SDK_CONFIG.min_gateway_version,
+    }
+    return payload
+
+
+def _warn_tier(capability: Capability) -> None:
+    msg = UPGRADE_MESSAGES.get(capability, f"{capability.value} not available on this tier.")
+    logger.warning("[AgentTrust] %s", msg)
+
+
+def _noop_response() -> ValidateResponse:
+    """Return a pass-through ValidateResponse used when SDK is disabled."""
+    from .models import DecisionResult, RiskResult, ValidationResult
+    return ValidateResponse(
+        envelope_id="disabled",
+        validation=ValidationResult(schema_score=100.0, final_confidence=100.0, failures=[]),
+        risk=RiskResult(),
+        decision=DecisionResult(outcome="approve", reason="AgentTrust disabled via AGENTRUST_ENABLED=false"),
+        latency_ms=0.0,
+        tier_info="disabled",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Local queue for failure_mode=queue
+# ---------------------------------------------------------------------------
+
+def _enqueue_failed_request(payload: dict[str, Any]) -> None:
+    """Buffer a failed validate payload to local SQLite for later replay."""
+    try:
+        db_path = SDK_CONFIG.queue_db
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        con = sqlite3.connect(str(db_path))
+        con.execute("PRAGMA journal_mode=WAL")
+        con.execute("PRAGMA synchronous=NORMAL")
+        con.execute(
+            "CREATE TABLE IF NOT EXISTS queue ("
+            "  id INTEGER PRIMARY KEY AUTOINCREMENT,"
+            "  payload TEXT NOT NULL,"
+            "  queued_at TEXT NOT NULL DEFAULT (datetime('now')),"
+            "  attempts INTEGER NOT NULL DEFAULT 0"
+            ")"
+        )
+        import json
+        con.execute("INSERT INTO queue (payload) VALUES (?)", (json.dumps(payload),))
+        con.commit()
+        con.close()
+        logger.info(
+            "[AgentTrust] Validation queued locally (gateway unavailable). "
+            "Run `agentrust queue replay` to flush when gateway returns. "
+            "Buffered at: %s", db_path
+        )
+    except Exception as exc:
+        logger.error("[AgentTrust] Failed to queue validation locally: %s", exc)
+
+
+def drain_queue(
+    base_url: str | None = None,
+    api_key: str | None = None,
+    timeout: float | None = None,
+) -> tuple[int, int]:
+    """Replay locally buffered validations against the gateway.
+
+    Returns (sent, failed) counts. Use after gateway recovers::
+
+        from agentrust_sdk.client import drain_queue
+        sent, failed = drain_queue()
+
+    Or via CLI: ``agentrust queue replay``
+    """
+    import json
+
+    db_path = SDK_CONFIG.queue_db
+    if not db_path.exists():
+        return 0, 0
+
+    _url = (base_url or SDK_CONFIG.gateway_url).rstrip("/")
+    _key = api_key or SDK_CONFIG.api_key
+    _timeout = timeout if timeout is not None else SDK_CONFIG.timeout_sec
+
+    headers: dict[str, str] = {
+        "Content-Type": "application/json",
+        "X-AgentTrust-SDK-Version": SDK_CONFIG.sdk_version,
+    }
+    if _key:
+        headers["X-AgentTrust-Token"] = _key
+
+    con = sqlite3.connect(str(db_path))
+    rows = con.execute("SELECT id, payload FROM queue ORDER BY id").fetchall()
+    sent = 0
+    failed = 0
+    for row_id, raw in rows:
+        try:
+            payload = json.loads(raw)
+            with httpx.Client(base_url=_url, headers=headers, timeout=_timeout) as http:
+                resp = http.post(_VALIDATE_PATH, json=payload)
+                resp.raise_for_status()
+            con.execute("DELETE FROM queue WHERE id = ?", (row_id,))
+            con.commit()
+            sent += 1
+        except Exception as exc:
+            logger.warning("[AgentTrust] Queue replay failed for record %d: %s", row_id, exc)
+            failed += 1
+    con.close()
+    return sent, failed
+
+
+# ---------------------------------------------------------------------------
+# Retry helper
+# ---------------------------------------------------------------------------
+
+def _make_sync_retry():
+    """Return a tenacity retry decorator for sync HTTP calls, or identity if tenacity missing."""
+    if not _HAS_TENACITY:
+        return lambda f: f
+    return retry(
+        retry=retry_if_exception_type((httpx.TransportError, httpx.TimeoutException)),
+        stop=stop_after_attempt(SDK_CONFIG.retry_attempts),
+        wait=wait_exponential(multiplier=SDK_CONFIG.retry_backoff_sec, min=0.1, max=30),
+        reraise=True,
+    )
+
+
+def _make_async_retry():
+    if not _HAS_TENACITY:
+        return lambda f: f
+    return retry(
+        retry=retry_if_exception_type((httpx.TransportError, httpx.TimeoutException)),
+        stop=stop_after_attempt(SDK_CONFIG.retry_attempts),
+        wait=wait_exponential(multiplier=SDK_CONFIG.retry_backoff_sec, min=0.1, max=30),
+        reraise=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+class AgentTrustClient:
+    """
+    Synchronous AgentTrust client with:
+      - kill-switch (AGENTRUST_ENABLED=false → no-op)
+      - retry/backoff (AGENTRUST_RETRY_ATTEMPTS, AGENTRUST_RETRY_BACKOFF)
+      - failure modes (AGENTRUST_FAILURE_MODE=open|closed|queue)
+      - OTel spans when opentelemetry-sdk installed
+      - version negotiation headers
+      - webhook dispatcher (Team tier and above)
+
+    Usage::
+
+        client = AgentTrustClient()
+        result = client.validate(agent_id="payment-agent", user="alice",
+                                 input="Pay invoice #42", output={"amount": 500})
+        print(result.decision.outcome)
+
+    With webhooks (Team tier)::
+
+        from agentrust_sdk.webhooks import WebhookDispatcher
+        dispatcher = WebhookDispatcher(tier=client.tier)
+        dispatcher.register(
+            url="https://discord.com/api/webhooks/...",
+            events=["block", "escalate"],
+        )
+        client = AgentTrustClient(webhook_dispatcher=dispatcher)
+        # webhook fires automatically after every validate()
+
+    Or via env vars (zero code)::
+
+        AGENTRUST_WEBHOOK_URL=https://discord.com/api/webhooks/...
+        AGENTRUST_WEBHOOK_EVENTS=block,escalate
+        # client auto-creates a dispatcher on __init__
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float | None = None,
+        raise_on_tier_gate: bool = False,
+        control_plane_url: str | None = None,
+        webhook_dispatcher: "Any | None" = None,
+    ) -> None:
+        self._key_info: KeyInfo = resolve_key(api_key or SDK_CONFIG.api_key)
+        _url = control_plane_url or base_url or SDK_CONFIG.gateway_url
+        self._base_url = _url.rstrip("/")
+        self._timeout = timeout if timeout is not None else SDK_CONFIG.timeout_sec
+        self._raise_on_tier_gate = raise_on_tier_gate
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-AgentTrust-SDK-Version": SDK_CONFIG.sdk_version,
+        }
+        if self._key_info.key:
+            headers["X-AgentTrust-Token"] = self._key_info.key
+
+        self._http = httpx.Client(
+            base_url=self._base_url, headers=headers, timeout=self._timeout
+        )
+        logger.debug(
+            "[AgentTrust] Client init: tier=%s org=%s failure_mode=%s retries=%d",
+            self._key_info.tier.value, self._key_info.org_id,
+            SDK_CONFIG.failure_mode, SDK_CONFIG.retry_attempts,
+        )
+
+        # ── Webhook dispatcher ────────────────────────────────────────────────
+        # Accept an explicit dispatcher; otherwise auto-create one when
+        # AGENTRUST_WEBHOOK_URL is set (mirrors Adrian's zero-config setup).
+        self._webhook_dispatcher = webhook_dispatcher
+        if self._webhook_dispatcher is None and SDK_CONFIG.webhook_url:
+            try:
+                from .webhooks import WebhookDispatcher as _WD
+                self._webhook_dispatcher = _WD(tier=self._key_info.tier)
+                logger.debug(
+                    "[AgentTrust] Webhook dispatcher auto-created from env var"
+                )
+            except Exception as exc:
+                logger.warning(
+                    "[AgentTrust] Failed to auto-create webhook dispatcher: %s", exc
+                )
+
+        # If failure_mode=queue, drain any buffered records in the background
+        # so they replay automatically when the gateway becomes reachable again.
+        if SDK_CONFIG.failure_mode == "queue" and SDK_CONFIG.queue_db.exists():
+            import threading as _threading
+
+            def _background_drain() -> None:
+                try:
+                    sent, failed = drain_queue(
+                        base_url=self._base_url,
+                        api_key=self._key_info.key,
+                        timeout=self._timeout,
+                    )
+                    if sent:
+                        logger.info(
+                            "[AgentTrust] Background queue drain: replayed %d, failed %d",
+                            sent, failed,
+                        )
+                except Exception as exc:
+                    logger.debug("[AgentTrust] Background drain skipped: %s", exc)
+
+            _threading.Thread(target=_background_drain, daemon=True).start()
+
+    @property
+    def tier(self) -> Tier:
+        return self._key_info.tier
+
+    @property
+    def webhook_dispatcher(self) -> "Any | None":
+        """The attached WebhookDispatcher, or None if not configured."""
+        return self._webhook_dispatcher
+
+    @webhook_dispatcher.setter
+    def webhook_dispatcher(self, dispatcher: "Any | None") -> None:
+        """Attach or replace the WebhookDispatcher after construction."""
+        self._webhook_dispatcher = dispatcher
+
+    def can(self, capability: Capability) -> bool:
+        return is_allowed(capability, self._key_info.tier)
+
+    def validate(
+        self,
+        agent_id: str,
+        user: str,
+        input: str,
+        output: dict[str, Any] | None = None,
+        *,
+        framework: str = "REST",
+        model: str = "unknown",
+        tools_called: list[dict] | None = None,
+        latency_ms: float = 0.0,
+        tokens: int = 0,
+        parent_envelope_id: str | None = None,
+        session_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> ValidateResponse:
+        # ── kill-switch ──────────────────────────────────────────────────────
+        if not SDK_CONFIG.enabled:
+            return _noop_response()
+
+        from .models import ToolCall
+
+        if parent_envelope_id and not self.can(Capability.TRUST_CHAIN):
+            _warn_tier(Capability.TRUST_CHAIN)
+            if self._raise_on_tier_gate:
+                raise TierGateError(Capability.TRUST_CHAIN, self._key_info.tier)
+            parent_envelope_id = None
+
+        req = ValidateRequest(
+            agent_id=agent_id, framework=framework, user=user, input=input,
+            output=output or {}, model=model,
+            tools_called=[ToolCall(**t) for t in (tools_called or [])],
+            latency_ms=latency_ms, tokens=tokens,
+            parent_envelope_id=parent_envelope_id,
+            session_id=session_id, metadata=metadata or {},
+        )
+
+        if self._key_info.tier == Tier.OSS:
+            return _oss_schema_only(req)
+
+        payload = _build_gateway_payload(req)
+        result = self._call_with_resilience(payload, req)
+
+        # ── Webhook fan-out (Team tier and above) ────────────────────────────
+        if (
+            self._webhook_dispatcher is not None
+            and SDK_CONFIG.webhook_auto_dispatch
+        ):
+            try:
+                from .webhooks import event_from_response
+                event = event_from_response(
+                    result,
+                    agent_id=agent_id,
+                    framework=framework,
+                    session_id=session_id,
+                )
+                self._webhook_dispatcher.dispatch(event)
+            except Exception as exc:
+                logger.debug(
+                    "[AgentTrust] Webhook dispatch skipped after validate: %s", exc
+                )
+
+        return result
+
+    def _call_with_resilience(
+        self, payload: dict[str, Any], req: ValidateRequest
+    ) -> ValidateResponse:
+        """Execute HTTP call with retry, OTel, and failure-mode handling."""
+        t0 = time.perf_counter()
+
+        def _do_request() -> ValidateResponse:
+            @_make_sync_retry()
+            def _inner():
+                resp = self._http.post(_VALIDATE_PATH, json=payload)
+                # 426 = version mismatch
+                if resp.status_code == 426:
+                    raise GatewayVersionError(
+                        f"Gateway requires SDK upgrade. "
+                        f"Current SDK: {SDK_CONFIG.sdk_version}. "
+                        f"Upgrade: pip install --upgrade agentrust-sdk"
+                    )
+                resp.raise_for_status()
+                return ValidateResponse.model_validate(resp.json())
+            return _inner()
+
+        span_ctx = (
+            _tracer.start_as_current_span(
+                "agentrust.validate",
+                attributes={"agent_id": req.agent_id, "framework": req.framework,
+                            "sdk_version": SDK_CONFIG.sdk_version},
+            ) if _HAS_OTEL else _nullspan()
+        )
+
+        with span_ctx as span:
+            try:
+                result = _do_request()
+                latency = (time.perf_counter() - t0) * 1000
+                if _HAS_OTEL:
+                    span.set_attribute("decision", result.decision.outcome)
+                    span.set_attribute("risk_tier", result.risk.tier if result.risk else "unknown")
+                    _validation_latency.record(latency, {"agent_id": req.agent_id})
+                    _validation_counter.add(1, {"decision": result.decision.outcome})
+                _apply_tier_mask(result, self._key_info.tier)
+                return result
+            except GatewayVersionError:
+                raise
+            except Exception as exc:
+                if _HAS_OTEL:
+                    span.record_exception(exc)
+                return self._handle_gateway_failure(exc, payload)
+
+    def _handle_gateway_failure(
+        self, exc: Exception, payload: dict[str, Any]
+    ) -> ValidateResponse:
+        mode = SDK_CONFIG.failure_mode
+        if mode == "closed":
+            raise GatewayUnavailableError(
+                f"AgentTrust gateway unreachable and AGENTRUST_FAILURE_MODE=closed. "
+                f"Original error: {exc}"
+            ) from exc
+        if mode == "queue":
+            _enqueue_failed_request(payload)
+        else:  # open (default)
+            logger.warning("[AgentTrust] Gateway unreachable (fail-open): %s", exc)
+        return _noop_response()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "AgentTrustClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+class AsyncAgentTrustClient:
+    """
+    Async AgentTrust client — same resilience features as the sync client,
+    plus async webhook dispatch (Team tier and above).
+
+    Usage::
+
+        async with AsyncAgentTrustClient() as client:
+            result = await client.validate(agent_id="...", user="...", input="...")
+
+    With webhooks (Team tier)::
+
+        from agentrust_sdk.webhooks import WebhookDispatcher
+        dispatcher = WebhookDispatcher(tier=Tier.TEAM)
+        dispatcher.register(url="https://discord.com/api/webhooks/...",
+                            events=["block"])
+        async with AsyncAgentTrustClient(webhook_dispatcher=dispatcher) as client:
+            result = await client.validate(...)
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float | None = None,
+        raise_on_tier_gate: bool = False,
+        control_plane_url: str | None = None,
+        webhook_dispatcher: "Any | None" = None,
+    ) -> None:
+        self._key_info: KeyInfo = resolve_key(api_key or SDK_CONFIG.api_key)
+        _url = control_plane_url or base_url or SDK_CONFIG.gateway_url
+        self._base_url = _url.rstrip("/")
+        self._timeout = timeout if timeout is not None else SDK_CONFIG.timeout_sec
+        self._raise_on_tier_gate = raise_on_tier_gate
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-AgentTrust-SDK-Version": SDK_CONFIG.sdk_version,
+        }
+        if self._key_info.key:
+            headers["X-AgentTrust-Token"] = self._key_info.key
+
+        self._http = httpx.AsyncClient(
+            base_url=self._base_url, headers=headers, timeout=self._timeout
+        )
+
+        # ── Webhook dispatcher ────────────────────────────────────────────────
+        self._webhook_dispatcher = webhook_dispatcher
+        if self._webhook_dispatcher is None and SDK_CONFIG.webhook_url:
+            try:
+                from .webhooks import WebhookDispatcher as _WD
+                self._webhook_dispatcher = _WD(tier=self._key_info.tier)
+            except Exception as exc:
+                logger.warning(
+                    "[AgentTrust] Failed to auto-create async webhook dispatcher: %s",
+                    exc,
+                )
+
+    @property
+    def tier(self) -> Tier:
+        return self._key_info.tier
+
+    @property
+    def webhook_dispatcher(self) -> "Any | None":
+        """The attached WebhookDispatcher, or None if not configured."""
+        return self._webhook_dispatcher
+
+    @webhook_dispatcher.setter
+    def webhook_dispatcher(self, dispatcher: "Any | None") -> None:
+        self._webhook_dispatcher = dispatcher
+
+    def can(self, capability: Capability) -> bool:
+        return is_allowed(capability, self._key_info.tier)
+
+    async def validate(
+        self,
+        agent_id: str,
+        user: str,
+        input: str,
+        output: dict[str, Any] | None = None,
+        *,
+        framework: str = "REST",
+        model: str = "unknown",
+        tools_called: list[dict] | None = None,
+        latency_ms: float = 0.0,
+        tokens: int = 0,
+        parent_envelope_id: str | None = None,
+        session_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> ValidateResponse:
+        if not SDK_CONFIG.enabled:
+            return _noop_response()
+
+        from .models import ToolCall
+
+        if parent_envelope_id and not self.can(Capability.TRUST_CHAIN):
+            _warn_tier(Capability.TRUST_CHAIN)
+            if self._raise_on_tier_gate:
+                raise TierGateError(Capability.TRUST_CHAIN, self._key_info.tier)
+            parent_envelope_id = None
+
+        req = ValidateRequest(
+            agent_id=agent_id, framework=framework, user=user, input=input,
+            output=output or {}, model=model,
+            tools_called=[ToolCall(**t) for t in (tools_called or [])],
+            latency_ms=latency_ms, tokens=tokens,
+            parent_envelope_id=parent_envelope_id,
+            session_id=session_id, metadata=metadata or {},
+        )
+
+        if self._key_info.tier == Tier.OSS:
+            return _oss_schema_only(req)
+
+        payload = _build_gateway_payload(req)
+        result = await self._call_with_resilience(payload, req)
+
+        # ── Async webhook fan-out (Team tier and above) ───────────────────────
+        if (
+            self._webhook_dispatcher is not None
+            and SDK_CONFIG.webhook_auto_dispatch
+        ):
+            try:
+                from .webhooks import event_from_response
+                event = event_from_response(
+                    result,
+                    agent_id=agent_id,
+                    framework=framework,
+                    session_id=session_id,
+                )
+                await self._webhook_dispatcher.async_dispatch(event)
+            except Exception as exc:
+                logger.debug(
+                    "[AgentTrust] Async webhook dispatch skipped after validate: %s",
+                    exc,
+                )
+
+        return result
+
+    async def _call_with_resilience(
+        self, payload: dict[str, Any], req: ValidateRequest
+    ) -> ValidateResponse:
+        t0 = time.perf_counter()
+
+        async def _do_request() -> ValidateResponse:
+            @_make_async_retry()
+            async def _inner():
+                resp = await self._http.post(_VALIDATE_PATH, json=payload)
+                if resp.status_code == 426:
+                    raise GatewayVersionError(
+                        f"Gateway requires SDK upgrade. Current: {SDK_CONFIG.sdk_version}. "
+                        f"Upgrade: pip install --upgrade agentrust-sdk"
+                    )
+                resp.raise_for_status()
+                return ValidateResponse.model_validate(resp.json())
+            return await _inner()
+
+        span_ctx = (
+            _tracer.start_as_current_span(
+                "agentrust.validate",
+                attributes={"agent_id": req.agent_id, "framework": req.framework,
+                            "sdk_version": SDK_CONFIG.sdk_version},
+            ) if _HAS_OTEL else _nullspan()
+        )
+
+        with span_ctx as span:
+            try:
+                result = await _do_request()
+                latency = (time.perf_counter() - t0) * 1000
+                if _HAS_OTEL:
+                    span.set_attribute("decision", result.decision.outcome)
+                    _validation_latency.record(latency, {"agent_id": req.agent_id})
+                    _validation_counter.add(1, {"decision": result.decision.outcome})
+                _apply_tier_mask(result, self._key_info.tier)
+                return result
+            except GatewayVersionError:
+                raise
+            except Exception as exc:
+                if _HAS_OTEL:
+                    span.record_exception(exc)
+                return self._handle_gateway_failure(exc, payload)
+
+    def _handle_gateway_failure(
+        self, exc: Exception, payload: dict[str, Any]
+    ) -> ValidateResponse:
+        mode = SDK_CONFIG.failure_mode
+        if mode == "closed":
+            raise GatewayUnavailableError(
+                f"AgentTrust gateway unreachable and AGENTRUST_FAILURE_MODE=closed. "
+                f"Original error: {exc}"
+            ) from exc
+        if mode == "queue":
+            _enqueue_failed_request(payload)
+        else:
+            logger.warning("[AgentTrust] Async gateway unreachable (fail-open): %s", exc)
+        return _noop_response()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncAgentTrustClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class TierGateError(RuntimeError):
+    def __init__(self, capability: Capability, current_tier: Tier) -> None:
+        msg = UPGRADE_MESSAGES.get(
+            capability, f"{capability.value} not available on {current_tier.value} tier."
+        )
+        super().__init__(msg)
+        self.capability = capability
+        self.current_tier = current_tier
+
+
+class GatewayUnavailableError(RuntimeError):
+    """Raised when AGENTRUST_FAILURE_MODE=closed and gateway is unreachable."""
+
+
+class GatewayVersionError(RuntimeError):
+    """Raised when gateway returns 426 — SDK version too old."""
+
+
+# ---------------------------------------------------------------------------
+# OSS schema-only path
+# ---------------------------------------------------------------------------
+
+def _oss_schema_only(req: ValidateRequest) -> ValidateResponse:
+    """Run schema validation in-process for OSS tier. No gateway call."""
+    from .models import DecisionResult, RiskResult, ValidationResult
+
+    failures: list[str] = []
+    if not isinstance(req.output, dict):
+        failures.append("output must be a JSON object")
+        schema_score = 0.0
+    elif not req.output:
+        failures.append("output is empty")
+        schema_score = 40.0
+    else:
+        schema_score = 100.0
+
+    return ValidateResponse(
+        envelope_id="oss-local",
+        validation=ValidationResult(
+            schema_score=schema_score, final_confidence=schema_score, failures=failures,
+        ),
+        risk=RiskResult(),
+        decision=DecisionResult(),
+        latency_ms=0.0,
+        tier_info=Tier.OSS.value,
+        upgrade_hint="Upgrade to Free tier for full validation: agentrust.io/signup",
+    )
+
+
+def _apply_tier_mask(result: ValidateResponse, tier: Tier) -> None:
+    from .models import DecisionResult, RiskResult
+    if not is_allowed(Capability.CONFIDENCE_ENGINE, tier):
+        result.validation.final_confidence = result.validation.schema_score
+    if not is_allowed(Capability.RISK_SCORING, tier):
+        result.risk = RiskResult()
+    if not is_allowed(Capability.AUTO_DECISION, tier):
+        result.decision = DecisionResult()
+    if not is_allowed(Capability.TRUST_CHAIN, tier):
+        result.trust_chain = None
+
+
+# ---------------------------------------------------------------------------
+# OTel null-span context manager (when OTel not installed)
+# ---------------------------------------------------------------------------
+
+class _NullSpan:
+    def set_attribute(self, *a: Any, **kw: Any) -> None: ...
+    def record_exception(self, *a: Any, **kw: Any) -> None: ...
+    def __enter__(self): return self
+    def __exit__(self, *a: Any): ...
+
+
+def _nullspan() -> _NullSpan:
+    return _NullSpan()