Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

25.8 KB
Raw Blame
//! [`RuntimeBuilder::build`]: the boot sequence.

use std::path::Path;
use std::sync::Arc;

use openhuman_core::config::Config;
use openhuman_core::core::runtime::{CoreBootMode, CoreBuilder, ServiceSet, TokenSource};
use openhuman_core::core::types::HostKind;
use tinyagents_session::port::SessionStoreProvider;

use super::builder::{starts_services_on_build, ConfigSource};
use super::presets::{default_domains, default_services};
use super::{ApiKey, Runtime, RuntimeBuilder, RuntimeError, RUNTIME_LIVE};
use crate::harness::workspace::ResolvedWorkspace;
use crate::harness::{Provider, Workspace};
use crate::Core;

struct SessionStoreCleanup {
    installed: Option<Arc<dyn SessionStoreProvider>>,
    previous: Option<Arc<dyn SessionStoreProvider>>,
}

impl Drop for SessionStoreCleanup {
    fn drop(&mut self) {
        let Some(installed) = self.installed.take() else {
            return;
        };
        if openhuman_core::storage::sessions::clear_if(&installed) {
            openhuman_core::storage::sessions::restore(self.previous.take());
        }
    }
}

/// Releases [`RUNTIME_LIVE`] unless disarmed: held across
/// [`RuntimeBuilder::build`]'s boot so a failed or cancelled build never
/// leaves the process slot claimed.
struct SlotClaim {
    armed: bool,
}

impl Drop for SlotClaim {
    fn drop(&mut self) {
        if self.armed {
            RUNTIME_LIVE.store(false, std::sync::atomic::Ordering::Release);
            log::debug!("[embed][runtime] build did not complete; process slot released");
        }
    }
}

impl RuntimeBuilder {
    /// Build the core and return a runtime ready to host agents.
    ///
    /// # Errors
    ///
    /// [`RuntimeError::AlreadyRunning`] if this process already has one;
    /// [`RuntimeError::BlankApiKey`] for an empty key;
    /// [`RuntimeError::Invalid`] for a knob the [`ConfigSource`] cannot
    /// honour or a refused controller extension.
    pub async fn build(self) -> Result<Runtime, RuntimeError> {
        // Claim the process slot before doing any work, so a losing racer
        // neither creates a temp dir nor half-initializes global state.
        if RUNTIME_LIVE.swap(true, std::sync::atomic::Ordering::AcqRel) {
            return Err(RuntimeError::AlreadyRunning);
        }
        // From here on every early return must release the slot, or a failed
        // build would permanently poison the process against retrying. The
        // claim is a drop guard rather than a match on the result so that a
        // *cancelled* build (the future dropped mid-boot, as the desktop
        // shell's startup timeout does to its server task) releases it too.
        let mut claim = SlotClaim { armed: true };
        let result = self.build_inner().await;
        if result.is_ok() {
            // The runtime's `CoreGuard` owns the slot from here.
            claim.armed = false;
        }
        result
    }

