Skip to content

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

20.3 KB
Raw Blame
//! Process-global core seams as builder options.
//!
//! The core exposes a handful of installers a host calls once per process:
//! the controller registry extension, the `tool_search` ranker, embedder
//! post-turn and tool hooks, the `run`/`serve` server launcher and the live
//! security policy. [`RuntimeBuilder`] takes each as an option, installs it on
//! `build()`, and restores what it can when the runtime is dropped:
//!
//! | Seam | Installed | On drop |
//! |---|---|---|
//! | [`controller_extension`](RuntimeBuilder::controller_extension) | before boot | kept: the registry has no removal; re-registering the same controllers is a no-op |
//! | [`tool_ranker`](RuntimeBuilder::tool_ranker) | before boot | the previous ranker is restored, if ours still holds the slot |
//! | [`post_turn_hook`](RuntimeBuilder::post_turn_hook) / [`tool_hook`](RuntimeBuilder::tool_hook) | before boot; learning sinks get private runtime identities, tool hooks retain declared names | newest first, while ours still holds the identity: ours removed, a replaced hook restored |
//! | [`server_launcher`](RuntimeBuilder::server_launcher) | before boot | kept: first install wins for the process |
//! | [`live_policy`](RuntimeBuilder::live_policy) | after boot | kept: the next boot (or a config reload) installs its own |
//! | [`storage`](RuntimeBuilder::storage) | before boot | the previous backend is restored (or cleared), if ours still holds the slot |
//!
//! The live policy goes in *after* boot because the core's bootstrap installs
//! one derived from the config; installing earlier would be overwritten. A
//! later `config.update_autonomy_settings` reload or channel startup rebuilds
//! the policy from config again — the override lasts until then.

use std::sync::Arc;

use crate::seams::{LearningSink, OpenHumanRunContext, ToolHook};
#[cfg(test)]
use openhuman_core::agent::hooks::embedder_post_turn_hooks;
use openhuman_core::agent::hooks::{
    embedder_post_turn_hook_named, embedder_tool_hooks, replace_embedder_post_turn_hook,
    replace_embedder_tool_hook,
};
use openhuman_core::agent::tinyagents::discovery::{
    clear_tool_ranker, install_tool_ranker, installed_tool_ranker,
};
use openhuman_core::core::all::{register_controller_extension, ControllerExtension};
use openhuman_core::core::server_launcher::{install_server_launcher, ServerLauncher};
use openhuman_core::core::slots::Extensions;
use openhuman_core::security::SecurityPolicy;
use openhuman_core::storage::StorageBackend;
use tinytools::ToolRanker;

use super::RuntimeBuilder;

/// Where a runtime's storage backend (the `tinystoragedrivers` ports the
/// core's `storage` domain reads) comes from.
#[derive(Clone)]
pub enum StorageSource {
    /// A storage URL (`sqlite://…`, `memory`, `mongodb://…`), opened when the
    /// runtime is built. A URL that cannot be opened fails the build.
    Url(String),
    /// A backend the host already opened. Pass a MongoDB backend as a
    /// [`Url`](Self::Url) instead, so its connection pool runs on the core's
    /// storage runtime rather than the host's.
    Backend(Arc<dyn StorageBackend>),
}

impl std::fmt::Debug for StorageSource {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // A URL can carry credentials: never print it.
        match self {
            Self::Url(_) => f.write_str("StorageSource::Url(<redacted>)"),
            Self::Backend(_) => f.write_str("StorageSource::Backend(<custom>)"),
        }
    }
}

impl From<&str> for StorageSource {
    fn from(url: &str) -> Self {
        Self::Url(url.to_string())
    }
}

impl From<String> for StorageSource {
    fn from(url: String) -> Self {
        Self::Url(url)
    }
}

impl From<Arc<dyn StorageBackend>> for StorageSource {
    fn from(backend: Arc<dyn StorageBackend>) -> Self {
        Self::Backend(backend)
    }
}

/// The seam options a builder collected, not yet installed.
#[derive(Default)]
pub(crate) struct HostSeams {
    pub(crate) controller_extensions: Vec<ControllerExtension>,
    pub(crate) core_extensions: Extensions,
    pub(crate) tool_ranker: Option<Arc<dyn ToolRanker>>,
    pub(crate) post_turn_hooks: Vec<Arc<dyn LearningSink>>,
    pub(crate) tool_hooks: Vec<Arc<dyn ToolHook<OpenHumanRunContext>>>,
    pub(crate) server_launcher: Option<ServerLauncher>,
    pub(crate) live_policy: Option<Arc<SecurityPolicy>>,
    pub(crate) storage: Option<StorageSource>,
    /// Driver metadata from a configured URL, retained after it is opened.
    /// Custom backends have no inferred driver identity.
    pub(crate) storage_driver: Option<String>,
}

