Skip to content

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

8.3 KB
Raw Blame
//! Tool groups as a **library-level axis**, alongside `ServiceSet` and
//! `DomainSet`.
//!
//! The packs in [`super::registry`] exist for one host's problem: an
//! orchestrator whose fixed per-turn cost is dominated by tool schemas. That is
//! a compression decision, and compiling it in is right for the desktop app —
//! membership must not be editable by config or RPC, or a caller could move a
//! dangerous tool out of the reviewed surface.
//!
//! An embedder is a different question. `openhuman_core` is consumed as a
//! library through [`Harness`](crate::Harness), and there the pack table is not
//! a compression choice but a *capability* one: a host embedding the harness to
//! summarise documents has no use for the crypto belt at any disclosure level,
//! and a host driving its own routing may want every schema on the wire because
//! it does not pay the orchestrator's budget. Neither is expressible by
//! membership alone, which only ever answers "advertised or withheld".
//!
//! So the group id — the same string the model names in `use_skill` — becomes
//! the unit an embedder selects on, with three states rather than two:
//!
//! | [`GroupMode`] | Schemas on the wire | Registered and callable |
//! | --- | --- | --- |
//! | `Advertised` | yes | yes |
//! | `Withheld` | no (reached via `use_skill`) | yes |
//! | `Off` | no | **no** |
//!
//! `Off` is the state that could not be said before, and it is the one an
//! embedder reaches for most: absence beats a registered tool that fails, for
//! the reason the `flows` compile gate already documents — a tool the model can
//! see teaches it the capability exists and makes it retry.
//!
//! **The default is fail-closed, which is not the same as inert.**
//! [`ToolGroups::default`] puts every pack in `Withheld`. That was identical to
//! the compiled-in table when this type was introduced, and it stops being
//! identical every time a family moves into a pack: a host that never calls
//! [`CoreBuilder::tool_groups`](crate::core::runtime::CoreBuilder::tool_groups)
//! loses that family silently on its next bump. An embedder that packs nothing
//! on purpose says so with [`set_process_default`], which needs no
//! `CoreContext` and so is reachable from the synchronous paths that actually
//! read this — a roster build, an agent build, a host's own test fixtures.
//!
//! **This axis does not widen what a build contains.** A group whose tools are
//! compiled out (`--no-default-features`) or whose `DomainGroup` is off under
//! the ambient `DomainSet` stays absent no matter what mode is set here;
//! `Advertised` cannot conjure a tool that was never registered. The three
//! filters compose one way only — narrowing.

use super::registry::PACKS;

/// How one tool group reaches the model.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum GroupMode {
    /// Schemas are on the wire on every provider call.
    Advertised,
    /// Registered and executable, but reached only through `use_skill`.
    /// The compiled-in default for every pack.
    #[default]
    Withheld,
    /// Not registered at all — the tools do not exist for this core.
    Off,
}

/// The number of compiled-in groups. `const` so [`ToolGroups`] can be a fixed
/// array and carry no allocation.
pub const GROUP_COUNT: usize = PACKS.len();

/// Per-group disclosure for one core.
///
/// Indexed positionally against [`PACKS`]; ids are resolved through
/// [`ToolGroups::index_of`] so a caller never depends on pack order.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ToolGroups {
    modes: [GroupMode; GROUP_COUNT],
}

impl Default for ToolGroups {
    /// Every group withheld.
    ///
    /// This was "byte-identical to the behaviour before this type existed" when
    /// written, and that held only while the packs were empty of anything a
    /// host actually used. It is no longer true: every family moved into a pack
    /// since is one this default withholds from a host that never asked for
    /// packing. It is a deliberate fail-closed floor, not a no-op — a host that
    /// wants the other posture says so via
    /// [`set_process_default`](super::set_process_default) or a `CoreContext`.
    fn default() -> Self {
        Self {
            modes: [GroupMode::Withheld; GROUP_COUNT],
        }
    }
}

