cua-sandbox-core

pub struct CloudCheck {
  pub name: String,
  pub ok: bool,
  pub detail: String,
}

pub struct CloudConnected {
  pub provider: CloudProvider,
  pub checks: Vec<CloudCheck>,
}

pub struct CloudCredentials {
  pub found: bool,
  pub source: String,
}

pub struct CloudDisconnected {
  pub provider: String,
  pub disconnected: bool,
  pub left: Vec<CloudResource>,
}

pub struct CloudKind {
  pub image: String,
  pub kind: String,
  pub supported: bool,
  pub reason: String,
  pub machine_type: String,
  pub usd_per_hour: f64,
}

pub trait CloudManager: Send + Sync + 'static {
  async fn status(&self, provider: Option<&str>) -> Result<CloudStatusReport>;
  async fn test(&self, target: &CloudTarget) -> Result<CloudTestReport>;
  async fn connect(&self, target: &CloudTarget, make_default: bool, ttl_hours: Option<u32>) -> Result<CloudConnected>;
  async fn disconnect(&self, provider: &str) -> Result<CloudDisconnected>;
  async fn sweep(&self, provider: Option<&str>, dry_run: bool, all: bool) -> Result<CloudSweepReport>;
}

pub struct CloudProvider {
  pub name: String,
  pub title: String,
  pub tier: String,
  pub connected: bool,
  pub default: bool,
  pub credentials: CloudCredentials,
  pub account: String,
  pub profile: String,
  pub region: String,
  pub zone: String,
  pub project: String,
  pub environment: String,
  pub label: String,
  pub ttl_hours: u32,
  pub kinds: Vec<CloudKind>,
}

pub struct CloudResource {
  pub provider: String,
  pub id: String,
  pub resource_type: String,
  pub sandbox: String,
  pub machine: String,
  pub region: String,
  pub state: String,
  pub created: String,
  pub expires: String,
  pub expired: bool,
}

pub struct CloudStatusReport {
  pub default_on: String,
  pub providers: Vec<CloudProvider>,
  pub resources: Vec<CloudResource>,
}

pub struct CloudSweepItem {
  pub resource: CloudResource,
  pub action: String,
  pub reason: String,
}

pub struct CloudSweepReport {
  pub dry_run: bool,
  pub resources: Vec<CloudSweepItem>,
}

pub struct CloudTarget {
  pub provider: String,
  pub profile: Option<String>,
  pub region: Option<String>,
  pub zone: Option<String>,
  pub project: Option<String>,
  pub environment: Option<String>,
}

pub struct CloudTestReport {
  pub provider: String,
  pub ok: bool,
  pub account: String,
  pub checks: Vec<CloudCheck>,
}

pub struct ConnectOptionsOverride {
  pub probe_timeout: Option<Duration>,
}

pub struct CreateOptions {
  pub provider: ProviderKind,
  pub name: Option<String>,
  pub image: String,
  pub os: String,
  pub cpus: u32,
  pub memory_mb: u64,
  pub disk_gb: Option<u32>,
  pub ports: Vec<u16>,
  pub services: BTreeMap<String, u16>,
  pub wait_for: Vec<Probe>,
  pub ready_timeout: Duration,
  pub ready_timeout_given: bool,
  pub env: BTreeMap<String, String>,
  pub command: Option<Vec<String>>,
  pub env_token: Option<String>,
  pub fleet: FleetOptions,
  pub firmware: Option<String>,
  pub sidecars: Vec<Sidecar>,
  pub registry_credentials: Option<RegistryCredentials>,
  pub build: Option<BuildSpec>,
  pub kind: Kind,
  pub runtime: Runtime,
  pub container_runtime: Option<String>,
  pub network: NetworkMode,
  pub owner_pid: Option<u32>,
  pub contrib: Option<String>,
  pub keep_on_failure: bool,
  pub gpu: Option<String>,
  pub ephemeral_name: Option<String>,
}
impl CreateOptions {
  fn new(provider: ProviderKind, image: impl Into<String>) -> Self;
  fn sidecar(self, sidecar: Sidecar) -> Self;
  fn default_warm(&self) -> Option<bool>;
  fn on(&self) -> Option<On>;
  fn apply_placement(&mut self) -> Result<()>;
  fn name(self, name: impl Into<String>) -> Self;
  fn wait_for(self, probe: Probe) -> Self;
  fn service(self, name: impl Into<String>, port: u16) -> Self;
  fn command<I, S>(self, argv: I) -> Self where I: IntoIterator<Item = S>, S: Into<String>;
  fn wait_for_service(self, service: &str, http_path: Option<&str>) -> Result<Self>;
  fn service_probe(&self, service: &str, http_path: Option<&str>) -> Result<Probe>;
  async fn fleet_pool_key(&self) -> Result<PoolSpecKey>;
  async fn fleet_pool_key_resolved(&self) -> Result<(PoolSpecKey, Option<ImageInfo>)>;
  fn pool_sandbox_spec(&self) -> SandboxSpec;
  fn validate_sidecars(&self) -> Result<()>;
}