    /// Refuse combinations the chosen [`ConfigSource`] cannot honour.
    pub(super) fn validate(&self) -> Result<(), RuntimeError> {
        self.validate_modules()?;
        let inspection = self.boot_mode == CoreBootMode::Inspection;
        if inspection {
            if self.config_source != ConfigSource::Resolved
                || self.config.is_none()
                || !matches!(self.workspace, Workspace::Inherit)
                || !matches!(&self.token, TokenSource::Fixed(_))
            {
                return Err(RuntimeError::Invalid(
                    "inspection boot requires an inherited workspace, caller-supplied resolved config, and fixed bearer".into(),
                ));
            }
            if self.workspace_dir.is_some()
                || self.action_dir.is_some()
                || self.api_key.is_some()
                || self.session.is_some()
                || self.session_store.is_some()
                || self.seams.storage.is_some()
            {
                return Err(RuntimeError::Invalid(
                    "inspection boot does not accept path overrides, credentials, sessions, or storage providers".into(),
                ));
            }
            if openhuman_core::storage::installed().is_some() {
                return Err(RuntimeError::Invalid(
                    "inspection boot requires no installed storage backend".into(),
                ));
            }
        }
        if !inspection && self.agent_defaults.skills.root.is_some() && !cfg!(feature = "skills") {
            return Err(RuntimeError::Invalid(
                "copying runtime skill bundles requires Cargo feature `openhuman-embed/skills`"
                    .into(),
            ));
        }

        if !inspection {
            validate_storage_feature(self.seams.storage.as_ref())?;
            if self.seams.storage.is_none() {
                if let Some(config) = &self.config {
                    if let Some(url) = openhuman_core::storage::explicit_url(config) {
                        validate_storage_feature(Some(&super::StorageSource::Url(url)))?;
                    }
                }
            }
        }
        self.agent_defaults
            .model
            .validate()
            .map_err(RuntimeError::Invalid)?;
        if self.api_key.as_ref().is_some_and(ApiKey::is_blank) {
            return Err(RuntimeError::BlankApiKey);
        }
        if !inspection
            && matches!(self.workspace, Workspace::Stateless)
            && self.session_store.is_none()
            && self.seams.storage.is_none()
            && self
                .config
                .as_ref()
                .and_then(openhuman_core::storage::explicit_url)
                .is_none()
        {
            return Err(RuntimeError::NoSessionStore);
        }
        if self.config_source == ConfigSource::Discovered {
            if !matches!(self.workspace, Workspace::Inherit) {
                return Err(RuntimeError::Invalid(
                    "ConfigSource::Discovered needs Workspace::Inherit: the core discovers \
                     the operator's install"
                        .into(),
                ));
            }
            let edits = [
                ("config", self.config.is_some()),
                ("backend_url", self.backend_url.is_some()),
                ("workspace_dir", self.workspace_dir.is_some()),
                ("action_dir", self.action_dir.is_some()),
                ("api_key", self.api_key.is_some()),
                ("typed configuration", self.config_knobs.is_set()),
            ];
            if let Some((knob, _)) = edits.iter().find(|(_, set)| *set) {
                return Err(RuntimeError::Invalid(format!(
                    "`{knob}` edits the boot config, which ConfigSource::Discovered leaves \
                     to the core; use ConfigSource::Resolved"
                )));
            }
        }
        Ok(())
    }

