Skip to content

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

21.8 KB
Raw Blame
//! The host adapter over `tinybus::module::Resolver`.
//!
//! The resolver ladder (already loaded, override, search path, release cache,
//! prune), the once-per-process resolution slots, failure caching, the module
//! runtime and the client all live in `tinybus::module`. This file is only what
//! OpenHuman contributes to them:
//!
//! - [`resolver`] turns a [`Config`] and the compiled [`registry`] into the
//!   resolver's plain inputs: the install directory, whether a cache miss may
//!   reach the network, the source each module is served from (see
//!   [`super::source`]), the `[components]` gate, per-module initialisation
//!   configuration and the shared Sentry reporter ([`super::report`]).
//! - [`client`] is a `tinybus::module::ModuleClient` over that resolver.
//! - [`list`] and [`state_of`] shape the resolver's answers into the
//!   `modules.list` RPC output.
//!
//! # Failures are cached, not retried
//!
//! tinybus never unloads a library. A module that was refused, faulted, or
//! failed to initialise keeps whatever it mapped, and loading it again cannot
//! reach a different outcome without a restart, so the resolver caches the
//! failure and returns it directly. The user-visible consequence is that fixing
//! a module means restarting the core, which the error says.
//!
//! The first caller for a module decides its resolution; later callers, with
//! whatever configuration they hold, wait on that outcome.

use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex, OnceLock};
use std::time::Duration;

use super::types::{ModuleRecord, ModuleSource, ModuleState, ModuleStatus};
use super::{linked, registry, report, runtime, source};
use crate::config::Config;
use tinybus::module::{
    AccessFuture, Availability, FailureReporter, LoadError, ModuleAccess, ModuleClient,
    ModuleSource as ResolverSource, ProxyFailure, ReleaseRecord, Resolver, ResolverInputs,
};
use tinybus::Proxy;

/// Environment variable naming a directory of bundled release archives, for
/// headless hosts (the Docker image, the CLI tarball, bench bundles).
pub const BUNDLED_MODULES_ENV: &str = "OPENHUMAN_BUNDLED_MODULES";

/// Directory name searched beside the executable when nothing else is set.
const BUNDLED_MODULES_DIR: &str = "bundled-modules";

/// Installer-owned, read-only release cache. The desktop host sets this before
/// starting the embedded core; headless hosts name it with
/// [`BUNDLED_MODULES_ENV`] or ship it beside the binary.
static BUNDLED_RELEASES: OnceLock<PathBuf> = OnceLock::new();

/// Register the directory of release archives shipped with the desktop app.
/// Its contents still pass the compiled digest and TinyBus admission gates.
pub fn set_bundled_releases_dir(path: PathBuf) -> Result<(), PathBuf> {
    BUNDLED_RELEASES.set(path)
}

/// The bundled release directory: the one the host registered, else
/// [`BUNDLED_MODULES_ENV`], else `bundled-modules/` beside the executable.
/// Only an existing directory counts; nothing here creates one.
fn bundled_releases_dir() -> Option<PathBuf> {
    let exe_dir = std::env::current_exe()
        .ok()
        .and_then(|exe| exe.parent().map(Path::to_path_buf));
    resolve_bundled_dir(
        BUNDLED_RELEASES.get().cloned(),
        std::env::var_os(BUNDLED_MODULES_ENV).map(PathBuf::from),
        exe_dir,
    )
}

pub(crate) fn resolve_bundled_dir(
    registered: Option<PathBuf>,
    from_env: Option<PathBuf>,
    exe_dir: Option<PathBuf>,
) -> Option<PathBuf> {
    // Each candidate must be a directory to win: a stale registered path or a
    // mistyped env var must not hide a valid directory further down the list.
    let found = [
        registered,
        from_env,
        exe_dir.map(|dir| dir.join(BUNDLED_MODULES_DIR)),
    ]
    .into_iter()
    .flatten()
    .find(|dir| dir.is_dir());
    if let Some(dir) = &found {
        log::debug!("[modules] bundled release directory: {}", dir.display());
    }
    found
}