pub struct EphemeralLease {
  pub name: String,
  pub pid: u32,
  pub created_at: u64,
}

pub enum Error {
  InvalidArgument(String),
  InvalidPlacement(PlacementError),
  NotFound(String),
  AmbiguousSandbox { name: String, candidates: Vec<String>, message: String },
  ProviderNotConfigured(ProviderKind),
  ContribNotConfigured(String),
  Unsupported { provider: ProviderKind, op: String },
  SpacesdNotAvailable { sandbox: String, reason: String },
  UnsupportedImage(String),
  Timeout(String),
  Http(String),
  Fleet(Error),
  Runtime(RuntimeError),
  Env(Error),
  Mcp(String),
  Cloud(String),
  Io(Error),
  Json(Error),
  Cancelled(String),
}

pub struct FleetOptions {
  pub pool: Option<String>,
  pub runtime: Option<RuntimeKind>,
  pub warm: Option<bool>,
  pub max_pool_size: Option<u32>,
  pub replicas: Option<u32>,
  pub ttl_seconds_after_created: Option<u32>,
  pub apply: bool,
  pub cpus_given: bool,
  pub memory_given: bool,
}

pub struct FleetState {
  pub name: String,
  pub runtime_type: String,
  pub pool_name: String,
  pub status: String,
  pub created_at: String,
  pub extra: Map<String, Value>,
}

pub struct Forward {
  pub guest_port: u16,
  pub local_addr: Option<SocketAddr>,
  pub url: Option<String>,
  pub via: ForwardVia,
}
impl Forward {
  async fn close(self) -> Result<()>;
}

pub enum ForwardVia {
  Tcp,
  EnvTunnel,
  GatewayUrl,
  GatewayProxy,
}

pub struct GuestDisplay {
  pub url: String,
  pub via: String,
  pub open_command: Option<Vec<String>>,
}
impl GuestDisplay {
  fn redacted_url(&self) -> String;
}

pub enum GuestOutput {
  Stdout(Vec<u8>),
  Stderr(Vec<u8>),
}

pub struct GuestScreenshot {
  pub png: Vec<u8>,
  pub width: u32,
  pub height: u32,
  pub via: String,
}

pub struct HttpResponse {
  pub status: u16,
  pub headers: Vec<(String, String)>,
  pub body: Vec<u8>,
}
impl HttpResponse {
  fn text(&self) -> String;
}

pub struct ImageInfo {
  pub reference: String,
  pub pinned_ref: String,
  pub digest: String,
  pub variant: String,
  pub arch: Option<String>,
  pub os: String,
  pub emulated: bool,
  pub spacesd: Option<bool>,
}

pub enum ImageMode {
  Direct,
  Template,
}

pub enum InstanceStatus {
  Running,
  Paused,
  Stopped,
  Provisioning,
  Unknown(String),
}

pub struct LocalEndpoints {
  pub host: String,
  pub ports: BTreeMap<u16, u16>,
  pub vnc: Option<String>,
  pub qmp: Option<String>,
  pub ssh: Option<String>,
  pub serial_log: Option<String>,
  pub container_id: Option<String>,
}

pub struct LocalFleetPlan {
  pub template: String,
  pub reference: String,
  pub runtime: RuntimeKind,
  pub image: String,
  pub firmware: Option<String>,
  pub cpus: Option<u32>,
  pub memory_mb: Option<u64>,
  pub services: BTreeMap<String, u16>,
  pub probes: Vec<Probe>,
}
impl LocalFleetPlan {
  fn apply(&self, o: &mut CreateOptions);
}

pub struct LocalInstance {
  pub name: String,
  pub backend: String,
  pub status: InstanceStatus,
  pub endpoints: LocalEndpoints,
}

pub struct LocalProbe {
  pub port: u16,
  pub http_path: Option<String>,
}