    async fn build_inner(mut self) -> Result<Runtime, RuntimeError> {
        self.validate()?;
        let inspection = self.boot_mode == CoreBootMode::Inspection;
        let discovered = self.config_source == ConfigSource::Discovered;
        let inherit = self.workspace.is_operator_owned();
        let resolved = ResolvedWorkspace::resolve(&self.workspace, self.action_dir.as_deref())
            .map_err(map_ws)?;

        // Discovered: the core loads its own config during boot; nothing to
        // assemble here. Resolved: `Inherit` starts from the operator's own
        // config — loaded here rather than left to the core to discover,
        // because the other knobs are applied *on top* of it.
        let mut config = if discovered {
            None
        } else {
            Some(self.resolve_config(&resolved).await?)
        };

        // The seams are the last fallible step before side effects a failed
        // build cannot undo (the stored API key, the host memory engine), so
        // a refused controller extension leaves neither behind. Restorable
        // seams are undone by this guard if the boot below fails.
        let mut storage_info = super::StorageInfo::describe(
            self.seams.storage.as_ref(),
            config.as_ref().unwrap_or(&Config::default()),
            self.seams.storage_driver.as_deref(),
        );
        let mut host_seams = std::mem::take(&mut self.seams);
        if !inspection {
            if host_seams.storage.is_none() {
                if let Some(config) = &config {
                    if let Some(url) = openhuman_core::storage::explicit_url(config) {
                        host_seams.storage = Some(super::StorageSource::Url(url));
                    }
                }
            }
            // A stateless workspace keeps nothing durable on disk: with no host
            // backend, the documents the core keeps beside the session store (run
            // status, cron, flows) go to memory instead of the workspace-default
            // SQLite under `<workspace>/storage`. Installed process-wide like any
            // storage seam, and removed with the runtime.
            if host_seams.storage.is_none() && matches!(self.workspace, Workspace::Stateless) {
                host_seams.storage = Some(super::StorageSource::Url("memory".into()));
            }
            validate_storage_feature(host_seams.storage.as_ref())?;
            host_seams
                .open_storage()
                .await
                .map_err(RuntimeError::Invalid)?;
        }
        if !inspection
            && host_seams.storage.is_none()
            && matches!(self.workspace, Workspace::Stateless)
        {
            host_seams.storage = Some(super::StorageSource::Url("memory".into()));
            storage_info = super::StorageInfo::url("backend", "memory");
        }
        let storage_backend = if inspection {
            None
        } else {
            match &host_seams.storage {
                Some(super::StorageSource::Backend(backend)) => Some(backend.clone()),
                _ => None,
            }
        };
        let core_extensions = host_seams.core_extensions.clone();
        if !inspection && self.session_store.is_none() {
            if let Some(backend) = &storage_backend {
                let stores = openhuman_core::storage::sessions::TenantSessionStores::new(
                    backend.clone(),
                    storage_info.recover_sessions_on_open(),
                )
                .map_err(|e| RuntimeError::Build(e.into()))?;
                self.session_store = Some(Arc::new(stores));
            }
        }
        let mut seams = host_seams.install().map_err(RuntimeError::Invalid)?;

        // Before `CoreBuilder::build()`: the scheduler gate reads the credential
        // store exactly once, at boot, to decide whether it is signed in.
        let has_api_key = match (self.api_key.as_ref(), config.as_ref()) {
            (Some(key), Some(config)) => {
                store_api_key(config, key)?;
                true
            }
            _ => false,
        };

        // An endpoint without a model is deliberately ignored by the route
        // applicator, so host policy follows the effective behaviour: only a
        // *usable* runtime-default route exempts an inherited install from
        // its session gate. An API key is a credential in its own right.
        let routed_provider_effective = routed_provider_effective(&self.provider, config.as_ref());
        let host_kind = effective_host_kind(
            self.host_kind,
            inherit,
            routed_provider_effective || has_api_key,
        );

        let domains = self.domains.unwrap_or_else(default_domains);
        let tool_groups = self.tool_groups.clone().unwrap_or_default();
        let services = if inspection {
            ServiceSet::none()
        } else {
            self.services.unwrap_or_else(default_services)
        };

        if !inspection {
            if let Some(engine) = self.memory_engine.clone() {
                openhuman_core::memory::engine::install_host_engine(engine);
            }
        }
        if !inspection {
            if let Some(delivery) = self.cron_delivery.clone() {
                log::debug!("[embed][runtime] host cron delivery installed");
                openhuman_core::cron::host_delivery::install(delivery);
            }
        }

        // Install only after all fallible workspace/config resolution has
        // completed; core boot performs recovery against this provider.
        let installed_session_store = if inspection {
            None
        } else {
            self.session_store.clone()
        };
        let previous_session_store = installed_session_store
            .clone()
            .and_then(openhuman_core::storage::sessions::install);
        let mut session_store_cleanup = SessionStoreCleanup {
            installed: installed_session_store,
            previous: previous_session_store,
        };

        log::debug!(
            "[embed][runtime] building host_kind={host_kind:?} config_source={:?} \
             inherit_workspace={inherit} routed_provider={} api_key={has_api_key} \
             domains={domains:?} services={services:?} tool_groups={tool_groups:?} \
             listen_host={:?} listen_port={:?}",
            self.config_source,
            self.provider.is_routed(),
            self.listen_host,
            self.listen_port,
        );

        let mut builder = CoreBuilder::new(host_kind)
            .boot_mode(self.boot_mode)
            .domains(domains)
            .tool_groups(tool_groups.clone())
            .services(services)
            .extensions(core_extensions)
            .token(std::mem::replace(
                &mut self.token,
                openhuman_core::core::runtime::TokenSource::EnvOrFile,
            ));
        if let Some(config) = config.clone() {
            builder = builder.config(config);
        }
        if let Some(host) = self.listen_host.take() {
            builder = builder.host(host);
        }
        if let Some(port) = self.listen_port {
            builder = builder.port(port);
        }
        let runtime = builder.build().await.map_err(|error| {
            log::warn!("[embed][runtime] core build failed: {error:#}");
            RuntimeError::Build(error)
        })?;
        let core = Core::from_runtime(Arc::new(runtime));
        let storage_backend = if inspection {
            None
        } else {
            storage_backend.or_else(openhuman_core::storage::installed)
        };
        if !storage_info.configured && storage_backend.is_some() {
            let installed_url = openhuman_core::storage::installed_url();
            storage_info = super::StorageInfo::backend(installed_url.as_deref());
        }

        // Discovered: agents start from the config the core just loaded.
        let (mut base_config, config_unavailable) = match config.take() {
            Some(config) => (config, None),
            None => discovered_base_config().await,
        };
        if discovered {
            // Agent defaults only — the core's own config is not edited.
            self.config_knobs.apply(&mut base_config);
            if let Some(value) = self.agent_defaults.model.temperature {
                base_config.default_temperature = value;
            }
            if let Some(value) = self.agent_defaults.model.max_iterations {
                base_config.agent.max_tool_iterations_override = Some(value);
            }
            self.access.apply(&mut base_config);
            apply_provider(&mut base_config, &self.provider);
        }

        if seams.has_pending_live_policy() {
            if config_unavailable.is_some() {
                // The base config is a placeholder: its directories are the
                // default root, not the operator's install, so a policy
                // scoped to them would guard the wrong tree. Keep the policy
                // the core's bootstrap installed.
                log::warn!(
                    "[embed][runtime] live policy not installed: discovered config unavailable"
                );
            } else {
                seams.install_live_policy(&base_config.workspace_dir, &base_config.action_dir);
            }
        }

        if let Some(session) = self.session.take() {
            core.auth().store(session).await?;
        }

        let installed_session_store = session_store_cleanup.installed.take();
        let previous_session_store = session_store_cleanup.previous.take();
        log::debug!("[embed][runtime] built host_kind={host_kind:?}");

        let defaults = self.resolved_defaults(&base_config, domains, tool_groups.clone());
        let runtime = Runtime::new(
            core,
            resolved,
            installed_session_store,
            previous_session_store,
            Some(seams),
            base_config,
            config_unavailable,
            inherit,
            domains,
            tool_groups,
            self.max_agents,
            defaults,
            host_kind,
            self.selection,
            storage_info,
            storage_backend,
        );
        for (kind, handler) in self.cron_job_handlers {
            runtime.register_job_handler(kind, handler);
        }
        if starts_services_on_build(services, self.defer_services) {
            log::debug!("[embed][runtime] starting background services {services:?}");
            runtime.start_services().await;
        }
        Ok(runtime)
    }

