saorsa-agent

Agent runtime with tool execution, session management, context engineering, and extension system for building AI coding agents.

Overview

saorsa-agent provides the runtime for AI agents that can execute tools, manage sessions, and integrate with terminal UIs. It builds on saorsa-ai for LLM communication and adds:

• Agent loop - Turn-based conversation with streaming, tool execution, and automatic continuation
• 7 built-in tools - bash, read, write, edit, grep, find, ls
• Session management - Tree-structured sessions with branching, forking, auto-save, and resume
• Context engineering - AGENTS.md/SYSTEM.md discovery, context compaction, merge strategies
• Skills system - On-demand capability injection from markdown files
• Templates - Prompt templates with variable substitution and conditionals
• Extension system - Lifecycle hooks, custom tools, commands, keybindings, and widgets
• Event system - Typed events for UI integration (text deltas, tool calls, turn lifecycle)

Quick Start

[dependencies]
saorsa-agent = "0.1"
saorsa-ai = "0.1"
tokio = { version = "1", features = ["full"] }

Note: saorsa-agent is provider-agnostic. Any Box<dyn saorsa_ai::StreamingProvider> works, including in-process providers like saorsa_ai::MistralrsProvider (feature-gated behind saorsa-ai's mistralrs feature).

Running the Agent Loop

use saorsa_agent::{AgentConfig, AgentLoop, default_tools, event_channel};
use saorsa_ai::{ProviderConfig, ProviderKind, ProviderRegistry};

#[tokio::main]
async fn main() -> saorsa_agent::Result<()> {
    // Create the LLM provider
    let config = ProviderConfig::new(
        ProviderKind::Anthropic,
        std::env::var("ANTHROPIC_API_KEY").expect("set ANTHROPIC_API_KEY"),
        "claude-sonnet-4",
    );
    let registry = ProviderRegistry::default();
    let provider = registry.create(config)?;

    // Set up agent
    let agent_config = AgentConfig::default();
    let tools = default_tools(std::env::current_dir()?);
    let (tx, mut rx) = event_channel(64);

    let mut agent = AgentLoop::new(provider, agent_config, tools, tx);

    // Consume events in a background task
    tokio::spawn(async move {
        while let Some(event) = rx.recv().await {
            match event {
                saorsa_agent::AgentEvent::TextDelta { text } => {
                    print!("{text}");
                }
                saorsa_agent::AgentEvent::ToolCall { name, .. } => {
                    eprintln!("[calling {name}...]");
                }
                _ => {}
            }
        }
    });

    // Run the agent
    let response = agent.run("List the files in the current directory").await?;
    println!("\nFinal: {response}");

    Ok(())
}

Agent Loop

The AgentLoop is the core runtime. It sends messages to an LLM, streams responses, executes tool calls, and loops until the model stops or the turn limit is reached.

Turn Lifecycle

1. TurnStart - Begin a new turn
2. Stream response - Receive text deltas and tool call fragments
3. TextComplete - Full text assembled
4. Tool execution - If StopReason::ToolUse, execute tools and add results to history
5. TurnEnd - Turn complete, loop if more tools needed

Configuration

use saorsa_agent::AgentConfig;

let config = AgentConfig::new("claude-sonnet-4")
    .system_prompt("You are a helpful coding assistant.")
    .max_turns(10)    // Maximum tool-use turns per run()
    .max_tokens(4096); // Max output tokens per completion

Defaults:

Built-in Tools

Tool Trait

All tools implement the async Tool trait:

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn input_schema(&self) -> serde_json::Value;
    async fn execute(&self, input: serde_json::Value) -> Result<String>;
}

Tool Registry

use saorsa_agent::{ToolRegistry, default_tools};

// Create registry with all 7 built-in tools
let tools = default_tools("/path/to/working/dir");
assert_eq!(tools.len(), 7);

// Or build a custom registry
let mut registry = ToolRegistry::new();
registry.register(Box::new(my_custom_tool));

Bash Tool

Execute shell commands with timeout and output limits.

{ "command": "cargo test", "working_directory": "/project", "timeout_ms": 60000 }

Captures both stdout and stderr. Output is truncated at safe UTF-8 boundaries if it exceeds the limit.

Read Tool

Read file contents with optional line ranges.

{ "file_path": "src/main.rs", "line_range": "10-20" }

Write Tool

Write content to files with automatic directory creation and diff display.

{ "file_path": "src/new_file.rs", "content": "fn main() {}" }

