Skip to content

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

5.7 KB
Raw Blame
//! Tool sources: id-keyed factories an outside crate registers so its tools
//! join the agent catalogue.
//!
//! [`all_tools_with_runtime`](super::ops::all_tools_with_runtime) builds the
//! built-in catalogue, splicing every registered source in at its
//! [`ToolSourcePlacement`], then applies the capability filters (`DomainSet`,
//! memory capability, `ToolGroups`). A registered tool is therefore filtered
//! exactly like a built-in one. With nothing registered the catalogue is
//! unchanged.
//!
//! The catalogue order is part of the prompt-cache layout, so a source can ask
//! to sit after a named anchor point instead of at the end. Sources sharing a
//! placement keep registration order.
//!
//! The registry is generic: it knows nothing about what a source builds.

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

use tinytools::Tool;

use crate::config::{BrowserConfig, Config, HttpRequestConfig};
use crate::core::slots::HookSlot;
use crate::modules::tinybox::host_runtime::RuntimeAdapter;
use crate::security::{AuditLogger, SecurityPolicy};

/// What a tool source can see while the catalogue is assembled: the same
/// handles `all_tools_with_runtime` was given.
pub struct ToolSourceCtx<'a> {
    /// The session's configuration snapshot.
    pub config: &'a Arc<Config>,
    /// The root configuration the catalogue is assembled under.
    pub root_config: &'a Config,
    pub security: &'a Arc<SecurityPolicy>,
    pub runtime: &'a Arc<dyn RuntimeAdapter>,
    pub audit: &'a Arc<AuditLogger>,
    pub browser_config: &'a BrowserConfig,
    pub http_config: &'a HttpRequestConfig,
    /// The agent's permitted read/write root.
    pub action_dir: &'a Path,
    pub approval_workspace_root: Option<&'a Path>,
}

/// A registered tool source.
pub type ToolSourceFactory =
    Arc<dyn for<'a> Fn(&ToolSourceCtx<'a>) -> Vec<Box<dyn Tool>> + Send + Sync>;

/// Anchor point: right after the search tools, before hosting.
pub const ANCHOR_AFTER_SEARCH: &str = "after_search";
/// Stable insertion point for registered hosted tools after the former
/// configured-delegate catalogue slot and before Composio.
pub const ANCHOR_AFTER_DELEGATE: &str = "after_delegate";
/// Every anchor `all_tools_with_runtime` splices sources into.
pub const ANCHORS: [&str; 2] = [ANCHOR_AFTER_SEARCH, ANCHOR_AFTER_DELEGATE];

/// Where in the catalogue a source's tools go.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ToolSourcePlacement {
    /// After every built-in tool (the default).
    #[default]
    End,
    /// Right after the named anchor point (one of [`ANCHORS`]). An unknown
    /// anchor falls back to [`ToolSourcePlacement::End`] and logs a warning.
    After(&'static str),
}

#[derive(Clone)]
struct ToolSourceEntry {
    placement: ToolSourcePlacement,
    factory: ToolSourceFactory,
}

static TOOL_SOURCES: HookSlot<ToolSourceEntry> = HookSlot::new("tools::sources");

/// Registers `factory` as the tool source `id` for the whole process, at the
/// end of the catalogue. Re-registering an id replaces its factory and keeps
/// its position.
pub fn register_tool_source<F>(id: impl Into<String>, factory: F)
where
    F: for<'a> Fn(&ToolSourceCtx<'a>) -> Vec<Box<dyn Tool>> + Send + Sync + 'static,
{
    register_tool_source_at(id, ToolSourcePlacement::End, factory);
}

/// Registers a tool source for the whole process at `placement`.
pub fn register_tool_source_at<F>(id: impl Into<String>, placement: ToolSourcePlacement, factory: F)
where
    F: for<'a> Fn(&ToolSourceCtx<'a>) -> Vec<Box<dyn Tool>> + Send + Sync + 'static,
{
    TOOL_SOURCES.register(
        id,
        ToolSourceEntry {
            placement,
            factory: Arc::new(factory),
        },
    );
}

/// Registers a tool source for the context built from `extensions`, at the end
/// of the catalogue.
pub fn register_tool_source_in<F>(
    extensions: &crate::core::slots::Extensions,
    id: impl Into<String>,
    factory: F,
) where
    F: for<'a> Fn(&ToolSourceCtx<'a>) -> Vec<Box<dyn Tool>> + Send + Sync + 'static,
{
    TOOL_SOURCES.register_in(
        extensions,
        id,
        ToolSourceEntry {
            placement: ToolSourcePlacement::End,
            factory: Arc::new(factory),
        },
    );
}

/// Removes the process-wide tool source `id`.
pub fn unregister_tool_source(id: &str) -> bool {
    TOOL_SOURCES.unregister(id)
}

/// The placement of every registered source, in registration order.
pub fn registered_tool_source_placements() -> Vec<(String, ToolSourcePlacement)> {
    TOOL_SOURCES
        .entries()
        .into_iter()
        .map(|(id, entry)| (id, entry.placement))
        .collect()
}

/// Builds the tools of every registered source placed at `anchor`
/// (`Some(name)`) or at the end (`None`, which also collects sources whose
/// anchor is unknown), in registration order.
pub(crate) fn build_registered_tool_sources(
    ctx: &ToolSourceCtx<'_>,
    anchor: Option<&str>,
) -> Vec<Box<dyn Tool>> {
    let mut tools = Vec::new();
    for (id, entry) in TOOL_SOURCES.entries() {
        let applies = match (entry.placement, anchor) {
            (ToolSourcePlacement::After(a), Some(wanted)) => a == wanted,
            (ToolSourcePlacement::After(a), None) if !ANCHORS.contains(&a) => {
                tracing::warn!(source = %id, anchor = a, "[tools::sources] unknown anchor; appending at the end");
                true
            }
            (ToolSourcePlacement::End, None) => true,
            _ => false,
        };
        if !applies {
            continue;
        }
        let built = (entry.factory)(ctx);
        tracing::debug!(
            source = %id,
            anchor = ?anchor,
            count = built.len(),
            "[tools::sources] registered tool source built"
        );
        tools.extend(built);
    }
    tools
}

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