impl HostSeams {
    /// Open a [`StorageSource::Url`] into a backend, so [`install`](Self::install)
    /// can stay synchronous. A no-op for any other source.
    ///
    /// # Errors
    ///
    /// The URL could not be parsed or opened.
    pub(crate) async fn open_storage(&mut self) -> Result<(), String> {
        if let Some(StorageSource::Url(url)) = &self.storage {
            self.storage_driver = Some(
                openhuman_core::storage::StorageUrl::parse(url)
                    .map_err(|_| String::from("invalid storage URL"))?
                    .driver()
                    .to_string(),
            );
            let backend = openhuman_core::storage::open(url)
                .await
                .map_err(|error| format!("opening the storage backend: {error}"))?;
            self.storage = Some(StorageSource::Backend(backend));
        }
        Ok(())
    }

    /// [`open_storage`](Self::open_storage) from synchronous code. The backend
    /// is opened on the core's storage runtime, so it outlives the call.
    pub(crate) fn open_storage_blocking(&mut self) -> Result<(), String> {
        let Some(StorageSource::Url(url)) = self.storage.take() else {
            return Ok(());
        };
        self.storage_driver = Some(
            openhuman_core::storage::StorageUrl::parse(&url)
                .map_err(|_| String::from("invalid storage URL"))?
                .driver()
                .to_string(),
        );
        let backend =
            openhuman_core::storage::block_on(
                async move { openhuman_core::storage::open(&url).await },
            )
            .map_err(|error| format!("opening the storage backend: {error}"))?;
        self.storage = Some(StorageSource::Backend(backend));
        Ok(())
    }

    /// Install every pre-boot seam and return the guard that undoes the
    /// restorable ones.
    ///
    /// Controller extensions go first because they are the only fallible
    /// step; nothing restorable has been touched when one is refused. An
    /// extension accepted before a later one is refused stays registered —
    /// the registry has no removal.
    pub(crate) fn install(self) -> Result<InstalledSeams, String> {
        for ext in self.controller_extensions {
            let group = ext.group;
            register_controller_extension(ext).map_err(|error| {
                log::warn!("[embed][seams] controller extension refused group={group:?}: {error}");
                error
            })?;
            log::debug!("[embed][seams] controller extension registered group={group:?}");
        }

        if let Some(launcher) = self.server_launcher {
            install_server_launcher(launcher);
            log::debug!("[embed][seams] server launcher installed (process lifetime)");
        }

        let ranker = self.tool_ranker.map(|ranker| {
            let previous = installed_tool_ranker();
            log::debug!(
                "[embed][seams] tool ranker installed kind={} replaced={}",
                ranker.kind(),
                previous.is_some()
            );
            install_tool_ranker(Arc::clone(&ranker));
            (ranker, previous)
        });

        let post_turn_hooks = self
            .post_turn_hooks
            .into_iter()
            .map(|hook| {
                static NEXT_LEARNING_SINK: std::sync::atomic::AtomicU64 =
                    std::sync::atomic::AtomicU64::new(0);
                let name = format!(
                    "embedder.learning_sink.{:020}",
                    NEXT_LEARNING_SINK.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
                );
                let previous = embedder_post_turn_hook_named(&name);
                replace_embedder_post_turn_hook(&name, Some(Arc::clone(&hook)));
                log::debug!(
                    "[embed][seams] post-turn hook installed name={name} replaced={}",
                    previous.is_some()
                );
                InstalledHook {
                    name,
                    ours: hook,
                    previous,
                }
            })
            .collect();

        let tool_hooks = self
            .tool_hooks
            .into_iter()
            .map(|hook| {
                let name = hook.name().to_string();
                let previous = embedder_tool_hooks()
                    .into_iter()
                    .find(|existing| existing.name() == name);
                replace_embedder_tool_hook(&name, Some(Arc::clone(&hook)));
                log::debug!(
                    "[embed][seams] tool hook installed name={name} replaced={}",
                    previous.is_some()
                );
                InstalledHook {
                    name,
                    ours: hook,
                    previous,
                }
            })
            .collect();

        let storage = match self.storage {
            Some(StorageSource::Backend(backend)) => {
                let previous = openhuman_core::storage::install(Arc::clone(&backend));
                log::debug!(
                    "[embed][seams] storage backend installed source_driver={:?} replaced={}",
                    self.storage_driver,
                    previous.is_some()
                );
                Some((backend, previous))
            }
            Some(StorageSource::Url(_)) => {
                return Err("storage url was not opened before install".to_string());
            }
            None => None,
        };

        Ok(InstalledSeams {
            storage,
            ranker,
            post_turn_hooks,
            tool_hooks,
            live_policy: self.live_policy,
            restore: true,
        })
    }
}

