External Guard Adapters

Every external-guard provider (Bedrock, Azure Content Safety, Vertex Safety, Snyk, VirusTotal, Safe Browsing) reaches the kernel through the same generic adapter: AsyncGuardAdapter. This page documents the adapter mechanics: how the circuit breaker, cache, rate limiter, and retry loop compose; how the async evaluator bridges back to a sync Guard impl; and which provider lives behind which struct. For configuration of a specific provider, read External Guards first.

Layering

A single call through the adapter passes four stages in a fixed order. The order matters because it determines which failure mode produces which verdict.

AsyncGuardAdapter::evaluate(ctx)
  1. CircuitBreaker.allow_call()      -> CircuitOpenVerdict on deny
  2. TtlCache.get(cache_key)          -> cached verdict on hit
  3. TokenBucket.try_acquire()        -> RateLimitedVerdict on empty
  4. retry_with_jitter(inner.eval)    -> Verdict::Deny on permanent failure
                                        -> Verdict on success (also cached)

Invariants enforced by crates/chio-guards/src/external/mod.rs:

• Cache before rate limit. Cache hits do not consume the bucket.
• Rate-limited calls do not fail the breaker. Only real attempts at the external service count toward the breaker's failure threshold.
• Permanent errors short-circuit retry. Only ExternalGuardError::Timeout and ::Transient retry;::Permanent returns immediately.
• The fallback is deny. Any uncaught error path returns Verdict::Deny with a tracing::warn! record.

ExternalGuard trait

The async trait a concrete provider implements:

#[async_trait]
pub trait ExternalGuard: Send + Sync {
    fn name(&self) -> &str;
    fn cache_key(&self, ctx: &GuardCallContext) -> Option<String>;
    async fn eval(&self, ctx: &GuardCallContext)
        -> Result<Verdict, ExternalGuardError>;
}

pub enum ExternalGuardError {
    Timeout,
    Transient(String),    // 5xx, connection reset, etc.
    Permanent(String),    // 4xx auth, malformed request, etc.
}

pub struct GuardCallContext {
    pub tool_name: String,
    pub agent_id: String,
    pub server_id: String,
    pub arguments_json: String,
}

eval describes a single attempt: one HTTP call, one decision. Concrete providers do not implement retry, caching, or rate limiting. The adapter wraps that for them.

AsyncGuardAdapterConfig

Defaults from AsyncGuardAdapterConfig::default():

Both CircuitOpenVerdict and RateLimitedVerdict are two-variant enums: Deny (default, fail-closed) and Allow (advisory only). There is no Escalate variant; a guard that needs human escalation pairs with the approval guard rather than overloading this knob.

Circuit breaker

Three-state breaker from crates/chio-guards/src/external/circuit_breaker.rs:

• Closed. Calls flow. Failures accumulate inside a sliding failure_window. Once the count reaches failure_threshold, the breaker opens and records the timestamp.
• Open. Calls short-circuit for at least reset_timeout. The adapter returns the configured CircuitOpenVerdict without touching the inner guard.
• HalfOpen. A bounded set of trial calls is admitted. After success_threshold consecutive successes the breaker closes; any failure reopens it.

Time uses a Clock abstraction; tests drive transitions through tokio::time::pause + advance without wall-clock sleeps. For the deeper rationale see Fail-Closed Semantics.

Retry strategies

From crates/chio-guards/src/external/retry.rs. Three strategies ship in tree:

pub enum BackoffStrategy {
    Exponential,      // base * 2^(attempt-1)
    Constant,         // base
    Linear,           // base * attempt
}

pub struct RetryConfig {
    pub max_retries: u32,            // additional retries after the first attempt
    pub base_delay: Duration,        // 100 ms default
    pub max_delay: Duration,         // 5 s ceiling before jitter
    pub jitter_fraction: f64,        // 0.0..=1.0; 0.25 default
    pub strategy: BackoffStrategy,   // Exponential default
}

Jitter is bounded multiplicative. The default RNG seeds from max_retries + 0x9E37_79B9_7F4A_7C15 for deterministic test runs; retry_with_jitter_rng accepts a caller-supplied Rng when needed. The sleep between attempts uses tokio::time::sleep so it honours tokio::time::pause.

TTL cache