pub trait LocalRuntime: Send + Sync {
  fn backend(&self) -> String;
  async fn start(&self, spec: &LocalStartSpec) -> RuntimeResult<LocalInstance>;
  async fn start_resolved(&self, spec: &LocalStartSpec) -> RuntimeResult<(LocalInstance, Option<ImageInfo>)>;
  async fn gpu_support(&self) -> Vec<GpuSupport>;
  async fn stop(&self, name: &str) -> RuntimeResult<()>;
  async fn suspend(&self, name: &str) -> RuntimeResult<()>;
  async fn resume(&self, name: &str) -> RuntimeResult<LocalInstance>;
  fn power_control(&self, runtime_type: &str) -> Option<PowerControl>;
  async fn fork(&self, source: &str, new_name: &str) -> RuntimeResult<()>;
  async fn checkpoint(&self, name: &str, checkpoint: &str) -> RuntimeResult<()>;
  async fn list(&self) -> RuntimeResult<Vec<LocalSummary>>;
  async fn status(&self, name: &str) -> RuntimeResult<InstanceStatus>;
  async fn status_on(&self, name: &str, runtime_type: &str) -> RuntimeResult<InstanceStatus>;
  async fn delete(&self, name: &str) -> RuntimeResult<()>;
  async fn endpoints(&self, name: &str) -> RuntimeResult<LocalEndpoints>;
  async fn guest_tcp_listening(&self, name: &str, guest_port: u16) -> RuntimeResult<Option<bool>>;
  async fn guest_exec(&self, name: &str, script: &str, timeout: Option<Duration>, sink: Sender<GuestOutput>) -> RuntimeResult<i64>;
  async fn guest_screenshot(&self, name: &str) -> RuntimeResult<GuestScreenshot>;
  async fn guest_display(&self, name: &str) -> RuntimeResult<GuestDisplay>;
  async fn build_image(&self, spec: &BuildSpec, creds: Option<&RegistryCredentials>) -> RuntimeResult<String>;
}

pub struct LocalStartSpec {
  pub name: String,
  pub image: String,
  pub os: String,
  pub cpus: u32,
  pub memory_mb: u64,
  pub disk_size_gb: Option<u32>,
  pub ports: Vec<u16>,
  pub env: BTreeMap<String, String>,
  pub command: Option<Vec<String>>,
  pub ready_timeout: Duration,
  pub firmware: Option<String>,
  pub sidecars: Vec<Sidecar>,
  pub registry_credentials: Option<RegistryCredentials>,
  pub container_runtime: Option<String>,
  pub kind: Option<String>,
  pub runtime: Option<String>,
  pub restrict_network: bool,
  pub gpu: Option<String>,
  pub probes: Vec<LocalProbe>,
  pub ephemeral: bool,
}

pub struct LocalState {
  pub name: String,
  pub runtime_type: String,
  pub image: Value,
  pub host: String,
  pub api_port: u16,
  pub exposed_ports: Option<BTreeMap<String, u16>>,
  pub vnc_port: Option<u16>,
  pub qmp_port: Option<u16>,
  pub grpc_port: Option<u16>,
  pub adb_serial: Option<String>,
  pub sdk_root: Option<String>,
  pub disk_path: Option<String>,
  pub os_type: Option<String>,
  pub vnc_display: Option<i64>,
  pub memory_mb: Option<u64>,
  pub cpu_count: Option<u32>,
  pub arch: Option<String>,
  pub status: String,
  pub created_at: String,
  pub extra: Map<String, Value>,
}

pub struct LocalSummary {
  pub name: String,
  pub backend: String,
  pub status: InstanceStatus,
}

pub enum Location {
  Local,
  Cloud,
  Direct,
  Relay,
  Contrib,
}
impl Location {
  const ALL: [Location; 4] = _;;
  fn as_str(self) -> &'static str;
  fn parse(s: &str) -> Option<Self>;
}

pub struct McpConfig {
  pub url: String,
  pub headers: Vec<(String, String)>,
}
impl McpConfig {
  fn of(endpoint: &ServiceEndpoint, path: Option<&str>) -> Self;
  fn for_url(url: &str, headers: Vec<(String, String)>) -> Result<Self>;
  async fn connect(&self) -> Result<McpClient>;
}

pub enum NetworkMode {
  Default,
  None,
}
impl NetworkMode {
  fn parse(s: &str) -> Result<Self>;
  fn as_str(self) -> &'static str;
}

pub enum Axis {
  On,
  Kind,
  Runtime,
  Image,
}
impl Axis {
  fn as_str(self) -> &'static str;
}

pub struct Capabilities {
  pub name: String,
  pub description: String,
  pub kinds: Vec<KindSupport>,
}
impl Capabilities {
  fn runtimes(&self, kind: Kind) -> Vec<Runtime>;
  fn kinds(&self) -> Vec<Kind>;
  fn kind_of(&self, runtime: &Runtime) -> Option<Kind>;
}

pub struct HostFacts {
  pub gvisor: Option<bool>,
  pub apple_silicon: bool,
}
impl HostFacts {
  fn current() -> Self;
}

pub struct ImageFacts {
  pub os: Option<String>,
  pub variants: Vec<Variant>,
}