/// A ranker we installed, and what held the slot before it.
type InstalledRanker = (Arc<dyn ToolRanker>, Option<Arc<dyn ToolRanker>>);

/// A storage backend we installed, and what held the slot before it.
type InstalledStorage = (Arc<dyn StorageBackend>, Option<Arc<dyn StorageBackend>>);

/// A hook we installed under `name`, and what held that name before it.
struct InstalledHook<H: ?Sized> {
    name: String,
    ours: Arc<H>,
    previous: Option<Arc<H>>,
}

/// Seams a runtime installed. Dropping it restores the restorable ones; see
/// the module docs.
pub(crate) struct InstalledSeams {
    storage: Option<InstalledStorage>,
    ranker: Option<InstalledRanker>,
    /// Our hooks, in install order, each with the same-named hook it replaced.
    post_turn_hooks: Vec<InstalledHook<dyn LearningSink>>,
    tool_hooks: Vec<InstalledHook<dyn ToolHook<OpenHumanRunContext>>>,
    /// Installed only once the core has booted.
    live_policy: Option<Arc<SecurityPolicy>>,
    restore: bool,
}

impl InstalledSeams {
    pub(crate) fn post_turn_hook(&mut self, name: &str, hook: Option<Arc<dyn LearningSink>>) {
        while let Some(index) = self
            .post_turn_hooks
            .iter()
            .rposition(|installed| installed.name == name)
        {
            let installed = self.post_turn_hooks.remove(index);
            let current = embedder_post_turn_hook_named(name);
            if current.is_some_and(|current| Arc::ptr_eq(&current, &installed.ours)) {
                replace_embedder_post_turn_hook(name, installed.previous);
            }
        }
        if let Some(hook) = hook {
            let previous = embedder_post_turn_hook_named(name);
            replace_embedder_post_turn_hook(name, Some(hook.clone()));
            self.post_turn_hooks.push(InstalledHook {
                name: name.to_owned(),
                ours: hook,
                previous,
            });
        }
    }
    pub(crate) fn tool_hook(
        &mut self,
        name: &str,
        hook: Option<Arc<dyn ToolHook<OpenHumanRunContext>>>,
    ) {
        while let Some(index) = self
            .tool_hooks
            .iter()
            .rposition(|installed| installed.name == name)
        {
            let installed = self.tool_hooks.remove(index);
            let current = embedder_tool_hooks()
                .into_iter()
                .find(|hook| hook.name() == name);
            if current.is_some_and(|current| Arc::ptr_eq(&current, &installed.ours)) {
                replace_embedder_tool_hook(name, installed.previous);
            }
        }
        if let Some(hook) = hook {
            let hook: Arc<dyn ToolHook<OpenHumanRunContext>> =
                Arc::new(super::live_hooks::NamedToolHook(name.to_owned(), hook));
            let previous = embedder_tool_hooks()
                .into_iter()
                .find(|hook| hook.name() == name);
            replace_embedder_tool_hook(name, Some(hook.clone()));
            self.tool_hooks.push(InstalledHook {
                name: name.to_owned(),
                ours: hook,
                previous,
            });
        }
    }
    /// Install the live policy, if one was given, against the booted config's
    /// directories. Call after the core's bootstrap has installed its own.
    pub(crate) fn install_live_policy(
        &mut self,
        workspace_dir: &std::path::Path,
        action_dir: &std::path::Path,
    ) {
        if let Some(policy) = self.live_policy.take() {
            openhuman_core::security::live_policy::install(
                policy,
                workspace_dir.to_path_buf(),
                action_dir.to_path_buf(),
            );
            log::debug!("[embed][seams] live policy installed (until the next reload)");
        }
    }

    /// Whether a live policy is still waiting for the core to boot.
    pub(crate) fn has_pending_live_policy(&self) -> bool {
        self.live_policy.is_some()
    }

    /// Keep everything installed for the rest of the process — for an entry
    /// point that never returns control to a runtime ([`RuntimeBuilder::run_from_args`]).
    pub(crate) fn persist(mut self) {
        self.restore = false;
        log::debug!("[embed][seams] seams kept for the process lifetime");
    }
}

