External Guard Adapters

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)

pub struct CircuitBreakerConfig {
    /// Failures observed within `failure_window` before the breaker opens.
    pub failure_threshold: u32,
    /// Rolling window for failure counting in the Closed state. Failures
    /// older than this are discarded from the sliding count.
    pub failure_window: Duration,
    /// Consecutive successes required in the HalfOpen state before the
    /// breaker transitions back to Closed.
    pub success_threshold: u32,
    /// Time the breaker remains Open before a HalfOpen probe is allowed.
    pub reset_timeout: Duration,
}

impl Default for CircuitBreakerConfig {
    fn default() -> Self {
        Self {
            failure_threshold: 5,
            failure_window: Duration::from_secs(60),
            success_threshold: 2,
            reset_timeout: Duration::from_secs(30),
        }
    }
}

pub enum BackoffStrategy {
    /// Each attempt sleeps `base_delay * 2^(attempt - 1)` before jitter.
    Exponential,
    /// Each attempt sleeps `base_delay` before jitter.
    Constant,
    /// Each attempt sleeps `base_delay * attempt` before jitter.
    Linear,
}

pub struct RetryConfig {
    /// Maximum number of retries after the initial attempt. A value of `0`
    /// means the operation is attempted exactly once.
    pub max_retries: u32,
    /// Base delay for the first retry.
    pub base_delay: Duration,
    /// Upper bound on the sleep between attempts (before jitter is added).
    pub max_delay: Duration,
    /// Fraction of the computed delay to use as bounded multiplicative
    /// jitter. Must be in `[0.0, 1.0]`; values outside that range are
    /// clamped.
    pub jitter_fraction: f64,
    /// Backoff curve.
    pub strategy: BackoffStrategy,
}

impl Default for RetryConfig {
    fn default() -> Self {
        Self {
            max_retries: 3,
            base_delay: Duration::from_millis(100),
            max_delay: Duration::from_secs(5),
            jitter_fraction: 0.25,
            strategy: BackoffStrategy::Exponential,
        }
    }
}

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;
}

pub struct ScopedAsyncGuard<E: ExternalGuard> {
    adapter: AsyncGuardAdapter<E>,
    tool_patterns: Vec<String>,
}

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

    fn evaluate(&self, ctx: &GuardContext) -> Result<GuardDecision, KernelError> {
        // By design: a tool-scoped guard returns Allow for traffic outside
        // its scope. The deny-by-default contract is enforced by the
        // composing authority layer, not by this single scoped guard.
        if !self.matches_tool(&ctx.request.tool_name) {
            return Ok(GuardDecision::allow());
        }

        let call_ctx = self.call_context(ctx);
        self.block_on(self.adapter.evaluate(&call_ctx))
            .map(GuardDecision::from_verdict)
    }

    fn revalidate_before_dispatch(&self, _ctx: &GuardContext) -> Result<(), KernelError> {
        // External evaluation can consume rate-limit, cache, retry, and
        // circuit-breaker state. The admission verdict is authoritative for
        // this dispatch, so readiness revalidation must not call the adapter a
        // second time.
        Ok(())
    }
}

pub trait ExternalGuard: Send + Sync {
    /// Human-readable guard name (e.g. `"bedrock-guardrail"`).
    fn name(&self) -> &str;

    /// Return a cache key for this request, or `None` to skip caching.
    fn cache_key(&self, ctx: &GuardCallContext) -> Option<String>;

    /// Evaluate the request against the external service.
    async fn eval(&self, ctx: &GuardCallContext) -> Result<Verdict, ExternalGuardError>;
}

pub struct GuardCallContext {
    /// Tool name being invoked.
    pub tool_name: String,
    /// Calling agent identifier.
    pub agent_id: String,
    /// Target server identifier.
    pub server_id: String,
    /// Tool arguments serialized as JSON. Kept as a `String` so the cache
    /// key can hash it cheaply without committing to a fixed schema.
    pub arguments_json: String,
}

pub enum ExternalGuardError {
    /// The downstream service timed out.
    #[error("external guard timeout")]
    Timeout,
    /// The downstream service returned a retryable failure (5xx, connection
    /// reset, etc.). Retryable errors are counted towards the circuit
    /// breaker and may trigger a retry.
    #[error("transient external error: {0}")]
    Transient(String),
    /// A permanent error that should not be retried (e.g. malformed request,
    /// 4xx auth failure).
    #[error("permanent external error: {0}")]
    Permanent(String),
}