TtlCache<String, Verdict> with bounded capacity. Keys come from ExternalGuard::cache_key; a provider that returns None opts the call out of caching. Default TTL is 60 seconds; default capacity is 1024 entries. Eviction is recency-biased on the underlying map.

The cache is consulted before the rate limiter so steady-state hot traffic does not drain the QPS budget. A cached verdict attests to a decision made within the configured TTL, not a live one; operators that need per-call freshness either set cache_ttl to 0 or override cache_key to return None.

AsyncGuardAdapter shape

pub struct AsyncGuardAdapter<E: ExternalGuard + ?Sized> {
    inner: Arc<E>,
    config: AsyncGuardAdapterConfig,
    cache: TtlCache<String, Verdict>,
    circuit: CircuitBreaker,
    bucket: TokenBucket,
}

impl<E: ExternalGuard + ?Sized> AsyncGuardAdapter<E> {
    pub fn builder(inner: Arc<E>) -> AsyncGuardAdapterBuilder<E>;
    pub fn name(&self) -> &str;
    pub fn config(&self) -> &AsyncGuardAdapterConfig;
    pub fn circuit_state(&self) -> CircuitState;
    pub async fn evaluate(&self, ctx: &GuardCallContext) -> Verdict;
}

Construction goes through the fluent builder. Tests pass a custom Clock via .clock(...) to drive breaker and cache transitions deterministically.

Sync bridge: ScopedAsyncGuard

The kernel guard pipeline is sync. The bridge in chio-external-guards wraps an AsyncGuardAdapter in a sync Guard and scopes it to a wildcard tool-name pattern set:

pub struct ScopedAsyncGuard<E: ExternalGuard> {
    adapter: AsyncGuardAdapter<E>,
    tool_patterns: Vec<String>,    // empty means "every tool"
}

impl<E: ExternalGuard> Guard for ScopedAsyncGuard<E> {
    fn name(&self) -> &str { self.adapter.name() }

    fn evaluate(&self, ctx: &GuardContext)
        -> Result<Verdict, KernelError>
    {
        if !self.matches_tool(&ctx.request.tool_name) {
            return Ok(Verdict::Allow);
        }
        let call_ctx = self.call_context(ctx);
        self.block_on(self.adapter.evaluate(&call_ctx))
    }
}

A non-matching tool returns Verdict::Allow without calling the external service and without consuming rate-limit or cache budget. The bridge detects the current Tokio runtime flavor and dispatches:

• MultiThread: tokio::task::block_in_place + the current handle.
• CurrentThread: spawn a fresh current-thread runtime on a scoped thread to avoid deadlocking the caller's executor.
• No runtime in scope: build a transient current-thread runtime and run to completion.
• Unknown future Tokio flavor: return KernelError::GuardDenied with a diagnostic name rather than panic.

Provider catalog

For credentials, endpoints, and per-provider thresholds, read External Guards. That page covers the HushSpec cloud_guardrails and threat_intel blocks and the SSRF-safe URL validator that gates every adapter.

Cache-key design

Each provider implements cache_key(ctx). The key must capture every input that influences the verdict and nothing else. Typical recipes:

• Content-safety providers hash the prompt or tool argument body so a benign prompt hits cache across agents.
• URL-threat providers hash the canonicalised URL host + path; the fragment is dropped because it does not change reputation.
• Vulnerability providers hash the package coordinate (name@version) plus the ecosystem.

Returning None opts out of caching for that specific call, useful when the input is sensitive or the verdict is too contextual to share.

Receipt evidence

The adapter records every decision on the receipt's guard-evidence block. The evidence struct preserves the guard name and provider identity, the provider decision label (Azure severity, Vertex probability, VirusTotal detection count, and so on), the upstream request correlation id when one is returned, and a cache-or-live flag so auditors can tell a cached decision from a fresh call.

Performance class

Hot path on a cache hit: one breaker check, one cache read. Sub-microsecond. Hot path on a miss: one breaker check, one cache read miss, one bucket acquire, one HTTP call (latency dominated by the provider), one cache insert. Hot path on a circuit-open call: one breaker check, one verdict return; never touches the network.

Next steps

• External Guards for provider configuration, the SSRF posture, and the fail-mode matrix.
• Fail-Closed Semantics for the kernel-wide invariants this adapter inherits.
• Rate Limit Guards for in-process limits that complement provider-side QPS budgets.