impl Drop for InstalledSeams {
    fn drop(&mut self) {
        if !self.restore {
            return;
        }
        if let Some((ours, previous)) = self.storage.take() {
            let still_ours =
                openhuman_core::storage::installed().is_some_and(|now| Arc::ptr_eq(&now, &ours));
            if still_ours {
                match previous {
                    Some(previous) => {
                        openhuman_core::storage::install(previous);
                    }
                    None => {
                        openhuman_core::storage::clear();
                    }
                }
                log::debug!("[embed][seams] storage backend restored");
            } else {
                log::debug!("[embed][seams] storage backend replaced since build; left alone");
            }
        }
        if let Some((ours, previous)) = self.ranker.take() {
            let still_ours = installed_tool_ranker().is_some_and(|now| Arc::ptr_eq(&now, &ours));
            if still_ours {
                match previous {
                    Some(previous) => install_tool_ranker(previous),
                    None => clear_tool_ranker(),
                }
                log::debug!("[embed][seams] tool ranker restored");
            } else {
                log::debug!("[embed][seams] tool ranker replaced since build; left alone");
            }
        }
        // Newest first: a second same-named hook recorded the first as its
        // `previous`, so unwinding in install order would put the first back
        // over the original. And only while ours still holds the name, so a
        // hook installed after build is not clobbered.
        while let Some(hook) = self.post_turn_hooks.pop() {
            let current = embedder_post_turn_hook_named(&hook.name);
            if current.is_some_and(|now| Arc::ptr_eq(&now, &hook.ours)) {
                replace_embedder_post_turn_hook(&hook.name, hook.previous);
                log::debug!("[embed][seams] post-turn hook restored name={}", hook.name);
            } else {
                log::debug!(
                    "[embed][seams] post-turn hook replaced since build; left alone name={}",
                    hook.name
                );
            }
        }
        while let Some(hook) = self.tool_hooks.pop() {
            let current = embedder_tool_hooks()
                .into_iter()
                .find(|existing| existing.name() == hook.name);
            if current.is_some_and(|now| Arc::ptr_eq(&now, &hook.ours)) {
                replace_embedder_tool_hook(&hook.name, hook.previous);
                log::debug!("[embed][seams] tool hook restored name={}", hook.name);
            } else {
                log::debug!(
                    "[embed][seams] tool hook replaced since build; left alone name={}",
                    hook.name
                );
            }
        }
    }
}

impl RuntimeBuilder {
    /// Configure context-scoped core hooks before this runtime is built.
    ///
    /// The callback receives the same extension set that is attached to the
    /// runtime's `CoreContext`; registrations remain isolated from other core
    /// contexts in the process. This is intended for layered host crates.
    #[doc(hidden)]
    pub fn configure_core_extensions(self, configure: impl FnOnce(&Extensions)) -> Self {
        configure(&self.seams.core_extensions);
        self
    }

    /// Contribute controllers to the core's registry, as the TinyHumans layer
    /// does for its hosted RPC proxies. May be called more than once.
    ///
    /// Registered before boot; a collision with a built-in or earlier
    /// extension fails the build with [`RuntimeError::Invalid`](super::RuntimeError::Invalid).
    /// The registry has no removal, so an extension outlives the runtime;
    /// registering identical controllers again is a no-op.
    pub fn controller_extension(mut self, extension: ControllerExtension) -> Self {
        self.seams.controller_extensions.push(extension);
        self
    }

    /// The process-wide `tool_search` ranker. Restored to the previous one
    /// when the runtime drops.
    pub fn tool_ranker(mut self, ranker: Arc<dyn ToolRanker>) -> Self {
        self.seams.tool_ranker = Some(ranker);
        self
    }

    /// A hook every agent session runs after each turn. The runtime registers
    /// it with a private identity before boot and removes it when the runtime
    /// drops.
    pub fn post_turn_hook(mut self, hook: Arc<dyn LearningSink>) -> Self {
        self.seams.post_turn_hooks.push(hook);
        self
    }

    /// A hook every agent session runs around each tool call. Same
    /// replacement and restore rules as [`post_turn_hook`](Self::post_turn_hook).
    pub fn tool_hook(mut self, hook: Arc<dyn ToolHook<OpenHumanRunContext>>) -> Self {
        self.seams.tool_hooks.push(hook);
        self
    }

    /// The launcher the CLI's `run` / `serve` subcommands start a server
    /// with. The first launcher installed in a process wins and stays.
    pub fn server_launcher(mut self, launcher: ServerLauncher) -> Self {
        self.seams.server_launcher = Some(launcher);
        self
    }

    /// The storage backend the core's `storage` domain reads (approvals,
    /// secrets, documents, per-agent scopes): a URL opened at build time, or a
    /// backend the host opened. Installed before boot and, when the runtime
    /// drops, the previous backend is restored (or cleared) if ours still holds
    /// the slot.
    ///
    /// This is only the backend. Conversations move onto it with
    /// [`session_store`](Self::session_store).
    pub fn storage(mut self, source: impl Into<StorageSource>) -> Self {
        self.seams.storage = Some(source.into());
        self
    }

    /// Replace the live security policy the core installs at boot. Applied
    /// after boot; a later autonomy-settings reload rebuilds it from config.
    pub fn live_policy(mut self, policy: Arc<SecurityPolicy>) -> Self {
        self.seams.live_policy = Some(policy);
        self
    }
}

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