    pub(super) fn resolved_defaults(
        &self,
        config: &Config,
        domains: crate::DomainSet,
        tool_groups: crate::ToolGroups,
    ) -> super::AgentDefaults {
        let mut defaults = self.agent_defaults.clone();
        defaults.provider = self.provider.clone();
        if defaults.provider.model_id().is_none() {
            if let Some(model) = &config.default_model {
                defaults.provider = defaults.provider.model(model);
            }
        }

        defaults.access = self.access.clone();
        defaults.domains = domains;
        defaults.tool_groups = tool_groups;
        let definition_model = defaults.definition.explicit_model_defaults();
        defaults.model.temperature = defaults
            .model
            .temperature
            .or(definition_model.temperature)
            .or(Some(config.default_temperature));
        defaults.model.max_iterations = defaults
            .model
            .max_iterations
            .or(definition_model.max_iterations)
            .or(config.agent.max_tool_iterations_override);
        if let Ok(definition) = defaults.definition.clone().into_core("runtime-defaults") {
            defaults.model.max_iterations = defaults
                .model
                .max_iterations
                .or(Some(definition.max_iterations));
            if defaults.sandbox == crate::SandboxModeSpec::None {
                defaults.sandbox = match definition.sandbox_mode {
                    tinyagents_definition::SandboxMode::None => crate::SandboxModeSpec::None,
                    tinyagents_definition::SandboxMode::ReadOnly => {
                        crate::SandboxModeSpec::ReadOnly
                    }
                    tinyagents_definition::SandboxMode::Sandboxed => {
                        crate::SandboxModeSpec::Sandboxed
                    }
                };
            }
        }
        defaults
    }

    /// The config a [`ConfigSource::Resolved`] runtime hands the core.
    async fn resolve_config(
        &mut self,
        resolved: &ResolvedWorkspace,
    ) -> Result<Config, RuntimeError> {
        let mut config = match (&self.workspace, self.config.take()) {
            (Workspace::Inherit, Some(config)) => config,
            (Workspace::Inherit, None) => {
                Config::load_or_init().await.map_err(RuntimeError::Build)?
            }
            (_, supplied) => {
                let mut config = supplied.unwrap_or_default();
                config.workspace_dir = resolved.workspace_dir.clone();
                config.action_dir = resolved.action_dir.clone();
                // Credential state, auth profiles and the keyring file backend
                // all resolve against this path's parent, not `workspace_dir`.
                config.config_path = resolved.config_path.clone();
                config
            }
        };
        // Raw paths refine the resolved workspace field by field; the
        // credential root (`config_path`) is left to the `Workspace`.
        if let Some(dir) = self.workspace_dir.clone() {
            create_dir(&dir, "create the workspace_dir")?;
            log::debug!("[embed][runtime] workspace_dir override applied");
            config.workspace_dir = dir;
        }
        if let Some(dir) = self.action_dir.clone() {
            create_dir(&dir, "create the action_dir")?;
            log::debug!("[embed][runtime] action_dir override applied");
            config.action_dir = dir;
        }
        if let Some(url) = self.backend_url.clone() {
            config.api_url = Some(url);
        }
        self.config_knobs.apply(&mut config);
        if let Some(temperature) = self.agent_defaults.model.temperature {
            config.default_temperature = temperature;
        }
        if let Some(iterations) = self.agent_defaults.model.max_iterations {
            config.agent.max_tool_iterations_override = Some(iterations);
        }
        self.access.apply(&mut config);
        apply_provider(&mut config, &self.provider);
        Ok(config)
    }
}

