Crate saorsa_agent 

saorsa-agent: AI coding agent runtime.

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

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     UI Layer (saorsa-app)                      │
│  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 context::AgentsContext;

pub use context::ContextBuilder;

pub use context::ContextBundle;

pub use context::ContextDiscovery;

pub use context::SystemContext;

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::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-tui AI agent.

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.