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, web\_search),
4//! event system for UI integration, and tool registry.
5//!
6//! # Architecture Overview
7//!
8//! ```text
9//! ┌─────────────────────────────────────────────────────────────┐
10//! │                     UI Layer (saorsa)                      │
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;
71/// Cost tracking for LLM interactions.
72pub mod cost;
73pub mod error;
74pub mod event;
75/// Extension system for plugins and custom functionality.
76pub mod extension;
77/// Session management for conversation history and persistence.
78pub mod session;
79/// Skills system for on-demand capabilities.
80pub mod skills;
81/// Prompt template system.
82pub mod templates;
83pub mod tool;
84pub mod tools;
85
86pub use agent::{AgentLoop, default_tools};
87pub use config::AgentConfig;
88pub use config::{
89    auth::{AuthConfig, AuthEntry},
90    import::{ImportReport, import_all},
91    models::{CustomModel, CustomProvider, ModelCost, ModelsConfig},
92    paths::{ensure_config_dir, saorsa_config_dir},
93    settings::{Settings, ThinkingLevel},
94};
95pub use context::{AgentsContext, ContextBuilder, ContextBundle, ContextDiscovery, SystemContext};
96pub use cost::{CostEntry, CostTracker};
97pub use error::{Result, SaorsaAgentError};
98pub use event::{AgentEvent, EventReceiver, EventSender, TurnEndReason, event_channel};
99pub use extension::{
100    CommandDefinition, CommandHandler, CommandRegistry, Extension, ExtensionMetadata,
101    ExtensionPackage, ExtensionRegistry, KeybindingDefinition, KeybindingHandler,
102    KeybindingRegistry, OverlayConfig, PackageManager, SharedExtensionRegistry,
103    ToolDefinition as ExtensionToolDefinition, ToolHandler as ExtensionToolHandler,
104    ToolParameter as ExtensionToolParameter, ToolRegistry as ExtensionToolRegistry, WidgetFactory,
105    WidgetRegistry, shared_registry,
106};
107pub use session::{
108    Bookmark, BookmarkManager, Message, SessionId, SessionMetadata, SessionNode, SessionStorage,
109    TreeNode, TreeRenderOptions, auto_fork_on_edit, build_session_tree, export_to_html,
110    find_in_tree, find_last_active_session, find_session_by_prefix, fork_session, render_tree,
111    restore_session,
112};
113pub use skills::{Skill, SkillRegistry};
114pub use templates::{TemplateContext, TemplateEngine, get_builtin, list_builtins, render_simple};
115pub use tool::{Tool, ToolRegistry};
116pub use tools::{
117    BashTool, EditTool, FindTool, GrepTool, LsTool, ReadTool, WebSearchTool, WriteTool,
118};
saorsa_agent/lib.rs

saorsa_agent/
lib.rs
