agent_runtime_core/
provider.rs

1//! Versioned provider adapter traits.
2//!
3//! `ProviderAdapterV1` is the stable provider-neutral interface consumed by
4//! control-plane crates such as `agentctl`.
5
6use crate::schema::{
7    AuthStateRequest, AuthStateResponse, CapabilitiesRequest, CapabilitiesResponse, ExecuteRequest,
8    ExecuteResponse, HealthcheckRequest, HealthcheckResponse, LimitsRequest, LimitsResponse,
9    ProviderEnvelope, ProviderMetadata, ProviderOperation, ProviderResult,
10};
11
12/// Provider adapter contract version `v1`.
13///
14/// Implementors provide the five normalized adapter surfaces and return typed
15/// results that are later wrapped into uniform envelopes for machine consumers.
16pub trait ProviderAdapterV1: Send + Sync {
17    /// Static provider metadata for contract negotiation and logging.
18    fn metadata(&self) -> ProviderMetadata;
19
20    /// Return provider capabilities and feature switches.
21    fn capabilities(&self, request: CapabilitiesRequest) -> ProviderResult<CapabilitiesResponse>;
22
23    /// Probe provider readiness.
24    fn healthcheck(&self, request: HealthcheckRequest) -> ProviderResult<HealthcheckResponse>;
25
26    /// Execute a provider-defined task payload.
27    fn execute(&self, request: ExecuteRequest) -> ProviderResult<ExecuteResponse>;
28
29    /// Report execution/auth/rate guardrails.
30    fn limits(&self, request: LimitsRequest) -> ProviderResult<LimitsResponse>;
31
32    /// Report current authentication state.
33    fn auth_state(&self, request: AuthStateRequest) -> ProviderResult<AuthStateResponse>;
34
35    /// Wrap `capabilities` result into the normalized response envelope.
36    fn capabilities_envelope(
37        &self,
38        request: CapabilitiesRequest,
39    ) -> ProviderEnvelope<CapabilitiesResponse> {
40        ProviderEnvelope::from_result(
41            self.metadata().provider_ref(),
42            ProviderOperation::Capabilities,
43            self.capabilities(request),
44        )
45    }
46
47    /// Wrap `healthcheck` result into the normalized response envelope.
48    fn healthcheck_envelope(
49        &self,
50        request: HealthcheckRequest,
51    ) -> ProviderEnvelope<HealthcheckResponse> {
52        ProviderEnvelope::from_result(
53            self.metadata().provider_ref(),
54            ProviderOperation::Healthcheck,
55            self.healthcheck(request),
56        )
57    }
58
59    /// Wrap `execute` result into the normalized response envelope.
60    fn execute_envelope(&self, request: ExecuteRequest) -> ProviderEnvelope<ExecuteResponse> {
61        ProviderEnvelope::from_result(
62            self.metadata().provider_ref(),
63            ProviderOperation::Execute,
64            self.execute(request),
65        )
66    }
67
68    /// Wrap `limits` result into the normalized response envelope.
69    fn limits_envelope(&self, request: LimitsRequest) -> ProviderEnvelope<LimitsResponse> {
70        ProviderEnvelope::from_result(
71            self.metadata().provider_ref(),
72            ProviderOperation::Limits,
73            self.limits(request),
74        )
75    }
76
77    /// Wrap `auth-state` result into the normalized response envelope.
78    fn auth_state_envelope(
79        &self,
80        request: AuthStateRequest,
81    ) -> ProviderEnvelope<AuthStateResponse> {
82        ProviderEnvelope::from_result(
83            self.metadata().provider_ref(),
84            ProviderOperation::AuthState,
85            self.auth_state(request),
86        )
87    }
88}
89
90/// Alias to the latest stable provider adapter contract.
91pub trait ProviderAdapter: ProviderAdapterV1 {}
92
93impl<T: ProviderAdapterV1 + ?Sized> ProviderAdapter for T {}
agent_runtime_core/provider.rs

agent_runtime_core/
provider.rs
