Skip to main content

RuntimeAdapter

zeroclaw_config::platform

Trait RuntimeAdapter 

pub trait RuntimeAdapter: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn has_filesystem_access(&self) -> bool;
    fn storage_path(&self) -> PathBuf;
    fn supports_long_running(&self) -> bool;
    fn shell_dialect(&self) -> ShellDialect;
    fn build_shell_command(
        &self,
        command: &str,
        workspace_dir: &Path,
    ) -> Result<Command, Error>;

    // Provided methods
    fn has_shell_access(&self) -> bool { ... }
    fn memory_budget(&self) -> u64 { ... }
    fn shell_profile(&self) -> Option<ShellProfile> { ... }
    fn build_shell_command_with_env_keys(
        &self,
        command: &str,
        workspace_dir: &Path,
        env_keys: &[&OsStr],
    ) -> Result<Command, Error> { ... }
}
Expand description

Runtime adapter that abstracts platform differences for the agent.

Implement this trait to port the agent to a new execution environment. The adapter declares platform capabilities (shell access, filesystem, long-running processes) and provides platform-specific implementations for operations like spawning shell commands. The orchestration loop queries these capabilities to adapt its behavior—for example, disabling tool execution on runtimes without shell access.

Implementations must be Send + Sync because the adapter is shared across async tasks on the Tokio runtime.

Required Methods§

Source

fn name(&self) -> &str

Return the human-readable name of this runtime environment.

Used in logs and diagnostics (e.g., "native", "docker", "cloudflare-workers").

Source

fn has_filesystem_access(&self) -> bool

Report whether this runtime supports filesystem read/write.

When false, the agent disables file-based tools and falls back to in-memory storage.

Source

fn storage_path(&self) -> PathBuf

Return the base directory for persistent storage on this runtime.

Memory backends, logs, and other artifacts are stored under this path. Implementations should return a platform-appropriate writable directory.

Source

fn supports_long_running(&self) -> bool

Report whether this runtime supports long-running background processes.

When true, the agent may start the gateway server, heartbeat loop, and other persistent tasks. Serverless runtimes with short execution limits should return false.

Source

fn shell_dialect(&self) -> ShellDialect

Return the shell language accepted by Self::build_shell_command.

This is the source of truth for both shell capability and command policy. Adapters without shell access must return ShellDialect::None.

An adapter must report the dialect it actually runs under, because the command-risk policy consults this to decide platform-specific safety (e.g. accepting a redirect to the nul null device). Docker executes via sh -c and therefore stays POSIX even on Windows; native cron jobs follow the configured runtime dialect.

Source

fn build_shell_command( &self, command: &str, workspace_dir: &Path, ) -> Result<Command, Error>

Build a shell command process configured for this runtime.

Constructs a [tokio::process::Command] that will execute command with workspace_dir as the working directory. Implementations may prepend sandbox wrappers, set environment variables, or redirect I/O as appropriate for the platform.

§Errors

Returns an error if the runtime does not support shell access or if the command cannot be constructed (e.g., missing shell binary).

Provided Methods§

Source

fn has_shell_access(&self) -> bool

Report whether this runtime supports shell command execution.

Shell capability is derived from Self::shell_dialect so adapters cannot report a shell while omitting the language that policy must validate (or report a language while disabling shell tools).

Source

fn memory_budget(&self) -> u64

Return the maximum memory budget in bytes for this runtime.

A value of 0 (the default) indicates no limit. Constrained environments (embedded, serverless) should return their actual memory ceiling so the agent can adapt buffer sizes and caching.

Source

fn shell_profile(&self) -> Option<ShellProfile>

Return what to tell the model about this runtime’s shell, or None when the runtime has no shell.

The system prompt renders this so the model writes commands in the language that will actually interpret them, instead of guessing from the OS name (which does not distinguish cmd.exe from PowerShell on Windows). Because it is answered by the same adapter that builds the command, the reported shell cannot drift from the executed one.

The default derives from Self::shell_dialect, which is correct for adapters with a fixed interpreter. Adapters that let the operator choose an interpreter should override this to name the configured one: sh/bash/zsh differ under POSIX, as do pwsh (7+) and powershell (5.1) under PowerShell.

Source

fn build_shell_command_with_env_keys( &self, command: &str, workspace_dir: &Path, env_keys: &[&OsStr], ) -> Result<Command, Error>

Build a shell command process with runtime-visible environment names.

env_keys contains variable names selected by the caller for passthrough. Implementations that need explicit forwarding, such as container runtimes, should pass only these names across their runtime boundary and rely on the spawned process environment for the values.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§