/// The base config for agents of a runtime whose core discovered its own:
/// the same `load_or_init` the core just ran, so the two agree.
///
/// When it fails the core has already booted without its workspace-bound
/// stores. The runtime still comes up (a host that never creates an agent,
/// like the desktop shell, keeps working), but the failure is returned with
/// the placeholder config so [`Runtime::agent`] refuses instead of laying an
/// agent out under the default root, a different workspace and credential
/// store from the one the operator selected.
async fn discovered_base_config() -> (Config, Option<String>) {
    match Config::load_or_init().await {
        Ok(config) => (config, None),
        Err(error) => {
            log::warn!(
                "[embed][runtime] discovered config failed to load; agents will be refused: {error:#}"
            );
            (Config::default(), Some(format!("{error:#}")))
        }
    }
}

/// Whether the runtime-default provider route would actually take effect. An
/// endpoint without a model is deliberately ignored by the route applicator,
/// so host policy follows the effective behaviour: only a usable route with a
/// model exempts an inherited install from its session gate. A
/// [`ConfigSource::Discovered`] build has no config yet (`None`), but the
/// provider is applied to the agents' base config after boot, so it is judged
/// by the model it carries itself.
pub(crate) fn routed_provider_effective(provider: &Provider, config: Option<&Config>) -> bool {
    provider.custom_model().is_some()
        || (provider.has_usable_route()
            && match config {
                Some(config) => config.default_model.as_deref(),
                None => provider.model_id(),
            }
            .is_some_and(|model| !model.trim().is_empty()))
}

fn store_api_key(config: &Config, key: &ApiKey) -> Result<(), RuntimeError> {
    let state_dir = config
        .config_path
        .parent()
        .map(Path::to_path_buf)
        .unwrap_or_else(|| config.config_path.clone());
    openhuman_core::security::credentials::api_key::store_api_key_in(
        &state_dir,
        config.secrets.encrypt,
        key.expose(),
    )
    .map(|_| ())
    .map_err(RuntimeError::Build)
}

fn create_dir(dir: &Path, what: &'static str) -> Result<(), RuntimeError> {
    std::fs::create_dir_all(dir).map_err(|source| RuntimeError::Workspace { what, source })
}

fn map_ws(err: crate::HarnessError) -> RuntimeError {
    match err {
        crate::HarnessError::Workspace { what, source } => RuntimeError::Workspace { what, source },
        crate::HarnessError::Invalid(msg) => RuntimeError::Invalid(msg),
        crate::HarnessError::Build(e) => RuntimeError::Build(e),
        crate::HarnessError::McpCleanup(e) => RuntimeError::Build(e.into()),
        crate::HarnessError::Call(e) => RuntimeError::Call(e),
        crate::HarnessError::AlreadyRunning => RuntimeError::AlreadyRunning,
    }
}

/// Preserve the installed application's authentication policy when the
/// runtime borrows both its workspace and provider. `Library` means the host
/// supplied inference (a route or an API key); it must not become a blanket
/// way to bypass the session gate around an operator-installed provider.
pub(crate) fn effective_host_kind(
    requested: HostKind,
    inherit_workspace: bool,
    host_supplied_credential: bool,
) -> HostKind {
    if requested == HostKind::Library && inherit_workspace && !host_supplied_credential {
        HostKind::Cli
    } else {
        requested
    }
}

/// Apply a [`Provider`]'s model to the config.
///
/// Only the model: the *route* is a per-turn parameter, never a config write,
/// because config routes persist. See the [`provider`](crate::harness::provider)
/// module docs.
pub(crate) fn apply_provider(config: &mut Config, provider: &Provider) {
    if let Some(model) = provider.model_id() {
        config.default_model = Some(model.to_string());
    }
}

/// Fail before opening a URL whose driver is absent; credential text never enters the error.
fn validate_storage_feature(source: Option<&super::StorageSource>) -> Result<(), RuntimeError> {
    let Some(super::StorageSource::Url(url)) = source else {
        return Ok(());
    };
    let driver = openhuman_core::storage::StorageUrl::parse(url)
        .map_err(|_| RuntimeError::Invalid("invalid storage URL".into()))?
        .driver()
        .to_string();
    let feature = match driver.as_str() {
        "sqlite" => Some("storage-sqlite"),
        "mongodb" => Some("storage-mongodb"),
        "file" => Some("storage-file"),
        _ => None,
    };
    if let Some(feature) = feature {
        if !openhuman_core::core::runtime::compiled_features()[feature] {
            return Err(RuntimeError::MissingStorageFeature { driver, feature });
        }
    }
    Ok(())
}