/// Library file stems of every module whose component is off, for skipping
/// their search-path artifacts. Both `name` and `libname` spellings, for the
/// source build (`lib_name`) and the release download (`<id>_module`).
#[must_use]
pub fn disabled_lib_stems(config: &Config) -> Vec<String> {
    registry::ALL
        .iter()
        .filter(|record| disabled_component(config, record.id).is_some())
        .flat_map(|record| {
            let stem = record.source.lib_name.to_string();
            let released = format!("{}_module", record.id);
            [
                format!("lib{stem}"),
                stem,
                format!("lib{released}"),
                released,
            ]
        })
        .collect()
}

/// The disabled `[components]` switch that owns module `id`, if any.
#[must_use]
pub fn disabled_component(config: &Config, id: &str) -> Option<&'static str> {
    let component = registry::component_for(id)?;
    let set = crate::core::runtime::ComponentSet::from_config(&config.components);
    (!set.enabled(component)).then_some(component)
}

/// A resolver over the compiled registry, configured from `config`.
///
/// Cheap to build and to drop: the records are compiled constants, and the
/// resolution table, the runtime and the reporter are process-wide. Building
/// one starts nothing.
#[must_use]
pub fn resolver(config: &Config) -> Resolver {
    let shared = Arc::new(config.clone());
    let mut sources = std::collections::HashMap::new();
    let mut linked_factories = std::collections::HashMap::new();
    for record in registry::ALL {
        let plan = source::plan(config, record.id);
        log_plan_once(record, &plan);
        match plan.served {
            ModuleSource::LocalFile | ModuleSource::Source => {
                if let Some(path) = plan.artifact {
                    sources.insert(
                        record.id.to_string(),
                        ResolverSource::LocalFile {
                            path: path.to_string_lossy().into_owned(),
                        },
                    );
                }
            }
            ModuleSource::Linked => {
                sources.insert(record.id.to_string(), ResolverSource::Linked);
                if let Some(factory) = linked::factory_for(record.id) {
                    linked_factories.insert(record.id.to_string(), factory);
                }
            }
            ModuleSource::Release if record.id == "tinymcp" || record.id == "tinyeventqueues" => {
                // These modules require a per-module storage callback, which
                // TinyBus can bind only on its verified local-file path.
                // Route a staged release through that rung; the callback-aware
                // client below supplies the unique destination at load time.
                if let Some(path) = source::local_artifact(record.id) {
                    sources.insert(
                        record.id.to_string(),
                        ResolverSource::LocalFile {
                            path: path.to_string_lossy().into_owned(),
                        },
                    );
                }
            }
            ModuleSource::Release => {}
        }
    }
    let gate_config = Arc::clone(&shared);
    let module_config_source = Arc::clone(&shared);
    let mut search_skip = disabled_lib_stems(config);
    search_skip.extend(super::search_path::configured_module_lib_stems());
    Resolver::new(ResolverInputs {
        enabled: config.modules.enabled,
        install_dir: install_dir(config),
        allow_download: config.modules.allow_download,
        bundled_dir: bundled_releases_dir(),
        sources,
        linked: linked_factories,
        search_skip,
        gate: Some(Arc::new(move |id| disabled_component(&gate_config, id))),
        on_resolved: Some(Arc::new(on_resolved)),
        records: registry::release_records(),
        terminal_marker: tinytools::status::MODULE_FAULT_MARKER.to_string(),
        runtime: Arc::new(|| Box::pin(runtime::runtime())),
        module_config: Arc::new(move |id| {
            let value = module_config(&module_config_source, id);
            if id == super::connectors::MODULE_ID {
                super::connectors::note_module_config_for_load(&module_config_source, &value);
            }
            value
        }),
        reporter: report::reporter(),
    })
}

/// The staged artifact the callback-bound module fixture loads in isolation.
#[cfg(test)]
pub(crate) fn local_artifact_for_test(id: &str) -> Option<std::path::PathBuf> {
    source::local_artifact(id)
}

/// A `tinybus::module::ModuleClient` that loads modules lazily through
/// [`resolver`].
///
/// Constructing a client starts nothing. It needs neither a signed-in session
/// nor a core runtime. Set the bundled releases directory through the module
/// facade before the first call when artifacts ship with the host.
#[must_use]
pub fn client(config: Config) -> ModuleClient {
    ModuleClient::new(CallbackAccess {
        resolver: resolver(&config),
        config,
    })
}

