loa_core/

builder.rs

//! Builder pattern for constructing Agent instances

use crate::{agent::Agent, supervisor, Error, Result};
use std::path::{Path, PathBuf};

/// Builder for configuring and creating an Agent
///
/// # Example
///
/// ```no_run
/// use elo::Agent;
///
/// # async fn example() -> anyhow::Result<()> {
/// let agent = Agent::builder()
///     .storage_path("/var/lib/loa")
///     .identity_path("/etc/loa/agent_id.key")
///     .dashboard_port(3000)
///     .build()
///     .await?;
/// # Ok(())
/// # }
/// ```
pub struct AgentBuilder {
    storage_path: Option<PathBuf>,
    identity_path: Option<PathBuf>,
    dashboard_port: Option<u16>,
    claim_token_id: Option<String>,
}

impl AgentBuilder {
    /// Create a new agent builder with default settings
    pub(crate) fn new() -> Self {
        Self {
            storage_path: None,
            identity_path: None,
            dashboard_port: None,
            claim_token_id: None,
        }
    }

    /// Set the storage path for databases and persistent data
    ///
    /// This is required. If not set, build() will return an error.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use elo::Agent;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let agent = Agent::builder()
    ///     .storage_path("/var/lib/loa")
    ///     .build()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn storage_path<P: AsRef<Path>>(mut self, path: P) -> Self {
        self.storage_path = Some(path.as_ref().to_path_buf());
        self
    }

    /// Set the identity path for agent identity key
    ///
    /// If not specified, defaults to `{storage_path}/agent_id.key`
    ///
    /// # Example
    ///
    /// ```no_run
    /// use elo::Agent;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let agent = Agent::builder()
    ///     .storage_path("/var/lib/loa")
    ///     .identity_path("/etc/loa/agent_id.key")
    ///     .build()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn identity_path<P: AsRef<Path>>(mut self, path: P) -> Self {
        self.identity_path = Some(path.as_ref().to_path_buf());
        self
    }

    /// Set the dashboard port
    ///
    /// Optional. If set, a dashboard will be served on this port (future feature).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use elo::Agent;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let agent = Agent::builder()
    ///     .storage_path("/var/lib/loa")
    ///     .dashboard_port(3000)
    ///     .build()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn dashboard_port(mut self, port: u16) -> Self {
        self.dashboard_port = Some(port);
        self
    }

    /// Claim this agent for a workspace using a claim token
    ///
    /// This allows immediate agent claiming during startup. The claim_token_id is sent
    /// with the heartbeat for self-registration, linking the agent to a workspace.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use elo::Agent;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let agent = Agent::builder()
    ///     .storage_path("/var/lib/loa")
    ///     .claim("550e8400-e29b-41d4-a716-446655440000")
    ///     .build()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn claim<S: Into<String>>(mut self, claim_token_id: S) -> Self {
        self.claim_token_id = Some(claim_token_id.into());
        self
    }

    /// Build the agent and spawn all internal actors
    ///
    /// This will:
    /// 1. Validate configuration
    /// 2. Create storage directories if needed
    /// 3. Spawn the root supervisor
    /// 4. Spawn all core actors (currently empty)
    /// 5. Return an Agent handle
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - storage_path is not set
    /// - storage directories cannot be created
    /// - supervisor fails to spawn
    ///
    /// # Example
    ///
    /// ```no_run
    /// use elo::Agent;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let agent = Agent::builder()
    ///     .storage_path("/var/lib/loa")
    ///     .build()
    ///     .await?;
    ///
    /// agent.run().await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn build(self) -> Result<Agent> {
        // Validate required fields
        let storage_path = self
            .storage_path
            .ok_or_else(|| Error::Config("storage_path is required".to_string()))?;

        // Apply defaults
        let identity_path = self.identity_path.or_else(|| {
            Some(storage_path.join("agent_id.key"))
        });

        tracing::debug!("Building agent...");
        tracing::debug!("  Storage: {}", storage_path.display());
        if let Some(ref identity_path) = identity_path {
            tracing::debug!("  Identity: {}", identity_path.display());
        }
        if let Some(port) = self.dashboard_port {
            tracing::debug!("  Dashboard: localhost:{}", port);
        }

        // Create storage directory if it doesn't exist
        if !storage_path.exists() {
            tracing::debug!("Creating storage directory: {}", storage_path.display());
            std::fs::create_dir_all(&storage_path)?;
        }

        // Load or generate agent identity (wrapped in Arc for efficient sharing)
        let identity_file = identity_path.as_ref().unwrap();
        tracing::debug!("Loading agent identity from {}", identity_file.display());
        let identity = std::sync::Arc::new(crate::AgentIdentity::from_file_or_generate_new(identity_file)?);
        let peer_id = identity.peer_id().clone();
        tracing::debug!("  Agent PeerId: {}", peer_id);

        // Initialize global identity singleton for access from all actors
        crate::identity::init_global_identity(identity.clone());

        // Spawn root supervisor with shared identity, claim_token_id, and storage_path
        tracing::debug!("Spawning root supervisor...");
        let (supervisor, supervisor_handle) = supervisor::spawn_root(identity, self.claim_token_id, storage_path.clone()).await?;
        tracing::debug!("  \u{2713} Root supervisor spawned");

        tracing::info!("Agent ready (PeerId: {}, Storage: {})", peer_id, storage_path.display());

        Ok(Agent::new(
            storage_path,
            identity_path,
            self.dashboard_port,
            supervisor,
            supervisor_handle,
        ))
    }
}