Trait Environment 

pub trait Environment: Send + Sync {
    // Required methods
    fn read_file<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn read_file_bytes<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn write_file<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        content: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn write_file_bytes<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        content: &'life2 [u8],
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn list_dir<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<FileEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn exists<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn is_dir<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn is_file<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn create_dir<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn delete_file<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn delete_dir<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        recursive: bool,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn grep<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        pattern: &'life1 str,
        path: &'life2 str,
        recursive: bool,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<GrepMatch>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn glob<'life0, 'life1, 'async_trait>(
        &'life0 self,
        pattern: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn root(&self) -> &str;

    // Provided methods
    fn exec<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _command: &'life1 str,
        _timeout_ms: Option<u64>,
    ) -> Pin<Box<dyn Future<Output = Result<ExecResult>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn resolve_path(&self, path: &str) -> String { ... }
}

Environment abstraction for file and command operations.

The SDK’s primitive tools (Read, Write, Grep, Glob, Bash) use this trait to interact with the underlying filesystem or storage backend.

Implementations:

• LocalFileSystem - Standard filesystem (provided by SDK)
• InMemoryFileSystem - For testing (provided by SDK)
• Custom backends (S3, Git, iCloud, etc.)

Required Methods

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

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

Read file contents as UTF-8 string

Errors

Returns an error if the file cannot be read.

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

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

Read file contents as raw bytes

Errors

Returns an error if the file cannot be read.

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

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

Write string content to file (creates or overwrites)

Errors

Returns an error if the file cannot be written.

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

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

Write raw bytes to file

Errors

Returns an error if the file cannot be written.

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

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

List directory contents

Errors

Returns an error if the directory cannot be read.

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

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

Check if path exists

Errors

Returns an error if existence cannot be determined.

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

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

Check if path is a directory

Errors

Returns an error if the check fails.

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

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

Check if path is a file

Errors

Returns an error if the check fails.

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

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

Create directory (including parents)

Errors

Returns an error if the directory cannot be created.

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

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

Delete file

Errors

Returns an error if the file cannot be deleted.

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

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

Delete directory (must be empty unless recursive)

Errors

Returns an error if the directory cannot be deleted.

fn grep<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, pattern: &'life1 str, path: &'life2 str, recursive: bool, ) -> Pin<Box<dyn Future<Output = Result<Vec<GrepMatch>>> + Send + 'async_trait>>

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

Search for pattern in files (like ripgrep)

Errors

Returns an error if the search fails.

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

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

Find files matching glob pattern

Errors

Returns an error if the glob operation fails.

fn root(&self) -> &str

Get the root/working directory for this environment

Provided Methods

fn exec<'life0, 'life1, 'async_trait>( &'life0 self, _command: &'life1 str, _timeout_ms: Option<u64>, ) -> Pin<Box<dyn Future<Output = Result<ExecResult>> + Send + 'async_trait>>

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

Execute a shell command

Not all environments support this. Default implementation returns an error.

Errors

Returns an error if command execution is not supported or fails.

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

Resolve an input path to an absolute path clamped to root.

This is the path-policy boundary for primitive tools: it interprets the model-supplied path against the environment root and guarantees the result can never lexically escape that root. Relative inputs are joined to the root; absolute inputs are accepted only when they already fall inside the root, otherwise they (and any .. traversal) are clamped back inside it. So with root = /workspace, both ../../etc/passwd and /etc/passwd resolve to a path under /workspace, never to the host’s /etc/passwd.

Security

The clamp is lexical (it does not touch the filesystem) so it cannot detect a symlink inside the root that points outside it. Callers that resolve against a real filesystem and need a symlink-proof boundary must use resolve_within_root_secure, which canonicalizes the path and verifies containment after following links.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors

impl Environment for NullEnvironment