Trait Substrate 

pub trait Substrate: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn run_command<'life0, 'life1, 'async_trait>(
        &'life0 self,
        cmd: &'life1 str,
        timeout_s: Option<f64>,
    ) -> Pin<Box<dyn Future<Output = Result<CommandOutput, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn read_text<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn write_text<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        content: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn read_bytes<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        offset: Option<u64>,
        len: Option<u64>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn write_bytes<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        bytes: &'life2 [u8],
    ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;

    // Provided methods
    fn path_state<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = PathState> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn is_local(&self) -> bool { ... }
    fn display_path(&self, path: &str) -> String { ... }
    fn pty_start<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _cmd: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn pty_input<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _id: &'life1 str,
        _data: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn pty_read<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn pty_resize<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _id: &'life1 str,
        _rows: u16,
        _cols: u16,
    ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn pty_kill<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
}

The environment an agent acts within. Bound once to a Runtime; the agent never chooses per-tool where execution lands.

Kept minimal on purpose — exec + file I/O, with PTY as an optional capability that defaults to “unsupported”. list_dir/find/grep/edit are reducible to these primitives and live as convenience tools, mirroring the vm MCP bridge.

Required Methods

fn name(&self) -> &str

Environment name: "local", "vm", "docker:...", etc.

fn run_command<'life0, 'life1, 'async_trait>( &'life0 self, cmd: &'life1 str, timeout_s: Option<f64>, ) -> Pin<Box<dyn Future<Output = Result<CommandOutput, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run a one-shot command, returning stdout/stderr/exit_code.

fn read_text<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read a UTF-8 text file in full.

fn write_text<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 str, content: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Write (truncate) a UTF-8 text file.

fn read_bytes<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, offset: Option<u64>, len: Option<u64>, ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read raw bytes, optionally a window [offset, offset+len).

fn write_bytes<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 str, bytes: &'life2 [u8], ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Write (truncate) raw bytes.

Provided Methods

fn path_state<'life0, 'life1, 'async_trait>( &'life0 self, _path: &'life1 str, ) -> Pin<Box<dyn Future<Output = PathState> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Determine whether path exists without requiring it to be valid UTF-8. The default is intentionally unknown: custom substrates can retain their existing trait implementation, while guarded writes fail closed until the adapter supplies a trustworthy presence check.

fn is_local(&self) -> bool

Whether this substrate is the host process itself. Convenience tools (list_dir/find_files/grep_files) that walk a directory tree use this to keep their byte-identical host-fs implementation on the local path; non-local environments fall back to composing on run_command.

fn display_path(&self, path: &str) -> String

How a path should appear in tool-result metadata for this environment. Pure/synchronous; no I/O. The default echoes the input unchanged. The local environment overrides this to reproduce the historic behavior of reporting the resolved absolute path (relative paths joined to the host CWD). Not a capability — just display canonicalization.

fn pty_start<'life0, 'life1, 'async_trait>( &'life0 self, _cmd: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn pty_input<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _id: &'life1 str, _data: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

fn pty_read<'life0, 'life1, 'async_trait>( &'life0 self, _id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn pty_resize<'life0, 'life1, 'async_trait>( &'life0 self, _id: &'life1 str, _rows: u16, _cols: u16, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn pty_kill<'life0, 'life1, 'async_trait>( &'life0 self, _id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Dyn Compatibility

This trait is dyn compatible.

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

Implementors

impl Substrate for LocalSubstrate

impl Substrate for McpSubstrate