Module Structure

Agent Air is organized into four top-level modules, each with a distinct responsibility. This page documents the internal structure of each module and the key types they export.

Top-Level Organization

src/
├── lib.rs              # Crate root, re-exports public API
├── agent/              # Agent infrastructure and configuration
├── controller/         # LLM session management and tool execution
├── client/             # HTTP client and LLM provider implementations
└── tui/                # Terminal UI components and application

The crate root (lib.rs) defines four public modules:

pub mod agent;      // Agent infrastructure and configuration
pub mod client;     // LLM client interface and providers
pub mod controller; // LLM session controller and tool execution
pub mod tui;        // Terminal UI components and application

Agent Module

The agent module provides the core infrastructure for building LLM-powered agents.

File Structure

agent/
├── mod.rs          # Module exports and re-exports
├── config.rs       # AgentConfig trait and configuration loading
├── core.rs         # AgentAir struct and lifecycle management
├── error.rs        # AgentError type definitions
├── logger.rs       # Tracing-based logging infrastructure
├── messages.rs     # UiMessage enum and channel definitions
└── router.rs       # InputRouter for message routing

Key Exports

Channel Type Aliases

pub type ToControllerTx = mpsc::Sender<ControllerInputPayload>;
pub type ToControllerRx = mpsc::Receiver<ControllerInputPayload>;
pub type FromControllerTx = mpsc::Sender<UiMessage>;
pub type FromControllerRx = mpsc::Receiver<UiMessage>;

Re-exports

The agent module re-exports commonly used controller types for convenience:

pub use crate::controller::{
    ControllerEvent, ControllerInputPayload, LLMController,
    LLMSessionConfig, PermissionRegistry, ToolResultStatus,
    TurnId, UserInteractionRegistry,
};

Controller Module

The controller module manages LLM interactions, session state, and tool execution.

File Structure

controller/
├── mod.rs              # Module exports
├── error.rs            # ControllerError type
├── llm_controller.rs   # Main LLMController with event loop
├── session/            # Session management
│   ├── mod.rs
│   ├── session.rs      # LLMSession struct
│   ├── manager.rs      # LLMSessionManager for multi-session
│   ├── config.rs       # LLMSessionConfig and CompactionConfig
│   └── compactor.rs    # ThresholdCompactor implementation
├── stateless/          # Stateless execution support
│   ├── mod.rs
│   ├── executor.rs     # StatelessExecutor
│   └── types.rs        # StatelessConfig, StatelessResult
├── tools/              # Tool execution framework
│   ├── mod.rs
│   ├── types.rs        # Executable trait, ToolContext, DisplayConfig
│   ├── executor.rs     # ToolExecutor for parallel execution
│   ├── registry.rs     # ToolRegistry for tool management
│   ├── ask_user_questions.rs    # Built-in user interaction tool
│   ├── ask_for_permissions.rs   # Built-in permission tool
│   └── web_search.rs            # Built-in web search tool
├── types/              # Core type definitions
│   ├── mod.rs
│   ├── enums.rs        # InputType, ControlCmd, MessageRole, etc.
│   ├── payload.rs      # ControllerEvent, ControllerInputPayload
│   ├── turnid.rs       # TurnId and TurnCounter
│   ├── message.rs      # Message enum
│   └── content.rs      # ContentBlock types
└── usage/              # Token tracking
    ├── mod.rs
    └── tracker.rs      # TokenUsageTracker

Key Exports

Core Controller Types:

Session Types:

Tool Types:

Message Types:

Registry Types:

Client Module

The client module provides HTTP communication with LLM providers.

File Structure

client/
├── mod.rs              # LLMClient struct and module exports
├── error.rs            # LlmError type
├── http.rs             # HttpClient with TLS and retry logic
├── models.rs           # Message, MessageOptions, StreamEvent
├── traits.rs           # LlmProvider trait
└── providers/          # Provider implementations
    ├── mod.rs
    ├── anthropic.rs    # Anthropic Claude API
    └── openai.rs       # OpenAI GPT API

Key Exports

LLMClient Interface

pub struct LLMClient {
    http_client: HttpClient,
    provider: Box<dyn LlmProvider + Send + Sync>,
}

impl LLMClient {
    pub fn new(provider: Box<dyn LlmProvider + Send + Sync>) -> Result<Self, LlmError>;
    pub async fn send_message(&self, messages: &[Message], options: &MessageOptions) -> Result<Message, LlmError>;
    pub async fn send_message_stream(&self, messages: &[Message], options: &MessageOptions)
        -> Result<Pin<Box<dyn Stream<Item = Result<StreamEvent, LlmError>> + Send>>, LlmError>;
}

TUI Module

The tui module provides terminal UI components built on Ratatui.

File Structure

tui/
├── mod.rs              # Module exports and re-exports
├── app.rs              # App struct and main event loop
├── markdown.rs         # Markdown rendering utilities
├── table.rs            # Table rendering utilities
├── commands/           # Slash command system
│   ├── mod.rs
│   ├── traits.rs       # SlashCommand trait
│   ├── registry.rs     # CommandRegistry
│   └── standard.rs     # Built-in commands (quit, help, clear, etc.)
├── keys/               # Key handling
│   ├── mod.rs
│   ├── handler.rs      # KeyHandler trait, DefaultKeyHandler
│   ├── bindings.rs     # KeyBindings configuration
│   └── types.rs        # KeyEvent, KeyContext, AppKeyAction
├── layout/             # Layout system
│   ├── mod.rs
│   ├── template.rs     # LayoutTemplate system
│   ├── standard.rs     # Standard layout with panels
│   ├── minimal.rs      # Minimal layout
│   └── helpers.rs      # Layout utilities
├── themes/             # Theme system
│   ├── mod.rs
│   ├── theme.rs        # Theme struct and colors
│   └── themes/         # 45+ built-in theme definitions
└── widgets/            # UI widgets
    ├── mod.rs
    ├── chat.rs         # ChatView for message display
    ├── input.rs        # TextInput for user input
    ├── status_bar.rs   # Status bar widget
    ├── permission_panel.rs  # Permission request UI
    ├── question_panel.rs    # User question UI
    ├── session_picker.rs    # Session selection UI
    └── slash_popup.rs       # Slash command autocomplete

Key Exports

Application:

Widgets:

Commands:

Key Handling:

Layout:

Themes:

Import Patterns

For Agent Developers

Most functionality is available through the agent module:

use agent_air::agent::{
    AgentAir, AgentConfig, AgentError,
    UiMessage, ControllerEvent, TurnId,
};

For Tool Developers

Import from the controller module:

use agent_air::controller::{
    Executable, ToolContext, ToolResult,
    DisplayConfig, DisplayResult,
};

For TUI Customization

Import from the tui module:

use agent_air::tui::{
    App, Theme, LayoutTemplate,
    SlashCommand, KeyHandler, Widget,
};

For Custom Providers

Import from the client module:

use agent_air::client::{
    LLMClient, LlmProvider, LlmError,
    Message, MessageOptions, StreamEvent,
};

Next Steps

• Message Flow - How messages traverse the module boundaries
• AgentAir Struct - The central orchestration struct
• Controller Events - Events emitted by the controller