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>,
    workspace_id: Option<String>,
    api_url: 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,
            workspace_id: None,
            api_url: 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 workspace ID
    ///
    /// This allows immediate agent claiming during startup. The workspace_id is sent
    /// during registration, and the server returns a unique claim_token that the agent
    /// persists for future registrations.
    ///
    /// - First registration: workspace_id → server creates claim_token → agent saves it
    /// - Subsequent registrations: agent sends claim_token from file
    /// - Transfer: agent sends both claim_token AND new workspace_id
    ///
    /// # Example
    ///
    /// ```no_run
    /// use elo::Agent;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let agent = Agent::builder()
    ///     .storage_path("/var/lib/loa")
    ///     .claim("j57abc123def456...")  // Convex workspace ID
    ///     .build()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn claim<S: Into<String>>(mut self, workspace_id: S) -> Self {
        self.workspace_id = Some(workspace_id.into());
        self
    }

    /// Set a custom API URL for the backend
    ///
    /// If not specified, uses the default production URL (https://api.loa.sh).
    /// Use this for local development or custom deployments.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use elo::Agent;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let agent = Agent::builder()
    ///     .storage_path("/var/lib/loa")
    ///     .api_url("http://localhost:8787")
    ///     .build()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn api_url<S: Into<String>>(mut self, url: S) -> Self {
        self.api_url = Some(url.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)
        tracing::debug!("Loading agent identity from {}", storage_path.display());
        let identity = std::sync::Arc::new(crate::AgentIdentity::from_storage_or_generate_new(&storage_path)?);
        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());

        // Initialize global API URL if custom URL is configured (e.g., --dev flag)
        // This allows constants::api_url() and constants::ingest_url() to use the runtime URL
        if let Some(ref url) = self.api_url {
            crate::constants::init_global_api_url(url.clone());
            tracing::debug!("  API URL: {}", url);
        }

        // Spawn root supervisor with shared identity, workspace_id, api_url, and storage_path
        tracing::debug!("Spawning root supervisor...");
        let (supervisor, supervisor_handle) = supervisor::spawn_root(identity, self.workspace_id, self.api_url, 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,
        ))
    }
}