/// The two modules that connect to storage through a capability scoped to
/// their exact verified module instance.
fn needs_storage_callback(id: &str) -> bool {
    id == "tinymcp" || id == "tinyeventqueues"
}

/// Serializes creation and retention of module-scoped storage callback bindings.
type StorageCallbackLoads = tokio::sync::Mutex<
    std::collections::HashMap<
        String,
        (
            std::sync::Arc<tinybus::module::HostCallbackBinding>,
            tinystoragedrivers_busproxy::ServedStorage,
        ),
    >,
>;

static STORAGE_CALLBACK_LOADS: std::sync::LazyLock<StorageCallbackLoads> =
    std::sync::LazyLock::new(|| tokio::sync::Mutex::new(std::collections::HashMap::new()));

async fn ensure_loaded_with_storage_callback(
    resolver: &Resolver,
    config: &Config,
    id: &str,
) -> Result<(), String> {
    let mut loads = STORAGE_CALLBACK_LOADS.lock().await;
    if let Some((binding, _served)) = loads.get(id) {
        if matches!(state_of(id), ModuleState::Ready) {
            // Already serving with this binding: a binding is spent once the
            // module takes it, so re-presenting it would be refused. The module
            // is process-wide, so every later workspace's client finds it
            // already serving.
            return Ok(());
        }
        let mut module_config = module_config(config, id);
        module_config["storage_callback"] = serde_json::json!(binding.unique_name().as_str());
        return resolver
            .ensure_loaded_with_host_callbacks(id, std::sync::Arc::clone(binding), module_config)
            .await;
    }

    let runtime = resolver
        .runtime()
        .await
        .map_err(|error| error.to_string())?;
    let (binding, served) = super::storage_host::prepare_module_callbacks(runtime)
        .await
        .map_err(|error| error.to_string())?;
    let mut module_config = module_config(config, id);
    module_config["storage_callback"] = serde_json::json!(binding.unique_name().as_str());
    resolver
        .ensure_loaded_with_host_callbacks(id, std::sync::Arc::clone(&binding), module_config)
        .await?;
    loads.insert(id.to_owned(), (binding, served));
    Ok(())
}

/// Module access that grants storage callbacks only while loading the two
/// modules whose contracts require them.
struct CallbackAccess {
    resolver: Resolver,
    config: Config,
}

impl ModuleAccess for CallbackAccess {
    fn find(&self, id: &str) -> Option<&'static ReleaseRecord> {
        self.resolver.find(id)
    }

    fn enabled(&self) -> bool {
        self.resolver.enabled()
    }

    fn reporter(&self) -> &FailureReporter {
        self.resolver.reporter()
    }

    fn ensure_loaded<'a>(&'a self, id: &'a str) -> AccessFuture<'a, Result<(), String>> {
        Box::pin(async move {
            let loaded = if needs_storage_callback(id) {
                ensure_loaded(&self.config, id).await
            } else {
                self.resolver.ensure_loaded(id).await
            };
            // The client collapses this message into a bare "module
            // unavailable"; keep the reason where an operator can grep it.
            if let Err(error) = &loaded {
                tracing::warn!(module = id, %error, "[modules] ensure_loaded refused the module");
            }
            loaded
        })
    }

    fn proxy<'a>(
        &'a self,
        bus_name: &'a str,
        object_path: &'a str,
    ) -> AccessFuture<'a, Result<Proxy, ProxyFailure>> {
        self.resolver.proxy(bus_name, object_path)
    }
}

/// A client whose every call goes to `proxy` instead of loading a module. The
/// module must still be in the registry and modules must still be enabled.
#[cfg(test)]
#[must_use]
pub(crate) fn fixture_client(proxy: tinybus::Proxy) -> ModuleClient {
    client(Config::default()).with_fixture(proxy)
}