Creates parent directories automatically. Shows a unified diff when updating existing files. Reports "No changes" if content is identical.

Edit Tool

Surgical text replacement with ambiguity detection.

{ "file_path": "src/lib.rs", "old_text": "fn old_name()", "new_text": "fn new_name()", "replace_all": false }

Grep Tool

Search file contents with regex patterns.

{ "pattern": "fn\\s+\\w+", "path": "src/", "case_insensitive": false }

Find Tool

Find files by glob pattern.

{ "pattern": "*.rs", "path": "src/" }

Ls Tool

List directory contents with metadata.

{ "path": "src/", "recursive": true }

Event System

The agent emits typed events for UI integration:

pub enum AgentEvent {
    TurnStart { turn: u32 },
    TextDelta { text: String },
    TextComplete { text: String },
    ToolCall { id: String, name: String, input: serde_json::Value },
    ToolResult { id: String, name: String, output: String, success: bool },
    TurnEnd { turn: u32, reason: TurnEndReason },
    Error { message: String },
}

pub enum TurnEndReason {
    EndTurn,    // Model finished naturally
    ToolUse,    // Tools executed, continuing
    MaxTurns,   // Turn limit reached
    MaxTokens,  // Token limit reached
    Error,      // Error occurred
}

Events are delivered via a tokio mpsc channel:

let (tx, mut rx) = event_channel(64);
let mut agent = AgentLoop::new(provider, config, tools, tx);

// UI task reads events
while let Some(event) = rx.recv().await {
    match event {
        AgentEvent::TextDelta { text } => { /* stream to display */ }
        AgentEvent::ToolCall { name, input, .. } => { /* show tool activity */ }
        AgentEvent::ToolResult { success, .. } => { /* show result status */ }
        AgentEvent::TurnEnd { reason, .. } => { /* update UI state */ }
        _ => {}
    }
}

Session Management

Session Storage

Sessions are persisted to disk in a structured format:

~/.saorsa/sessions/
  <session-uuid>/
    manifest.json       # SessionMetadata (title, tags, timestamps)
    tree.json           # SessionNode (parent/child relationships)
    messages/
      0-user.json       # Chronological message files
      1-assistant.json
      2-tool_call.json
      3-tool_result.json

use saorsa_agent::{SessionId, SessionMetadata, SessionStorage};

let storage = SessionStorage::new()?;
let id = SessionId::new();

// Save/load metadata
storage.save_manifest(&id, &metadata)?;
let metadata = storage.load_manifest(&id)?;

// Save/load messages
storage.save_message(&id, 0, &message)?;
let messages = storage.load_messages(&id)?;

Tree-Structured Sessions

Sessions form a tree: forking creates a child session that shares history up to the fork point.

use saorsa_agent::{fork_session, build_session_tree, render_tree, TreeRenderOptions};

// Fork from an existing session
let child_id = fork_session(&storage, &parent_id)?;

// Build and render the session tree
let tree = build_session_tree(&storage)?;
let output = render_tree(&tree, &TreeRenderOptions::default());
println!("{output}");

Resume & Find

use saorsa_agent::{find_last_active_session, find_session_by_prefix, restore_session};

// Resume the most recent session
let id = find_last_active_session(&storage)?;
let messages = restore_session(&storage, &id)?;

// Find by 8-character prefix
let id = find_session_by_prefix(&storage, "a1b2c3d4")?;

Auto-Save

Sessions auto-save with debouncing and atomic writes (temp file + rename):

// Auto-fork when editing a message mid-conversation
let forked = auto_fork_on_edit(&storage, &session_id, edit_index)?;

Bookmarks

use saorsa_agent::{Bookmark, BookmarkManager};

let mut bookmarks = BookmarkManager::new(&storage);
bookmarks.add(Bookmark::new(session_id, "Important conversation"))?;

Export

use saorsa_agent::export_to_html;

let html = export_to_html(&storage, &session_id)?;
std::fs::write("session.html", html)?;

Context Engineering

AGENTS.md / SYSTEM.md Discovery

The agent searches for context files in precedence order:

1. Current working directory (highest precedence)
2. Parent directories (walking up to root/home)
3. ~/.saorsa/ (global, lowest precedence)

use saorsa_agent::ContextDiscovery;

let discovery = ContextDiscovery::new()?;

// Find all AGENTS.md files (highest precedence first)
let agents_files = discovery.discover_agents_md();

// Find all SYSTEM.md files
let system_files = discovery.discover_system_md();

Context Bundle