pub enum Kind {
  Auto,
  Container,
  Vm,
}
impl Kind {
  fn as_str(self) -> &'static str;
  fn parse(s: &str) -> Result<Self, PlacementError>;
}

pub struct KindSupport {
  pub kind: Kind,
  pub runtimes: Vec<Runtime>,
}

pub enum On {
  Local,
  Cloud,
  Direct(String),
  Relay(String),
  Host(String),
  Provider(String),
}
impl On {
  fn location(&self) -> &str;
  fn is_existing_machine(&self) -> bool;
  fn parse(s: &str) -> Result<Self, PlacementError>;
  fn parse_or_host(s: &str) -> Result<Self, PlacementError>;
}

pub struct PlacementError {
  pub axis: Axis,
  pub given: String,
  pub message: String,
  pub valid: Vec<String>,
}
impl PlacementError {
  fn new(axis: Axis, given: &str, why: String, valid: Vec<String>) -> Self;
}

pub enum Runtime {
  Auto,
  Gvisor,
  Runc,
  Qemu,
  Lume,
  Kubevirt,
  Other(String),
}
impl Runtime {
  const BUILTIN: [Runtime; 5] = _;;
  fn as_str(&self) -> &str;
  fn parse(s: &str) -> Result<Self, PlacementError>;
  fn builtin_kind(&self) -> Option<Kind>;
}

pub struct Selection {
  pub on: On,
  pub kind: Kind,
  pub runtime: Runtime,
  pub reason: String,
}

pub enum PortExposure {
  None,
  Https,
}

pub enum PortTarget {
  Addr { host: String, port: u16 },
  Url(String),
}

pub enum PowerControl {
  Suspend,
  Stop,
}
impl PowerControl {
  fn as_str(self) -> &'static str;
  fn parse(word: &str) -> Option<Self>;
  fn off_state(self) -> PowerState;
}

pub enum PowerState {
  Running,
  Suspended,
  Stopped,
}
impl PowerState {
  fn as_str(self) -> &'static str;
  fn parse(word: &str) -> Option<Self>;
  fn is_off(self) -> bool;
}

pub enum Probe {
  Tcp(u16),
  Http { port: u16, path: String, status: Option<u16> },
}

pub trait Provider: Send + Sync + 'static {
  fn name(&self) -> &'static str;
  fn capabilities(&self) -> ProviderCapabilities;
  fn check_configured(&self) -> Result<()>;
  async fn create(&self, spec: &ProviderCreate) -> Result<ProviderInstance>;
  async fn abort_create(&self, name: &str) -> Result<()>;
  async fn get(&self, id: &str) -> Result<ProviderInstance>;
  async fn list(&self) -> Result<Vec<ProviderInstance>>;
  async fn delete(&self, id: &str) -> Result<()>;
  fn endpoint(&self, instance: &ProviderInstance, port: u16) -> Result<ServiceEndpoint>;
  async fn suspend(&self, _id: &str) -> Result<()>;
  async fn resume(&self, _id: &str) -> Result<ProviderInstance>;
  async fn keep_alive(&self, _id: &str, _duration: Duration) -> Result<()>;
  fn joins_relay(&self) -> bool;
  fn connect_options(&self, _instance: &ProviderInstance, _port: u16) -> Option<Result<ConnectOptions>>;
  fn power(&self) -> Option<PowerControl>;
  async fn stop(&self, _id: &str) -> Result<()>;
  async fn start(&self, _id: &str) -> Result<ProviderInstance>;
}

pub struct ProviderCapabilities {
  pub kinds: Vec<RunKind>,
  pub runtime: &'static str,
  pub arches: Vec<&'static str>,
  pub image_mode: ImageMode,
  pub ports: PortExposure,
  pub command: bool,
  pub env_to_entrypoint: bool,
  pub private_registry: bool,
  pub suspend: bool,
  pub max_cpus: Option<u32>,
  pub max_memory_mb: Option<u64>,
  pub credential_env: &'static [&'static str],
  pub gpus: Vec<GpuOption>,
}

pub struct ProviderCreate {
  pub name: String,
  pub image: ProviderImage,
  pub cpus: u32,
  pub memory_mb: u64,
  pub env: BTreeMap<String, String>,
  pub command: Option<Vec<String>>,
  pub ports: Vec<u16>,
  pub ttl: Option<Duration>,
  pub labels: BTreeMap<String, String>,
  pub registry_credentials: Option<RegistryCredentials>,
  pub timeout: Duration,
  pub runtime: Runtime,
  pub gpu: Option<String>,
}

pub struct ProviderImage {
  pub reference: String,
  pub pinned_ref: String,
  pub digest: String,
  pub kind: RunKind,
  pub arch: String,
  pub spacesd: Option<bool>,
}

