Skip to main content

Sandbox

tiny_agent::sandbox

Trait Sandbox 

Source 
pub trait Sandbox: Send + Sync {
    // Required methods
    fn open<'life0, 'async_trait>(
        self: Arc<Self>,
        session_id: &'life0 str,
    ) -> Pin<Box<dyn Future<Output = Result<Arc<dyn Sandbox>, SandboxError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn execute<'life0, 'life1, 'async_trait>(
        &'life0 self,
        command: &'life1 str,
        on_output: Option<OutputCallback>,
    ) -> Pin<Box<dyn Future<Output = Result<ExecOutput, SandboxError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn save<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<(), SandboxError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn fork<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _to_session: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), SandboxError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
}
Expand description

agent 工具的执行环境抽象。

所有会触达“外部世界“(进程、文件系统)的工具都应通过 Sandbox::execute 走这一层,这样替换 sandbox 实现(真机 / bashkit / 容器)时工具代码无需改动。

agent 的执行环境抽象。

一个 Sandbox 实例绑定一个会话:execute 负责执行, save 持久化自身状态,fork 把自身复制给另一个会话。

框架完全不规定状态怎么序列化:可能是一坨字节、一个容器 image id、一个远程 快照引用……都藏在实现内部,trait 不暴露任何序列化格式。不需要持久化的后端 (如 HostSandbox)用默认实现即可。

Sandbox::open 是按 session 打开 / 恢复 / 初始化执行环境的入口。 对无会话状态的实现(如 HostSandbox),可直接返回自己;对需要快照 / 挂载 / bootstrap 的实现,则在这里按 session_id 恢复出真正的 session-bound sandbox。

Required Methods§

Source

fn open<'life0, 'async_trait>( self: Arc<Self>, session_id: &'life0 str, ) -> Pin<Box<dyn Future<Output = Result<Arc<dyn Sandbox>, SandboxError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

打开或恢复某个 session 对应的 sandbox。实现应保持幂等:同一 session 多次 open 应恢复到同一份状态,并且 bootstrap 逻辑不应重复破坏环境。

Source

fn execute<'life0, 'life1, 'async_trait>( &'life0 self, command: &'life1 str, on_output: Option<OutputCallback>, ) -> Pin<Box<dyn Future<Output = Result<ExecOutput, SandboxError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

执行一条命令并返回结果。

文件读写等操作由各工具自行拼成命令(如 cat、printf),本层只负责执行。

on_output 可选:传入则在执行期间每产出一块输出就回调一次(用于实时刷屏 / 增量收集); 不关心实时输出的调用方传 None。无论是否流式,完整结果都在末尾通过返回值给出。

Provided Methods§

Source

fn save<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), SandboxError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

持久化自身当前状态。实例自己知道 session_id 和存到哪里,故无参。 默认不做事(真机文件系统本来就持久)。

Source

fn fork<'life0, 'life1, 'async_trait>( &'life0 self, _to_session: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), SandboxError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

把自身当前状态复制给另一个会话 to_session。默认不支持。

Dyn Compatibility§

This trait is dyn compatible.

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

Implementors§