agent_sdk_toolkit/environment/
runtime.rs

1//! Data-only aliases for common isolation runtime refs.
2//!
3//! These helpers make profile construction easier while keeping concrete
4//! adapter registration, process startup, network policy, and cleanup owned by
5//! the host or a future optional runtime-adapter crate.
6
7use std::fmt;
8
9use agent_sdk_core::{IsolationClass, IsolationRuntimeRef};
10use serde::{Deserialize, Serialize};
11
12/// Well-known toolkit runtime refs for common environment profiles.
13///
14/// These values are data-only aliases for `IsolationRuntimeRef`. Hosts and
15/// optional runtime crates still own adapter registration and enforcement.
16///
17/// ```
18/// use agent_sdk_core::{IsolationClass, IsolationRuntimeRef};
19/// use agent_sdk_toolkit::EnvironmentRuntime;
20///
21/// let runtime = EnvironmentRuntime::LocalContainer;
22/// assert_eq!(runtime.as_str(), "runtime:local.container");
23/// assert_eq!(runtime.isolation_class(), IsolationClass::Container);
24///
25/// let runtime_ref: IsolationRuntimeRef = runtime.into();
26/// assert_eq!(runtime_ref.as_str(), "runtime:local.container");
27/// ```
28#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
29pub enum EnvironmentRuntime {
30    /// Local container adapter ref (`runtime:local.container`), requiring container isolation.
31    #[serde(rename = "runtime:local.container")]
32    LocalContainer,
33    /// Local sandbox adapter ref (`runtime:local.sandbox`), requiring sandbox isolation.
34    #[serde(rename = "runtime:local.sandbox")]
35    LocalSandbox,
36    /// Local lightweight VM adapter ref (`runtime:local.lightweight_vm`), requiring VM isolation.
37    #[serde(rename = "runtime:local.lightweight_vm")]
38    LocalLightweightVm,
39    /// Remote sandbox adapter ref (`runtime:remote.sandbox`), requiring remote sandbox isolation.
40    #[serde(rename = "runtime:remote.sandbox")]
41    RemoteSandbox,
42    /// Explicit host-process adapter ref (`runtime:local.host_process`).
43    ///
44    /// Hosts should use this only when policy allows host process execution.
45    #[serde(rename = "runtime:local.host_process")]
46    LocalHostProcess,
47}
48
49impl EnvironmentRuntime {
50    /// Returns the stable serialized runtime ref lowered into core isolation contracts.
51    pub fn as_str(self) -> &'static str {
52        match self {
53            Self::LocalContainer => "runtime:local.container",
54            Self::LocalSandbox => "runtime:local.sandbox",
55            Self::LocalLightweightVm => "runtime:local.lightweight_vm",
56            Self::RemoteSandbox => "runtime:remote.sandbox",
57            Self::LocalHostProcess => "runtime:local.host_process",
58        }
59    }
60
61    /// Returns the matching minimum isolation class for this runtime ref.
62    ///
63    /// The value is used by `AgentWorkspaceEnvironmentProfile::runtime` when it
64    /// builds a core isolation requirement. It is not an adapter capability
65    /// check by itself.
66    pub fn isolation_class(self) -> IsolationClass {
67        match self {
68            Self::LocalContainer => IsolationClass::Container,
69            Self::LocalSandbox => IsolationClass::Sandbox,
70            Self::LocalLightweightVm => IsolationClass::LightweightVm,
71            Self::RemoteSandbox => IsolationClass::RemoteSandbox,
72            Self::LocalHostProcess => IsolationClass::HostProcess,
73        }
74    }
75
76    /// Returns the core runtime ref for this well-known runtime alias.
77    ///
78    /// Constructing the ref is data-only. A host must still register a matching
79    /// isolation adapter before execution can select it.
80    pub fn runtime_ref(self) -> IsolationRuntimeRef {
81        IsolationRuntimeRef::new(self.as_str())
82    }
83}
84
85impl fmt::Display for EnvironmentRuntime {
86    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
87        formatter.write_str(self.as_str())
88    }
89}
90
91impl From<EnvironmentRuntime> for IsolationRuntimeRef {
92    fn from(runtime: EnvironmentRuntime) -> Self {
93        runtime.runtime_ref()
94    }
95}
agent_sdk_toolkit/environment/runtime.rs

agent_sdk_toolkit/environment/
runtime.rs
