anyclaw-sdk-runtime 0.1.0

use crate::error::RuntimeSdkError;
use crate::types::{
    ExecRequest, ExecResult, RuntimeHealthStatus, RuntimeInitializeParams, RuntimeInitializeResult,
};

/// Trait for building runtime extensions.
///
/// A runtime manages the execution environment for agent sandboxes:
/// containers, networking, proxy, and process execution. The supervisor
/// communicates with the runtime via JSON-RPC over stdio.
///
/// The runtime is responsible for:
/// - Setting up the environment (container, network, proxy) on [`start`](Runtime::start)
/// - Spawning processes inside the environment via [`exec`](Runtime::exec)
/// - Reporting health status
/// - Tearing down cleanly on [`stop`](Runtime::stop)
///
/// The supervisor uses `exec()` to spawn agent worker processes. It does not
/// know or care whether the environment is Docker, Podman, Firecracker, or
/// a local process — it only uses this trait interface.
pub trait Runtime: Send + 'static {
    /// Initialize and start the runtime environment.
    ///
    /// Called once during boot. The runtime should:
    /// - Create the execution environment (container, VM, etc.)
    /// - Set up networking (proxy, DNAT rules, network isolation)
    /// - Return environment info (env vars for processes, workspace root)
    fn start(
        &mut self,
        params: RuntimeInitializeParams,
    ) -> impl std::future::Future<Output = Result<RuntimeInitializeResult, RuntimeSdkError>> + Send;

    /// Execute a process inside the runtime environment.
    ///
    /// The supervisor calls this to spawn agent worker processes. The runtime
    /// starts the process and returns connection info (socket paths) for
    /// bidirectional stdio communication.
    ///
    /// Multiple concurrent `exec` calls are expected (worker pool).
    fn exec(
        &self,
        request: ExecRequest,
    ) -> impl std::future::Future<Output = Result<ExecResult, RuntimeSdkError>> + Send;

    /// Report current health status.
    ///
    /// Called periodically by the supervisor's health loop.
    fn health(&self) -> impl std::future::Future<Output = RuntimeHealthStatus> + Send;

    /// Gracefully stop the runtime environment.
    ///
    /// The supervisor calls this during shutdown. The runtime should:
    /// - Drain/kill all running processes
    /// - Tear down networking (remove DNAT rules, delete network)
    /// - Remove the container/VM
    fn stop(&mut self) -> impl std::future::Future<Output = Result<(), RuntimeSdkError>> + Send;

    /// Kill a specific process by its ID.
    ///
    /// Called when the supervisor needs to terminate a single worker
    /// (e.g., crash recovery, scaling down).
    fn kill(
        &self,
        process_id: &str,
    ) -> impl std::future::Future<Output = Result<(), RuntimeSdkError>> + Send;
}