darman
9929941748
Include Luna AI Assistant design docs covering channels, configuration, core architecture, memory, scheduler, and skills. Add reference docs from OpenClaw and ZeroClaw projects, plus Mistral and OpenAI API specs.
104 lines
5.1 KiB
Markdown
104 lines
5.1 KiB
Markdown
# Runtime Adapters
|
|
|
|
ZeroClaw uses the `RuntimeAdapter` trait to abstract the execution environment from the core agent logic. This abstraction allows the same agent code to run natively on a host machine, inside a Docker container, or on restricted edge runtimes without modification to the core loop.
|
|
|
|
***
|
|
|
|
## RuntimeAdapter Trait
|
|
|
|
The `RuntimeAdapter` trait defines the capabilities and interface for any environment ZeroClaw operates within. It is designed to be `Send + Sync` to allow safe sharing across asynchronous tasks.
|
|
|
|
```rust
|
|
pub trait RuntimeAdapter: Send + Sync {
|
|
/// Return the human-readable name of this runtime environment.
|
|
fn name(&self) -> &str;
|
|
|
|
/// Report whether this runtime supports shell command execution.
|
|
fn has_shell_access(&self) -> bool;
|
|
|
|
/// Report whether this runtime supports filesystem read/write.
|
|
fn has_filesystem_access(&self) -> bool;
|
|
|
|
/// Return the base directory for persistent storage on this runtime.
|
|
fn storage_path(&self) -> PathBuf;
|
|
|
|
/// Report whether this runtime supports long-running background processes.
|
|
fn supports_long_running(&self) -> bool;
|
|
|
|
/// Return the maximum memory budget in bytes for this runtime.
|
|
fn memory_budget(&self) -> u64 {
|
|
0
|
|
}
|
|
|
|
/// Build a shell command process configured for this runtime.
|
|
fn build_shell_command(
|
|
&self,
|
|
command: &str,
|
|
workspace_dir: &Path,
|
|
) -> anyhow::Result<tokio::process::Command>;
|
|
}
|
|
```
|
|
|
|
***
|
|
|
|
## NativeRuntime
|
|
|
|
The `NativeRuntime` implementation provides direct execution on the host operating system. It represents the least restrictive environment and is typically used for local development or trusted server environments.
|
|
|
|
* **Shell Access**: Returns `true`. Commands are executed directly via the system shell.
|
|
* **Filesystem Access**: Returns `true`. The agent can interact with any path permitted by the user's OS permissions.
|
|
* **Memory Limits**: Typically returns `0` (unlimited), relying on the OS to manage process resources.
|
|
* **Command Building**: Spawns `tokio::process::Command` directly with the requested command string.
|
|
|
|
***
|
|
|
|
## DockerRuntime
|
|
|
|
The `DockerRuntime` provides isolated execution by wrapping operations in Docker containers. This is the preferred runtime for untrusted code execution or when strict environment reproducibility is required.
|
|
|
|
* **Shell Access**: Configurable, but generally `true`. Commands are wrapped in `docker exec` calls targeting a specific container.
|
|
* **Filesystem Access**: Restricted to the volumes and mounts defined in the container configuration.
|
|
* **Memory Budgets**: Returns the memory limits defined for the container, allowing the agent to adapt its cache and buffer sizes.
|
|
* **Command Building**: Instead of direct execution, it constructs a command that executes inside the container namespace, often involving complex argument escaping and environment variable injection.
|
|
|
|
***
|
|
|
|
## Capability Querying
|
|
|
|
The agent loop queries the `RuntimeAdapter` before attempting to execute tools or background tasks. This ensures that the agent fails gracefully or skips unavailable functionality based on its environment.
|
|
|
|
1. **Tool Pre-flight**: Before executing a shell tool, the orchestrator checks `has_shell_access()`.
|
|
2. **Persistence Check**: Before initializing disk-based state, the agent checks `has_filesystem_access()`.
|
|
3. **Background Services**: The heartbeat loop and gateway server only start if `supports_long_running()` returns `true`.
|
|
|
|
This pattern prevents runtime errors by verifying environmental support at the logic gate rather than deep within the execution stack.
|
|
|
|
***
|
|
|
|
## Command Building
|
|
|
|
The `build_shell_command` method is the primary bridge between the agent and the OS. It takes a raw command string and a workspace directory, returning a configured `tokio::process::Command`.
|
|
|
|
Runtimes use this to:
|
|
* Prepend sandbox wrappers (e.g., `firejail` or `sudo -u limited`).
|
|
* Set environment variables specific to the runtime (e.g., `PATH` or `HOME`).
|
|
* Handle working directory mapping (especially important in Docker where host paths and container paths differ).
|
|
|
|
***
|
|
|
|
## Tool Routing
|
|
|
|
Tool execution can be routed through specific runtimes based on security requirements. A "Security Router" might send filesystem operations to a native runtime for speed while routing unknown shell scripts to a Docker runtime for isolation. This routing logic relies on the standardized interface provided by the `RuntimeAdapter`.
|
|
|
|
***
|
|
|
|
## Relevance to Luna
|
|
|
|
Luna currently operates with implicit native execution. As Luna evolves to support tool execution and autonomous tasks, implementing an `IRuntimeAdapter` interface will be critical for safety.
|
|
|
|
* **Isolation**: Adopting a pattern similar to ZeroClaw's `DockerRuntime` would allow Luna to run generated code in a sandbox without risking the host system.
|
|
* **Cross-Platform**: A runtime abstraction simplifies porting Luna to different OSs or containerized environments.
|
|
* **Security Integration**: This pairs with [[Security]] patterns to ensure that capabilities are not just checked by the runtime, but also verified against user-defined security policies.
|
|
|
|
Cross-links: [[Core]], [[Skills]], [[Configuration]].
|