Combine discovered context into a single bundle:

use saorsa_agent::ContextBundle;

let context = ContextBundle::builder()
    .agents(agents_context)   // From AGENTS.md
    .system(system_context)   // From SYSTEM.md
    .user("Additional context") // Ad-hoc context
    .build();

SYSTEM.md Modes

Context Compaction

When conversations approach the context window limit:

use saorsa_agent::{CompactionConfig, CompactionStrategy, compact};

let config = CompactionConfig::default();
let compacted = compact(&messages, &config)?;

Skills System

Skills inject specialized knowledge on demand from markdown files:

use saorsa_agent::SkillRegistry;

// Discover skills from ~/.saorsa/skills/
let skills = SkillRegistry::discover_skills();

for skill in &skills {
    println!("{}: {}", skill.name, skill.description);
}

Skill files are markdown with front matter for metadata (name, description, trigger keywords).

Templates

Prompt templates with variable substitution:

use saorsa_agent::{TemplateEngine, render_simple};
use std::collections::HashMap;

// Simple variable substitution
let mut ctx = HashMap::new();
ctx.insert("name".to_string(), "Alice".to_string());
ctx.insert("model".to_string(), "claude-sonnet-4".to_string());

let result = render_simple("Hello {{name}}, using {{model}}!", &ctx)?;
// "Hello Alice, using claude-sonnet-4!"

Template syntax:

• Variables: {{name}}
• Conditionals: {{#if var}}...{{/if}}
• Negated: {{#unless var}}...{{/unless}}

Built-in templates are available via get_builtin() and list_builtins(). User templates are loaded from ~/.saorsa/templates/*.md.

Extension System

Extensions add custom functionality via lifecycle hooks:

use saorsa_agent::Extension;

pub trait Extension: Send + Sync {
    fn name(&self) -> &str;
    fn version(&self) -> &str;
    fn on_load(&mut self) -> Result<()>;
    fn on_unload(&mut self) -> Result<()>;
    fn on_tool_call(&mut self, tool: &str, args: &str) -> Result<Option<String>>;
    fn on_message(&mut self, message: &str) -> Result<Option<String>>;
    fn on_turn_start(&mut self) -> Result<()>;
    fn on_turn_end(&mut self) -> Result<()>;
}

Extension Registry

use saorsa_agent::{ExtensionRegistry, shared_registry};

// Thread-safe shared registry
let registry = shared_registry();

// Register an extension
{
    let mut reg = registry.write().unwrap();
    reg.register(Box::new(my_extension))?;
}

// Notify all extensions of events
{
    let mut reg = registry.write().unwrap();
    reg.notify_turn_start()?;
    let responses = reg.notify_tool_call("bash", "{\"command\": \"ls\"}")?;
    reg.notify_turn_end()?;
}

Specialized Registries

Extensions are loaded from ~/.saorsa/extensions/.

Custom Tools

Implement the Tool trait to add your own tools:

use saorsa_agent::Tool;
use async_trait::async_trait;

struct MyTool;

#[async_trait]
impl Tool for MyTool {
    fn name(&self) -> &str { "my_tool" }

    fn description(&self) -> &str {
        "Does something useful"
    }

    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "query": { "type": "string", "description": "The query" }
            },
            "required": ["query"]
        })
    }

    async fn execute(&self, input: serde_json::Value) -> saorsa_agent::Result<String> {
        let query = input["query"].as_str().unwrap_or("");
        Ok(format!("Result for: {query}"))
    }
}

// Register it
let mut registry = saorsa_agent::ToolRegistry::new();
registry.register(Box::new(MyTool));

Error Handling

pub enum SaorsaAgentError {
    Tool(String),           // Tool execution error
    Session(String),        // Session storage error
    Context(String),        // Context engineering error
    Provider(SaorsaAiError), // LLM provider error (from saorsa-ai)
    Cancelled(String),      // Operation cancelled
    Io(std::io::Error),     // File I/O error
    Json(serde_json::Error), // Serialization error
    Internal(String),       // Internal error
    Extension(String),      // Extension error
}

Dependencies

Development

# Run all tests
cargo test -p saorsa-agent

# Run integration tests
cargo test -p saorsa-agent --test tool_integration
cargo test -p saorsa-agent --test integration_tools

Minimum Supported Rust Version

The MSRV is 1.88 (Rust Edition 2024). This is enforced in CI.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

Contributing

Part of the saorsa-tui workspace. See the workspace root for contribution guidelines.