/// Log which source serves each module and warn about a local build whose
/// gitlink is ahead of its released pin, once per id per process.
fn log_plan_once(record: &ModuleRecord, plan: &source::SourcePlan) {
    static LOGGED: OnceLock<Mutex<std::collections::HashSet<&'static str>>> = OnceLock::new();
    let first = LOGGED
        .get_or_init(Default::default)
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
        .insert(record.id);
    if !first {
        return;
    }
    if let Some(reason) = plan.fallback {
        log::warn!(
            "[modules] id={} requested={} served=release: {reason}",
            record.id,
            plan.requested.as_str()
        );
    }
    log::debug!(
        "[modules] id={} requested={} served={:?}",
        record.id,
        plan.requested.as_str(),
        plan.served
    );
    if let Some(line) = source::pin_ahead_warning(
        record.id,
        plan.served,
        std::env::var(source::PIN_AHEAD_ENV).ok().as_deref(),
        cfg!(debug_assertions),
    ) {
        log::warn!("{line}");
    }
}

/// The connector module's curated catalogs are cached in the host; a module
/// that has just been (re)resolved may serve other tables, so drop the snapshot
/// before any waiting caller is released. The next connector call (or the boot
/// warm-up) reads it again.
fn on_resolved(id: &str) {
    if id == super::connectors::MODULE_ID {
        crate::integrations::composio::contract::curated::invalidate();
    }
}

/// The message for a caller that cannot distinguish the cases. A switched-off
/// component keeps its typed `COMPONENT_DISABLED:<name>` spelling.
#[must_use]
pub fn load_error_message(error: LoadError) -> String {
    match error {
        LoadError::Disabled(component) => format!("COMPONENT_DISABLED:{component}"),
        other => other.into_message(),
    }
}

/// Ensure `id` is loaded and serving, loading it if this is the first ask.
///
/// Waits without bound. Prefer [`ensure_loaded_within`] from any path that has
/// a deadline of its own.
///
/// # Errors
///
/// Returns a message suitable for surfacing to a user or a model when the module
/// cannot be loaded: no artifact for this host, downloads disabled, a refused
/// artifact, or a previous failure in this process.
pub async fn ensure_loaded(config: &Config, id: &str) -> Result<(), String> {
    ensure_loaded_within(config, id, None)
        .await
        .map_err(load_error_message)
}

/// [`ensure_loaded`] with a bound on how long this caller waits.
///
/// The bound is on the *wait*, never on the resolution: a caller that gives up
/// leaves the download running and the slot intact, and a later call finds the
/// outcome. `None` waits without bound.
///
/// # Errors
///
/// [`LoadError::Failed`] when the module cannot be loaded in this process;
/// [`LoadError::StillLoading`] when `within` passed first;
/// [`LoadError::Disabled`] when its `[components]` switch is off.
pub async fn ensure_loaded_within(
    config: &Config,
    id: &str,
    within: Option<Duration>,
) -> Result<(), LoadError> {
    let resolver = resolver(config);
    let result = if needs_storage_callback(id) {
        if let Some(component) = disabled_component(config, id) {
            Err(LoadError::Disabled(component))
        } else {
            let load = ensure_loaded_with_storage_callback(&resolver, config, id);
            match within {
                Some(within) => tokio::time::timeout(within, load)
                    .await
                    .map_err(|_| LoadError::StillLoading)?
                    .map_err(LoadError::Failed),
                None => load.await.map_err(LoadError::Failed),
            }
        }
    } else {
        resolver.ensure_loaded_within(id, within).await
    };
    if id == super::connectors::MODULE_ID && result.is_ok() {
        super::connectors::note_load_resolution_ready();
    }
    result
}

/// The state of `id` as the resolution table reports it, without touching it.
#[must_use]
pub fn state_of(id: &str) -> ModuleState {
    use tinybus::module::resolution::{self, ResolutionState};
    match resolution::global().peek(id) {
        ResolutionState::Unresolved => ModuleState::Available,
        ResolutionState::Loading => ModuleState::Loading,
        ResolutionState::Ready => ModuleState::Ready,
        ResolutionState::Failed(_) => ModuleState::Failed,
    }
}

