Cersei Rust SDK

cersei-vms provides a pluggable sandbox runtime layer for Cersei coding agents. It prevents agents from executing shell commands or editing files directly on the host machine, providing isolation and security.

Key Capabilities

• Sandbox Runtimes: Supports different execution environments via the SandboxRuntime trait.
• Per-sandbox Surface: Each Sandbox provides access to commands() (for running, streaming, or signaling processes) and filesystem() (for reading, writing, listing, and managing files).
• Cross-sandbox Primitives: Allows parallel agents to communicate and share state safely through host-mediated primitives without direct network links:
  • Volume: Host-mounted directories.
  • Mailbox: Broadcast pub/sub messaging.
  • KvStore: Versioned Content-Addressable Storage (CAS).
• Snapshots: Capture the state of a sandbox using Sandbox::snapshot() -> SnapshotId and restore it using SandboxRuntime::restore(&id). For Docker, this uses docker commit; for local runtimes, it copies the directory. Manifests are stored in ~/.cersei/vms/snapshots/.

use cersei::prelude easily;
use cersei::vms::prelude easily;

The abstract-cli (referred to as 'Abstract' in benchmarks) is designed for high-performance agentic workflows. Key architectural advantages include:

• Low Startup Latency: Average startup time is ~32ms, significantly faster than Claude Code (~266ms).
• Minimal Resource Footprint: A single 6.0 MB static Rust binary with a median peak memory (RSS) of ~4.9 MB.
• High-Speed Tool Dispatch: SDK-level tool execution (e.g., Read, Write, Edit) occurs in sub-millisecond time (e.g., Read at 0.09ms), whereas Claude Code relies on process forking (~265ms).
• Efficient Memory Management: Uses a Graph-based memory backend (Grafeo) that provides relationship-aware queries with negligible overhead (<3%) compared to file-only scans.
• Lean System Prompts: Uses ~2,200 tokens for system prompts and tool definitions, saving approximately 5,800 tokens per session compared to Claude Code.

AgentRL is a self-evolving orchestration layer for Cersei that transforms single-shot coding agents into self-improving systems. When an agent fails a task, AgentRL performs the following loop:

1. Failure Tracing: The ExecutionGraph distills a FailureTrace from the agent's event stream.
2. Planning: A PlannerAgent generates multiple fix proposals based on the trace.
3. Sandboxed Execution: Proposals are executed in isolated environments (using cersei-vms or local directories) to prevent interference.
4. Verification: An independent Verifier checks if the proposal actually works.
5. Promotion & Registration: The successful proposal is promoted to the working directory and registered in the ToolRegistry as a reusable DynamicTool.

This allows the agent to solve similar future problems via tool recall rather than re-derivation, reducing LLM spend and latency.

A Provider is an abstraction over an LLM backend. It encapsulates authentication, request formatting, SSE (Server-Sent Events) streaming, and capability discovery. By using the Provider trait, Cersei can interact with different LLM backends (like Anthropic or OpenAI) using a unified interface.

The Provider trait requires implementing the following methods:

• name(): Returns the provider's name.
• context_window(model): Returns the token limit for a specific model.
• capabilities(model): Returns a ProviderCapabilities struct describing supported features (streaming, tool use, etc.).
• complete(request): Asynchronous method for streaming responses via CompletionStream.
• complete_blocking(request): Asynchronous method for non-streaming responses via CompletionResponse.
• count_tokens(messages, model): Returns the token count for a set of messages.

#[async_trait]
pub trait Provider: Send + Sync {
    fn name(&self) -> &str;
    fn context_window(&self, model: &str) -> u64;
    fn capabilities(&self, model: &str) -> ProviderCapabilities;
    async fn complete(&self, request: CompletionRequest) -> Result<CompletionStream>;
    async fn complete_blocking(&self, request: CompletionRequest) -> Result<CompletionResponse>;
    async fn count_tokens(&self, messages: &[Message], model: &str) -> Result<u64>;
}

The Agent::run("prompt") method initiates an agentic loop that manages the lifecycle of a conversation. The flow follows these steps:

1. Session Loading: If Memory is configured, the session is loaded.
2. Completion Request: An LLM request is built and sent via a Provider.
3. Stream Accumulation: A StreamAccumulator collects StreamEvents (like TextDelta, ThinkingDelta, or ToolUse).
4. Turn Processing: Once a model turn completes, the agent checks the stop_reason:
   • EndTurn: The loop breaks.
   • ToolUse: The agent dispatches tools. For each tool, it runs PreToolUse hooks, checks the PermissionPolicy, executes Tool.execute(), and runs PostToolUse hooks.
   • MaxTokens: The agent injects a continuation and continues the loop.
5. Session Saving: If Memory is configured, the updated session is saved.
6. Output: Returns an AgentOutput containing the message, usage, stop reason, turns, and tool calls.

Memory in Cersei provides session persistence and retrieval, which allows for resumable conversations and long-term knowledge storage. By associating an Agent with a Memory backend and a specific session_id, the agent can automatically load previous conversation history when a new session starts and save the updated history when the session completes.

Agent Lifecycle with Memory

1. On agent.run(): If memory and session_id are configured, the agent calls memory.load(session_id) and prepends existing messages to the current conversation.
2. During execution: New messages (user prompts, assistant responses, and tool results) are accumulated.
3. On completion: The agent calls memory.store(session_id, all_messages) to persist the full conversation.

Emitted Events

You can monitor the memory lifecycle via these events:

• AgentEvent::SessionLoaded { session_id, message_count }: Emitted after loading previous messages.
• AgentEvent::SessionSaved { session_id }: Emitted after persisting the conversation.