pub struct ProviderInstance {
  pub id: String,
  pub name: String,
  pub status: Status,
  pub endpoints: BTreeMap<u16, ServiceEndpoint>,
  pub details: BTreeMap<String, String>,
}
impl ProviderInstance {
  fn new(id: impl Into<String>, name: impl Into<String>, status: Status) -> Self;
}

pub enum ProviderKind {
  Fleet,
  Local,
  Direct,
  Contrib,
}

pub struct HttpProxy { /* private fields */ }
impl HttpProxy {
  async fn start(bind: SocketAddr, router: Arc<dyn ProxyRouter>) -> Result<Self>;
  fn local_addr(&self) -> SocketAddr;
  fn url(&self) -> String;
  fn close(self);
}

pub struct ProxyRoute {
  pub url: String,
  pub headers: Vec<(String, String)>,
}

pub trait ProxyRouter: Send + Sync + 'static {
  fn route(&self, path_and_query: &str) -> RouteFuture;
}

pub enum RouteDecision {
  Forward(ProxyRoute),
  Refuse(u16, String),
}

pub enum RunKind {
  Container,
  Vm,
}
impl RunKind {
  fn as_str(self) -> &'static str;
}

pub enum RuntimeError {
  NotFound(String),
  Unsupported { backend: String, op: String },
  UnsupportedImage(String),
  InsufficientDisk(String),
  InvalidPlacement(PlacementError),
  Other(String),
}

pub struct Sandbox { /* private fields */ }
impl Sandbox {
  async fn mcp_config(&self, service: &str, path: Option<&str>) -> Result<McpConfig>;
  async fn mcp(&self, service: &str, path: Option<&str>) -> Result<McpClient>;
  fn name(&self) -> &str;
  fn image_info(&self) -> Option<&ImageInfo>;
  fn provider(&self) -> ProviderKind;
  fn runtime_type(&self) -> &str;
  fn is_ephemeral(&self) -> bool;
  fn id(&self) -> String;
  fn sandbox_ref(&self) -> SandboxRef;
  fn location(&self) -> &'static str;
  fn expires_at(&self) -> Option<SystemTime>;
  fn provider_details(&self) -> BTreeMap<String, String>;
  fn placement(&self) -> (Kind, Runtime);
  fn fleet_sandbox(&self) -> Option<&BoundSandbox>;
  fn services(&self) -> &BTreeMap<String, u16>;
  fn ports(&self) -> BTreeMap<u16, PortTarget>;
  fn port(&self, port: u16) -> Result<PortTarget>;
  fn service(&self, name: &str) -> Result<Service>;
  fn tunnel(&self) -> Tunnel;
  async fn spacesd(&self) -> Result<SpacesdClient>;
  async fn spacesd_with(&self, o: ConnectOptionsOverride) -> Result<SpacesdClient>;
  fn lacks_spacesd(&self) -> bool;
  async fn guest_exec(&self, script: &str, timeout: Option<Duration>, sink: Sender<GuestOutput>) -> Result<i64>;
  async fn guest_screenshot(&self) -> Result<GuestScreenshot>;
  async fn guest_display(&self) -> Result<GuestDisplay>;
  fn env_token(&self) -> Option<String>;
  fn declares_spacesd(&self, options: &CreateOptions) -> bool;
  async fn wait_spacesd(&self, timeout: Duration) -> Result<()>;
  async fn wait_ready(&self, probes: &[Probe], timeout: Duration) -> Result<()>;
  async fn status(&self) -> Result<Status>;
  async fn suspend(&self) -> Result<()>;
  async fn resume(&self) -> Result<()>;
  async fn restart(&self) -> Result<()>;
  async fn keep_alive(&self, duration: Duration) -> Result<()>;
  fn detach(&self);
  async fn delete(self) -> Result<()>;
}

