Crate saorsa_agent 

saorsa-agent: AI coding agent runtime.

Provides the agent loop, built-in tools (bash, read, write, edit, grep, find, ls, web_search), event system for UI integration, and tool registry.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     UI Layer (saorsa)                      │
│  Sends user input, receives AgentEvent stream               │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                  AgentLoop (async runtime)                  │
│  User message → Context → LLM request → Tool execution      │
│  → Follow-up → ... → Final response → TurnEnd               │
└─────────────────────────────────────────────────────────────┘
         │                   │                   │
         ▼                   ▼                   ▼
   ┌──────────┐      ┌──────────────┐    ┌──────────────┐
   │ Context  │      │  Provider    │    │ ToolRegistry │
   │ Builder  │      │  (saorsa-ai)    │    │              │
   └──────────┘      └──────────────┘    └──────────────┘
        │                   │                   │
        ▼                   ▼                   ▼
┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│ AGENTS.md      │  │ Stream events  │  │ Bash, Read,    │
│ SYSTEM.md      │  │ Tool calls     │  │ Write, Edit,   │
│ Project files  │  │ Content delta  │  │ Grep, Find, Ls │
└────────────────┘  └────────────────┘  └────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│              SessionStorage (persistence)                   │
│  Messages, tool results, tree structure, bookmarks          │
└─────────────────────────────────────────────────────────────┘

Core Subsystems

• AgentLoop: Main async runtime coordinating LLM interaction and tool execution
• Context Engineering: Loads AGENTS.md, SYSTEM.md, project files into LLM context
• Tool Registry: Built-in tools (bash, file ops, search) + extension tools
• Session Management: Conversation history with tree-based branching and bookmarks
• Event System: Async channel for UI updates (thinking, tool execution, streaming)
• Skills System: On-demand capabilities loaded from ~/.claude/skills/
• Extension System: Plugins for commands, keybindings, tools, and widgets

Agent Execution Flow

1. User Input → ContextBuilder assembles prompt with context files
2. LLM Request → Provider streams back content and tool calls
3. Tool Execution → Tools run in parallel, results added to conversation
4. Follow-up → If tools were called, LLM gets results and continues
5. Turn End → Final response emitted, session persisted

Key Types

• AgentLoop: Main agent runtime (run_turn, execute_tools)
• Tool: Trait for executable tools with JSON schema parameters
• ContextBuilder: Assembles system prompt with AGENTS.md, project files
• SessionStorage: Persists conversation history and tree structure
• AgentEvent: UI update events (thinking, tool execution, streaming, turn end)

Re-exports

pub use agent::AgentLoop;

pub use agent::default_tools;

pub use config::AgentConfig;

pub use config::auth::AuthConfig;

pub use config::auth::AuthEntry;

pub use config::import::ImportReport;

pub use config::import::import_all;

pub use config::models::CustomModel;

pub use config::models::CustomProvider;

pub use config::models::ModelCost;

pub use config::models::ModelsConfig;

pub use config::paths::ensure_config_dir;

pub use config::paths::saorsa_config_dir;

pub use config::settings::Settings;

pub use config::settings::ThinkingLevel;

pub use context::AgentsContext;

pub use context::ContextBuilder;

pub use context::ContextBundle;

pub use context::ContextDiscovery;

pub use context::SystemContext;

pub use cost::CostEntry;

pub use cost::CostTracker;

pub use error::Result;

pub use error::SaorsaAgentError;

pub use event::AgentEvent;

pub use event::EventReceiver;

pub use event::EventSender;

pub use event::TurnEndReason;

pub use event::event_channel;

pub use extension::CommandDefinition;

pub use extension::CommandHandler;

pub use extension::CommandRegistry;

pub use extension::Extension;

pub use extension::ExtensionMetadata;

pub use extension::ExtensionPackage;

pub use extension::ExtensionRegistry;

pub use extension::KeybindingDefinition;

pub use extension::KeybindingHandler;

pub use extension::KeybindingRegistry;

pub use extension::OverlayConfig;

pub use extension::PackageManager;

pub use extension::SharedExtensionRegistry;

pub use extension::ToolDefinition as ExtensionToolDefinition;

pub use extension::ToolHandler as ExtensionToolHandler;

pub use extension::ToolParameter as ExtensionToolParameter;

pub use extension::ToolRegistry as ExtensionToolRegistry;

pub use extension::WidgetFactory;

pub use extension::WidgetRegistry;

pub use extension::shared_registry;

pub use session::Bookmark;

pub use session::BookmarkManager;

pub use session::Message;

pub use session::SessionId;

pub use session::SessionMetadata;

pub use session::SessionNode;

pub use session::SessionStorage;

pub use session::TreeNode;

pub use session::TreeRenderOptions;

pub use session::auto_fork_on_edit;

pub use session::build_session_tree;

pub use session::export_to_html;

pub use session::find_in_tree;

pub use session::find_last_active_session;

pub use session::find_session_by_prefix;

pub use session::fork_session;

pub use session::render_tree;

pub use session::restore_session;

pub use skills::Skill;

pub use skills::SkillRegistry;

pub use templates::TemplateContext;

pub use templates::TemplateEngine;

pub use templates::get_builtin;

pub use templates::list_builtins;

pub use templates::render_simple;

pub use tool::Tool;

pub use tool::ToolRegistry;

pub use tools::BashTool;

pub use tools::EditTool;

pub use tools::FindTool;

pub use tools::GrepTool;

pub use tools::LsTool;

pub use tools::ReadTool;

pub use tools::WebSearchTool;

pub use tools::WriteTool;

Modules

agent

Core agent loop for interacting with LLM providers.

config

Agent configuration.

context

Context engineering (AGENTS.md, SYSTEM.md, compaction, skills, templates). Context engineering system for the saorsa AI agent.

cost

Cost tracking for LLM interactions. Cost tracking for LLM interactions.

error

Error types for saorsa-agent.

event

Agent events for UI integration.

extension

Extension system for plugins and custom functionality. Extension system for saorsa-agent.

session

Session management for conversation history and persistence. Session management types and functionality.

skills

Skills system for on-demand capabilities. Skills system for on-demand capability injection.

templates

Prompt template system. Prompt template system with variable substitution and conditionals.

tool

Tool trait and registry for agent tool execution.

tools

Built-in tools for the AI coding agent.