saorsa_agent/
lib.rs

1//! saorsa-agent: AI coding agent runtime.
2//!
3//! Provides the agent loop, built-in tools (bash, read, write, edit, grep, find, ls),
4//! event system for UI integration, and tool registry.
5//!
6//! # Architecture Overview
7//!
8//! ```text
9//! ┌─────────────────────────────────────────────────────────────┐
10//! │                     UI Layer (saorsa-app)                      │
11//! │  Sends user input, receives AgentEvent stream               │
12//! └─────────────────────────────────────────────────────────────┘
13//!                              │
14//!                              ▼
15//! ┌─────────────────────────────────────────────────────────────┐
16//! │                  AgentLoop (async runtime)                  │
17//! │  User message → Context → LLM request → Tool execution      │
18//! │  → Follow-up → ... → Final response → TurnEnd               │
19//! └─────────────────────────────────────────────────────────────┘
20//!          │                   │                   │
21//!          ▼                   ▼                   ▼
22//!    ┌──────────┐      ┌──────────────┐    ┌──────────────┐
23//!    │ Context  │      │  Provider    │    │ ToolRegistry │
24//!    │ Builder  │      │  (saorsa-ai)    │    │              │
25//!    └──────────┘      └──────────────┘    └──────────────┘
26//!         │                   │                   │
27//!         ▼                   ▼                   ▼
28//! ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
29//! │ AGENTS.md      │  │ Stream events  │  │ Bash, Read,    │
30//! │ SYSTEM.md      │  │ Tool calls     │  │ Write, Edit,   │
31//! │ Project files  │  │ Content delta  │  │ Grep, Find, Ls │
32//! └────────────────┘  └────────────────┘  └────────────────┘
33//!                              │
34//!                              ▼
35//! ┌─────────────────────────────────────────────────────────────┐
36//! │              SessionStorage (persistence)                   │
37//! │  Messages, tool results, tree structure, bookmarks          │
38//! └─────────────────────────────────────────────────────────────┘
39//! ```
40//!
41//! ## Core Subsystems
42//!
43//! - **AgentLoop**: Main async runtime coordinating LLM interaction and tool execution
44//! - **Context Engineering**: Loads AGENTS.md, SYSTEM.md, project files into LLM context
45//! - **Tool Registry**: Built-in tools (bash, file ops, search) + extension tools
46//! - **Session Management**: Conversation history with tree-based branching and bookmarks
47//! - **Event System**: Async channel for UI updates (thinking, tool execution, streaming)
48//! - **Skills System**: On-demand capabilities loaded from `~/.claude/skills/`
49//! - **Extension System**: Plugins for commands, keybindings, tools, and widgets
50//!
51//! ## Agent Execution Flow
52//!
53//! 1. **User Input** → ContextBuilder assembles prompt with context files
54//! 2. **LLM Request** → Provider streams back content and tool calls
55//! 3. **Tool Execution** → Tools run in parallel, results added to conversation
56//! 4. **Follow-up** → If tools were called, LLM gets results and continues
57//! 5. **Turn End** → Final response emitted, session persisted
58//!
59//! ## Key Types
60//!
61//! - `AgentLoop`: Main agent runtime (run_turn, execute_tools)
62//! - `Tool`: Trait for executable tools with JSON schema parameters
63//! - `ContextBuilder`: Assembles system prompt with AGENTS.md, project files
64//! - `SessionStorage`: Persists conversation history and tree structure
65//! - `AgentEvent`: UI update events (thinking, tool execution, streaming, turn end)
66
67pub mod agent;
68pub mod config;
69/// Context engineering (AGENTS.md, SYSTEM.md, compaction, skills, templates).
70pub mod context;
71pub mod error;
72pub mod event;
73/// Extension system for plugins and custom functionality.
74pub mod extension;
75/// Session management for conversation history and persistence.
76pub mod session;
77/// Skills system for on-demand capabilities.
78pub mod skills;
79/// Prompt template system.
80pub mod templates;
81pub mod tool;
82pub mod tools;
83
84pub use agent::{AgentLoop, default_tools};
85pub use config::AgentConfig;
86pub use context::{AgentsContext, ContextBuilder, ContextBundle, ContextDiscovery, SystemContext};
87pub use error::{Result, SaorsaAgentError};
88pub use event::{AgentEvent, EventReceiver, EventSender, TurnEndReason, event_channel};
89pub use extension::{
90    CommandDefinition, CommandHandler, CommandRegistry, Extension, ExtensionMetadata,
91    ExtensionPackage, ExtensionRegistry, KeybindingDefinition, KeybindingHandler,
92    KeybindingRegistry, OverlayConfig, PackageManager, SharedExtensionRegistry,
93    ToolDefinition as ExtensionToolDefinition, ToolHandler as ExtensionToolHandler,
94    ToolParameter as ExtensionToolParameter, ToolRegistry as ExtensionToolRegistry, WidgetFactory,
95    WidgetRegistry, shared_registry,
96};
97pub use session::{
98    Bookmark, BookmarkManager, Message, SessionId, SessionMetadata, SessionNode, SessionStorage,
99    TreeNode, TreeRenderOptions, auto_fork_on_edit, build_session_tree, export_to_html,
100    find_in_tree, find_last_active_session, find_session_by_prefix, fork_session, render_tree,
101    restore_session,
102};
103pub use skills::{Skill, SkillRegistry};
104pub use templates::{TemplateContext, TemplateEngine, get_builtin, list_builtins, render_simple};
105pub use tool::{Tool, ToolRegistry};
106pub use tools::{BashTool, EditTool, FindTool, GrepTool, LsTool, ReadTool, WriteTool};
saorsa_agent/lib.rs

saorsa_agent/
lib.rs