pub struct Sandboxes { /* private fields */ }
impl Sandboxes {
  fn builder() -> SandboxesBuilder;
  fn state(&self) -> &StateStore;
  fn pools(&self) -> Result<&PoolManager>;
  fn contrib_provider(&self, name: &str) -> Result<&Arc<dyn Provider>>;
  fn clouds(&self) -> Result<&Arc<dyn CloudManager>>;
  fn persisted_details(&self, name: &str) -> BTreeMap<String, String>;
  fn cloud_of_relay_machine(&self, machine: &str) -> Option<(String, String)>;
  fn by_relay_machine(&self, machine: &str) -> Result<Option<String>>;
  fn contrib_providers(&self) -> Vec<Arc<dyn Provider>>;
  async fn create(&self, options: CreateOptions) -> Result<Sandbox>;
  async fn create_cancellable(&self, options: CreateOptions, cancel: CancellationToken) -> Result<Sandbox>;
  async fn create_tracked(&self, options: CreateOptions) -> Result<Sandbox>;
  async fn cancel_create(&self, name: &str) -> Result<Option<String>>;
  fn connect_url(&self, url: &str, token: Option<String>) -> Result<Sandbox>;
  fn connect_url_named(&self, url: &str, token: Option<String>, name: Option<&str>) -> Result<Sandbox>;
  async fn gpu_support(&self, provider: ProviderKind, contrib: Option<&str>) -> Vec<GpuSupport>;
  async fn local_name_in_use(&self, name: &str) -> bool;
  async fn delete_local_instance(&self, name: &str) -> Result<bool>;
  async fn connect(&self, name: &str) -> Result<Sandbox>;
  async fn connect_ref(&self, wanted: &SandboxRef) -> Result<Sandbox>;
  async fn connect_cloud(&self, name: &str, namespace: Option<&str>) -> Result<Sandbox>;
  fn recorded_cloud_image(&self, name: &str, pool: &str) -> Option<ImageInfo>;
  async fn known_refs(&self) -> Result<Vec<SandboxRef>>;
  async fn resolve_ref(&self, wanted: &SandboxRef) -> Result<SandboxRef>;
  async fn resolve_ref_among(&self, wanted: &SandboxRef, extra: Vec<(String, SandboxRef)>) -> Result<SandboxRef>;
  fn remember_direct(&self, name: &str, url: &str) -> Result<()>;
  async fn list(&self) -> Result<Vec<SandboxInfo>>;
  async fn get(&self, name: &str) -> Result<SandboxInfo>;
  async fn suspend(&self, name: &str) -> Result<()>;
  async fn resume(&self, name: &str) -> Result<()>;
  async fn restart(&self, name: &str) -> Result<()>;
  fn power_control(&self, name: &str) -> Option<PowerControl>;
  fn power_state(&self, name: &str) -> Option<PowerState>;
  async fn power_off(&self, name: &str) -> Result<PowerState>;
  async fn power_off_as(&self, name: &str, control: PowerControl) -> Result<PowerState>;
  async fn power_on(&self, name: &str) -> Result<()>;
  async fn delete(&self, name: &str) -> Result<()>;
  async fn keep_alive(&self, name: &str, duration: Duration) -> Result<()>;
}

pub struct SandboxesBuilder { /* private fields */ }
impl SandboxesBuilder {
  fn fleet(self, fleet: FleetClient) -> Self;
  fn pool_manager(self, pools: PoolManager) -> Self;
  fn local(self, runtime: Arc<dyn LocalRuntime>) -> Self;
  fn provider(self, provider: Arc<dyn Provider>) -> Self;
  fn clouds(self, clouds: Arc<dyn CloudManager>) -> Self;
  fn state_dir(self, dir: impl Into<PathBuf>) -> Self;
  fn build(self) -> Sandboxes;
}

pub struct SandboxInfo {
  pub id: String,
  pub name: String,
  pub provider: ProviderKind,
  pub runtime_type: String,
  pub status: Status,
}

pub enum SandboxRef {
  Local { name: String },
  Cloud { name: String, namespace: Option<String> },
  Direct { authority: String },
  Relay { machine_id: String },
  Contrib { provider: String, name: String },
  Bare { name: String },
}
impl SandboxRef {
  fn parse(input: &str) -> Result<Self>;
  fn qualified(location: Location, name: &str) -> Result<Self>;
  fn location(&self) -> Option<Location>;
  fn location_word(&self) -> Option<&str>;
  fn is_qualified(&self) -> bool;
  fn name(&self) -> &str;
  fn namespace_hint(&self) -> Option<&str>;
  fn narrow(self, location: Option<Location>) -> Result<Self>;
}

pub enum SandboxState {
  Fleet(FleetState),
  Local(LocalState),
}
impl SandboxState {
  fn sandbox_ref(&self) -> SandboxRef;
  fn name(&self) -> &str;
  fn runtime_type(&self) -> &str;
  fn status(&self) -> &str;
}

pub struct Service { /* private fields */ }
impl Service {
  async fn mcp_config(&self, path: Option<&str>) -> Result<McpConfig>;
  async fn mcp(&self, path: Option<&str>) -> Result<McpClient>;
  fn name(&self) -> &str;
  fn url(&self) -> &str;
  async fn request(&self, method: &str, path: &str, body: Option<Vec<u8>>, timeout: Duration) -> Result<HttpResponse>;
  async fn endpoint(&self) -> Result<ServiceEndpoint>;
  async fn open(&self, method: &str, path: &str, headers: &[(String, String)], body: RequestBody, head_timeout: Option<Duration>) -> Result<StreamingResponse>;
  async fn request_with_headers(&self, method: &str, path: &str, headers: &[(String, String)], body: Option<Vec<u8>>, timeout: Duration) -> Result<HttpResponse>;
}