impl ToolGroups {
    /// Every group withheld. The desktop app's shape, and the default.
    pub fn packed() -> Self {
        Self::default()
    }

    /// Every group's schemas on the wire.
    ///
    /// For a host that does not pay the orchestrator's per-turn schema budget —
    /// a short-lived harness run, or an embedder doing its own routing — and
    /// wants native function calling rather than the `use_skill` envelope.
    pub fn advertised() -> Self {
        Self {
            modes: [GroupMode::Advertised; GROUP_COUNT],
        }
    }

    /// No group's tools registered at all: the baseline belt only.
    ///
    /// The starting point for a host that opts individual groups back in, the
    /// way `DomainSet::kernel()` is for domains.
    pub fn none() -> Self {
        Self {
            modes: [GroupMode::Off; GROUP_COUNT],
        }
    }

    /// Set one group's mode. Unknown ids are ignored — a group id is data, and
    /// a build that compiled a family out should not panic a host that still
    /// names it.
    pub fn with(mut self, id: &str, mode: GroupMode) -> Self {
        if let Some(i) = Self::index_of(id) {
            self.modes[i] = mode;
        } else {
            log::warn!(
                "[toolgroups] ignoring unknown group id `{id}` (not compiled into this build)"
            );
        }
        self
    }

    /// The mode for `id`. An unknown id reports [`GroupMode::Advertised`],
    /// because a tool that belongs to no compiled-in group is never withheld.
    pub fn mode(&self, id: &str) -> GroupMode {
        Self::index_of(id)
            .map(|i| self.modes[i])
            .unwrap_or(GroupMode::Advertised)
    }

    /// The mode owning `tool`, or [`GroupMode::Advertised`] when no group does.
    pub fn mode_for_tool(&self, tool: &str) -> GroupMode {
        match super::registry::pack_for_tool(tool) {
            Some(pack) => self.mode(pack.id),
            None => GroupMode::Advertised,
        }
    }

    /// Every compiled-in group id, in table order.
    pub fn ids() -> impl Iterator<Item = &'static str> {
        PACKS.iter().map(|p| p.id)
    }

    fn index_of(id: &str) -> Option<usize> {
        PACKS.iter().position(|p| p.id == id)
    }
}

/// The process-wide posture for a host that establishes no [`CoreContext`].
///
/// Set by [`set_process_default`]; consulted by [`current`] only when there is
/// no context to read.
///
/// [`CoreContext`]: crate::core::runtime::context::CoreContext
static PROCESS_GROUPS: std::sync::OnceLock<ToolGroups> = std::sync::OnceLock::new();

/// Set the process-wide group posture for hosts that do not establish a core context.
pub fn set_process_default(groups: ToolGroups) {
    let _ = PROCESS_GROUPS.set(groups);
}

/// The ambient groups for the running core.
///
/// Resolution order: the scoped [`CoreContext`], then the process default from
/// [`set_process_default`], then [`ToolGroups::default`] — every group
/// withheld.
///
/// That last step is a **fail-closed** default, and it is load-bearing for a
/// host that packs deliberately (the desktop app). It is the wrong answer for an
/// embedder that packs nothing on purpose, which is why the middle step exists:
/// an embedder had no way to say so, so filling a pack silently removed
/// capability from it on the next bump.
///
/// [`CoreContext`]: crate::core::runtime::context::CoreContext
pub fn current() -> ToolGroups {
    resolve(
        crate::core::runtime::context::CoreContext::current().map(|c| c.tool_groups()),
        PROCESS_GROUPS.get().cloned(),
    )
}

/// The precedence itself, as a pure function of its two inputs.
///
/// Split out so the ordering is testable without touching process state:
/// `PROCESS_GROUPS` is a `OnceLock`, so a test that set it would decide the
/// posture for every other test sharing the binary — including the ones
/// asserting that packed tools *are* withheld.
fn resolve(scoped: Option<ToolGroups>, process: Option<ToolGroups>) -> ToolGroups {
    scoped.or(process).unwrap_or_default()
}

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