/// Configuration crossing into a first-party compiled module.
///
/// Credentials and callback destinations are intentionally absent. TinyMemory
/// receives only its compute configuration; TinyMCP and TinyEventQueues get a
/// unique storage callback destination from the verified loader.
pub(super) fn module_config(config: &Config, id: &str) -> serde_json::Value {
    if id == super::search::MODULE_ID {
        return super::search::load_configuration(config);
    }
    if id == super::desktop::MODULE_ID {
        return super::desktop::module_config(config);
    }
    // The queue manifest and pipeline the inbound event queues run; the
    // storage host declares the same manifest on the module's scope.
    #[cfg(feature = "inbound-queues")]
    if id == super::event_queues::MODULE_ID {
        return crate::inbound::module_config(config);
    }
    if id == super::connectors::MODULE_ID {
        // The connector module takes its route and credential from here and
        // reads one from nowhere else. A configuration that cannot be built —
        // direct mode with no key, an unknown mode — loads the module with an
        // empty blob rather than failing the load: the capability members need
        // no route and must still answer, and every member that does need one
        // reports the missing route when it is called.
        return super::connectors::module_config(config).unwrap_or_else(|error| {
            tracing::info!(
                error = %error,
                "[connectors] no route configured; loading with the capability surface only"
            );
            serde_json::json!({ "offered_toolkits": super::connectors::offered_toolkits(config) })
        });
    }
    serde_json::json!({})
}

/// [`module_config`] for a test in a sibling module.
#[cfg(test)]
pub(super) fn module_config_for_test(config: &Config, id: &str) -> serde_json::Value {
    module_config(config, id)
}

/// Where downloaded artifacts are kept.
///
/// The user cache directory, falling back to the workspace when there is none —
/// the same shape used by other module asset installers, for the same
/// reason: a headless container often has no `XDG_CACHE_HOME`, and failing to
/// install because of that would be worse than writing beside the workspace.
#[must_use]
pub fn install_dir(config: &Config) -> Option<PathBuf> {
    if let Some(configured) = &config.modules.install_dir {
        return Some(PathBuf::from(configured));
    }
    if let Some(cache) = dirs::cache_dir() {
        return Some(cache.join("openhuman").join("modules"));
    }
    log::warn!("[modules] no cache directory; installing modules under the workspace instead");
    Some(config.workspace_dir.join("modules"))
}

/// Status of every module this build knows about.
#[must_use]
pub fn list(config: &Config) -> Vec<ModuleStatus> {
    registry::ALL
        .iter()
        .map(|record| status_of(config, record))
        .collect()
}

/// Status of one module.
fn status_of(config: &Config, record: &ModuleRecord) -> ModuleStatus {
    // Configuration is authoritative for the current core instance. A module
    // may remain loaded in this process after a prior request, but callers
    // whose configuration disables modules must still be told it is unusable.
    let (state, detail) = match disabled_component(config, record.id) {
        Some(component) => (
            ModuleState::Disabled,
            Some(format!(
                "COMPONENT_DISABLED:{component} (set [components] {component} = true to enable)"
            )),
        ),
        None => {
            let (availability, detail) = resolver(config).status_of(&record.release());
            (
                match availability {
                    Availability::Available => ModuleState::Available,
                    Availability::Loading => ModuleState::Loading,
                    Availability::Ready => ModuleState::Ready,
                    Availability::Failed => ModuleState::Failed,
                    Availability::Unsupported => ModuleState::Unsupported,
                    Availability::Disabled => ModuleState::Disabled,
                },
                detail,
            )
        }
    };
    let plan = source::plan(config, record.id);
    let source =
        (!matches!(state, ModuleState::Unsupported | ModuleState::Disabled)).then_some(plan.served);
    let detail = detail.or_else(|| plan.fallback.map(str::to_string));
    ModuleStatus {
        id: record.id.to_string(),
        description: record.description.to_string(),
        version: record.version.to_string(),
        bus_name: record.bus_name.to_string(),
        state,
        source,
        detail,
    }
}

#[cfg(test)]
#[path = "ops_tests.rs"]
mod tests;

#[cfg(test)]
#[path = "ops_components_tests.rs"]
mod components_tests;

#[cfg(test)]
#[path = "ops_client_tests.rs"]
mod client_tests;

#[cfg(test)]
#[path = "ops_resolver_tests.rs"]
mod resolver_tests;