pub struct ServiceEndpoint {
  pub url: String,
  pub headers: Vec<(String, String)>,
}
impl ServiceEndpoint {
  fn url_for(&self, path: &str) -> String;
}

pub struct Entry {
  pub key: Key,
  pub value: String,
  pub source: Source,
}

pub struct Key {
  pub name: &'static str,
  pub env: &'static str,
  pub default: &'static str,
  pub description: &'static str,
}

pub struct Resolved {
  pub on: On,
  pub on_source: Source,
  pub kind: Kind,
  pub kind_source: Source,
  pub runtime: Runtime,
  pub runtime_source: Source,
}

pub struct Settings { /* private fields */ }
impl Settings {
  fn load() -> Result<Self, SettingsError>;
  fn load_with(path: impl Into<PathBuf>, env: impl Fn(&str) -> Option<String>) -> Result<Self, SettingsError>;
  fn path(&self) -> &Path;
  fn entry(&self, key: Key) -> Entry;
  fn list(&self) -> Vec<Entry>;
  fn configured(&self, key: Key) -> Option<String>;
  fn lookup(&self, env_var: &str) -> Option<String>;
  fn set(&mut self, key: Key, value: &str) -> Result<String, SettingsError>;
  fn unset(&mut self, key: Key) -> Result<bool, SettingsError>;
  fn default_on(&self) -> Result<(On, Source), SettingsError>;
  fn default_kind(&self) -> Result<(Kind, Source), SettingsError>;
  fn default_runtime(&self) -> Result<(Runtime, Source), SettingsError>;
  fn resolve(&self, on: Option<On>, kind: Option<Kind>, runtime: Option<Runtime>) -> Result<Resolved, SettingsError>;
}

pub struct SettingsError(pub String);

pub enum Source {
  Explicit,
  Env(&'static str),
  Config(PathBuf),
  Default,
}
impl Source {
  fn kind(&self) -> &'static str;
  fn is_user_set(&self) -> bool;
}

pub struct StateStore { /* private fields */ }
impl StateStore {
  fn new(dir: impl Into<PathBuf>) -> Self;
  fn dir(&self) -> &Path;
  fn save(&self, state: &SandboxState) -> Result<()>;
  fn restrict(&self, name: &str) -> Result<()>;
  fn save_fleet_claim(&self, name: &str, pool_name: &str) -> Result<()>;
  fn load(&self, name: &str) -> Option<SandboxState>;
  fn load_raw(&self, name: &str) -> Option<Map<String, Value>>;
  fn update(&self, name: &str, fields: Map<String, Value>) -> Result<()>;
  fn set_status(&self, name: &str, status: &str) -> Result<()>;
  fn delete(&self, name: &str) -> Result<()>;
  fn write_lease(&self, name: &str, pid: u32) -> Result<()>;
  fn remove_lease(&self, name: &str) -> Result<()>;
  fn leases(&self) -> Vec<EphemeralLease>;
  fn list_all(&self) -> Vec<SandboxState>;
}

pub enum Status {
  Running,
  Suspended,
  Stopped,
  Provisioning,
  Unknown(String),
}

pub struct Tunnel { /* private fields */ }
impl Tunnel {
  async fn forward(&self, port: u16) -> Result<Forward>;
}

/// Whether `word` names your own cloud ...
pub fn is_cloud_location(word: &str) -> bool
/// Whether `word` is a contrib location ...
pub fn is_contrib_location(word: &str) -> bool
/// Looks up `name` on Fleet (read-only) as ...
pub async fn local_from_fleet_template(fleet: &FleetClient, name: &str) -> Result<LocalFleetPlan>
/// State-file fields of a sandbox on a ...
pub fn placement_of_backend(backend: &str) -> (Kind, Runtime)
/// Translates a template for the local ...
pub fn plan_from_template(t: &Template) -> Result<LocalFleetPlan>
/// The pool an image string names ...
pub fn pool_image(image: &str) -> Option<&str>
/// Pool `pool`'s template image as an ...
pub async fn pool_image_info(fleet: &FleetClient, pool: &str, creds: Option<&RegistryCredentials>) -> Result<Option<ImageInfo>>
 
// mod byoc
/// The error a cloud word without a ...
pub fn not_built() -> Error
 
// mod fleet_local
/// Parses Kubernetes quantities as MiB ...
pub fn parse_memory_mb(q: &str) -> Option<u64>
/// Readiness probes in a template's ...
pub fn probes_from_json(v: &Value, services: &BTreeMap<String, u16>) -> Vec<Probe>
/// The template name an image string / ...
pub fn template_name(o: &CreateOptions) -> Option<&str>
 
// mod http
/// Reads a streamed response whole.
pub async fn collect(resp: StreamingResponse) -> Result<HttpResponse>
/// A request body from bytes.
pub fn full(body: impl Into<Bytes>) -> RequestBody
/// Hop-by-hop headers (RFC 9110 §7.6.1) a ...
pub fn is_hop_by_hop(name: &str) -> bool
/// Opens a streaming request to `endpoint` ...
pub async fn open(endpoint: &ServiceEndpoint, method: &str, path: &str, headers: &[(String, String)], body: RequestBody, head_timeout: Option<Duration>) -> Result<StreamingResponse>
 
// mod mcp
/// Connects rmcp to `config`.
pub async fn connect(config: &McpConfig) -> Result<McpClient>
/// The protocol revisions cua asks for ...
pub fn preferred_versions() -> Vec<ProtocolVersion>
 
// mod placement
/// The capabilities of `on` (an existing ...
pub fn capabilities(on: &On) -> Capabilities
/// The built-in `cloud` capabilities.
pub fn cloud_capabilities() -> Capabilities
/// The built-in `local` capabilities.
pub fn local_capabilities() -> Capabilities
/// Every location: `local`, `cloud`, then ...
pub fn locations() -> Vec<Capabilities>
/// The registered third-party provider ...
pub fn provider(name: &str) -> Option<Capabilities>
/// Registers a third-party location (--on ...
pub fn register_provider(caps: Capabilities) -> Result<(), PlacementError>
/// Chooses the kind and runtime for a ...
pub fn select(on: &On, kind: Kind, runtime: &Runtime, image: &ImageFacts, host: &HostFacts) -> Result<Selection, PlacementError>
/// Checks a request against the location's ...
pub fn validate(on: &On, kind: Kind, runtime: &Runtime) -> Result<Kind, PlacementError>
 
// mod pool_image
/// A template image as an `ImageInfo` for ...
pub async fn template_image_info(image: &str, runtime: &RuntimeKind, creds: Option<&RegistryCredentials>) -> ImageInfo
 
// mod provider
/// Whether `word` is a provider location ...
pub fn is_provider_location(word: &str) -> bool
/// The error for `--on <word>` when this ...
pub fn not_built(word: &str) -> Error
/// `Error::Unsupported` for a contrib ...
pub fn unsupported(provider: &str, op: impl Into<String>) -> Error
 
// mod proxy
/// A proxy to one upstream base URL with ...
pub async fn forward_to(base: String, headers: Vec<(String, String)>) -> Result<HttpProxy>
/// Joins an upstream base URL and a ...
pub fn join_url(base: &str, path_and_query: &str) -> String
/// Validates that `url` is a plain-HTTP ...
pub fn require_loopback_http(url: &str) -> Result<()>
 
// mod refs
/// The message of Erro ...
pub fn ambiguous_message(name: &str, candidates: &[SandboxRef]) -> String
/// `host:port`, bracketing an IPv6 literal.
pub fn authority(host: &str, port: u16) -> String
/// Canonicalizes any accepted spelling ...
pub fn canonical(input: &str) -> Result<String>
/// Resolves `wanted` among `known` (every ...
pub fn resolve(wanted: &SandboxRef, known: impl IntoIterator<Item = SandboxRef>) -> Result<SandboxRef>
/// `resolve` over `(display name, ref)` ...
pub fn resolve_named(wanted: &SandboxRef, known: impl IntoIterator<Item = (String, SandboxRef)>) -> Result<SandboxRef>
/// Relay machine ids are DNS-label safe ...
pub fn valid_machine_id(id: &str) -> bool
 
// mod settings
/// The cloud pool settings with the user's ...
pub fn auto_pool_config() -> AutoPoolConfig
/// The hint appended to "no cloud ...
pub fn cloud_default_hint(source: &Source) -> Option<String>
/// `$CUA_HOME/config.toml`.
pub fn config_path() -> PathBuf
/// The cua home: `$CUA_HOME`, else ...
pub fn cua_home() -> PathBuf
/// The setting named `name`.
pub fn key(name: &str) -> Result<Key, SettingsError>
/// Checks and normalises a value for `key`.
pub fn normalize(key: Key, value: &str) -> Result<String, SettingsError>
 
// mod state
/// `~/.cua/sandboxes` ( ...
pub fn default_state_dir() -> PathBuf
/// datetime.now(timezo ...
pub fn python_utc_now() -> String
/// Image.from_registry(ref, os_type=... ...
pub fn registry_image_dict(reference: &str, os_type: &str, kind: Option<&str>) -> Value