Skip to content

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

21.3 KB
Raw Blame
//! Turning an [`AgentSpec`] into an [`AgentInner`] on a [`Runtime`].
//!
//! Order matters and is fixed here: validate the id, lay out directories,
//! assemble the per-agent `Config` (base → access → provider → MCP →
//! Composio → memory binding → escape hatch), build the definition, copy skills, check the
//! narrowing rules, derive the context.

use std::path::Path;

use openhuman_core::agent_registry::host_definition::{AgentDefinition, AgentDefinitionRegistry};
use openhuman_core::core::all::DomainGroup;
use openhuman_core::core::runtime::{ContextOverlay, DomainSet};
use openhuman_core::tools::toolpacks::{GroupMode, ToolGroups};
use tinyagents_definition::SubagentEntry;

use super::{AgentError, AgentInner, AgentLayout, AgentSpec};
use crate::harness::Access;
use crate::runtime::Runtime;

pub(crate) fn instantiate(runtime: &Runtime, spec: AgentSpec) -> Result<AgentInner, AgentError> {
    let mut parts = spec.into_parts();
    let defaults = runtime.defaults();
    let mut runtime_definition = defaults.definition.clone();
    if defaults.sandbox != crate::SandboxModeSpec::None {
        runtime_definition = runtime_definition.sandbox(defaults.sandbox);
    }
    if let Some(v) = defaults.model.temperature {
        runtime_definition = runtime_definition.temperature(v);
    }
    if let Some(v) = defaults.model.max_iterations {
        runtime_definition = runtime_definition.max_iterations(v);
    }
    let mut inherited = if let Some(name) = parts.template.take() {
        defaults
            .templates
            .get(&name)
            .cloned()
            .ok_or(AgentError::UnknownTemplate(name))?
            .inherit(runtime_definition)?
    } else {
        runtime_definition
    };
    let mut model_defaults = defaults.model.overlay(&parts.model_defaults);
    model_defaults.validate().map_err(AgentError::Invalid)?;
    if let Some(v) = parts.model_defaults.temperature {
        inherited = inherited.temperature(v);
    }
    if let Some(v) = parts.model_defaults.max_iterations {
        inherited = inherited.max_iterations(v);
    }
    parts.definition = parts.definition.inherit(inherited)?;
    let include_user_skills = parts
        .include_user_skills
        .unwrap_or(defaults.skills.include_user_skills);
    #[cfg(feature = "skills")]
    {
        parts.skills_dir = parts.skills_dir.or(defaults.skills.root.clone());
    }
    #[cfg(feature = "mcp")]
    {
        let mut servers = defaults.mcp_baseline.clone();
        servers.extend(parts.mcp_servers);
        parts.mcp_servers = servers;
    }

    let id = parts.id;
    validate_agent_id(&id).map_err(|reason| AgentError::InvalidId {
        id: id.clone(),
        reason,
    })?;
    let catalogue = process_catalogue();
    if catalogue.get(&id).is_some() {
        return Err(AgentError::ReservedId(id));
    }

    // A host-only agent must never act, whatever else the spec says, so its
    // exclusions are settled before any of the spec is applied.
    let host_only = parts.definition.is_host_only();
    if host_only {
        #[cfg(feature = "mcp")]
        if !parts.mcp_servers.is_empty() {
            return Err(AgentError::Invalid(
                "a HostOnly agent cannot declare MCP servers; supply its tools as host tools"
                    .into(),
            ));
        }
        #[cfg(feature = "skills")]
        if parts.skills_dir.is_some() {
            return Err(AgentError::Invalid(
                "a HostOnly agent cannot install skills".into(),
            ));
        }
    }

    let base = runtime.base_config();
    let root_dir = base
        .config_path
        .parent()
        .map(Path::to_path_buf)
        .unwrap_or_default();

    // ── config ───────────────────────────────────────────────────────────
    let mut config = base.clone();
    // Modeled default; `config.action_dir` is the field every later step
    // (including the `config_fn` escape hatch below) actually reads and can
    // override, so the directory we create and the layout we resolve are
    // taken from it again below, after every step has had a chance to touch
    // it — not from this local, which would go stale the moment a caller's
    // `config_fn` edits `config.action_dir`.
    config.action_dir = parts.action_dir.unwrap_or_else(|| {
        AgentLayout::default_action_dir(
            &root_dir,
            &base.action_dir,
            runtime.inherited_workspace(),
            &id,
        )
    });

    let mut access = parts.access.unwrap_or_else(|| defaults.access.clone());
    for (path, grant) in parts.trusted {
        access = access.trust(path, grant);
    }
    if host_only {
        // Read-only regardless of what was asked: no tier that could park a
        // write for approval, no automation origin, no trusted roots.
        log::debug!("[embed][agent] id={id} is host-only; forcing read-only access");
        access = Access::readonly();
    }
    access.apply(&mut config);

    let provider = if parts.inherit_provider_route {
        match parts.provider.as_ref().and_then(crate::Provider::model_id) {
            Some(model) => defaults.provider.clone().model(model),
            None => defaults.provider.clone(),
        }
    } else {
        parts.provider.unwrap_or_else(|| defaults.provider.clone())
    };
    crate::runtime::builder::apply_provider(&mut config, &provider);
    if let Some(v) = parts.model_defaults.temperature {
        config.default_temperature = v;
    }
    if let Some(v) = parts.model_defaults.max_iterations {
        config.agent.max_tool_iterations_override = Some(v);
    }

    #[cfg(feature = "mcp")]
    if !parts.mcp_servers.is_empty() {
        config.mcp_client.enabled = true;
        config.mcp_client.servers.extend(
            parts
                .mcp_servers
                .iter()
                .cloned()
                .map(crate::harness::McpServer::into_config),
        );
    }

    if let Some(credential) = parts.composio {
        log::debug!("[embed][agent] id={id} pins its own composio credential");
        config.composio.pin_host_credential(credential);
    }

    if let Some(binding) = parts.memory {
        let agent_id = binding.agent_id().trim();
        if agent_id.is_empty() {
            return Err(AgentError::Invalid(
                "a memory binding needs an agent id".into(),
            ));
        }
        if let Some(root) = binding.root_namespace() {
            tinymemory_tools::layout::identity::validate_root(root)
                .map_err(|reason| AgentError::Invalid(format!("memory root {root:?}: {reason}")))?;
        }
        log::debug!("[embed][agent] id={id} binds its memory agent_id={agent_id}");
        config.memory.agent_id = Some(agent_id.to_string());
        config.memory.root = binding.root_namespace().map(|root| root.trim().to_string());
        config.memory.recall_each_turn_ms = binding
            .recall_each_turn_timeout()
            .map(|timeout| u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX));
    }

    if let Some(f) = parts.config_fn {
        f(&mut config);
        // Every agent shares the runtime's credential store and keyring; a
        // moved `config_path` would silently point this agent at another.
        config.config_path = base.config_path.clone();
    }
    // Runtime::agent holds the agent-map lock across instantiate. Check the
    // final workspace (after the config escape hatch) before creating any
    // directories, so a new agent cannot reuse an id whose old MCP service
    // still awaits close acknowledgment.
    if openhuman_core::mcp::host::agent_close_pending(&config.workspace_dir, &id) {
        return Err(AgentError::CleanupPending);
    }
    if host_only {
        // After the escape hatch, so it cannot loosen either.
        Access::readonly().apply(&mut config);
        config.mcp_client.enabled = false;
    }

    // Read back now, after `config_fn` (the escape hatch, applied above) has
    // had its chance to edit `config.action_dir` — the directory created and
    // the layout resolved below must match whatever it ends up being, not
    // the pre-`config_fn` default computed further up.
    let action_dir = config.action_dir.clone();
    std::fs::create_dir_all(&action_dir).map_err(|source| AgentError::Workspace {
        what: "create the agent's action directory",
        source,
    })?;
    let layout = AgentLayout::resolve(&config.workspace_dir, &id, action_dir);
    std::fs::create_dir_all(&layout.home).map_err(|source| AgentError::Workspace {
        what: "create the agent's home",
        source,
    })?;
    std::fs::create_dir_all(&layout.skills).map_err(|source| AgentError::Workspace {
        what: "create the agent's skills directory",
        source,
    })?;

    // ── skills ───────────────────────────────────────────────────────────
    #[cfg(feature = "skills")]
    if let Some(dir) = parts.skills_dir.as_deref() {
        let dest = match parts.skills_dest {
            super::spec::SkillsDest::AgentLocal => layout.skills.clone(),
            super::spec::SkillsDest::WorkspaceLegacy => config.workspace_dir.join("skills"),
        };
        crate::harness::skills::install(dir, &dest).map_err(map_harness_err)?;
    }

    // ── definition ───────────────────────────────────────────────────────
    let mut definition = parts.definition.into_core(&id)?;
    model_defaults.temperature = Some(definition.temperature);
    model_defaults.max_iterations = Some(definition.max_iterations);
    if config.agent.max_tool_iterations_override.is_some() {
        config.agent.max_tool_iterations_override = Some(definition.max_iterations);
    }

    // Every declared server's tools are registered as their own
    // `mcp_<server>_<tool>`, deferred by default. A wildcard belt reaches them
    // through `tool_search` already; a named belt reaches deferred tools only
    // when it lists `tool_search`, so declaring a server implies it.
    #[cfg(feature = "mcp")]
    if !parts.mcp_servers.is_empty() {
        opt_named_belt_into_discovery(&mut definition.tools);
    }

    // A named scope is an explicit allowlist: unless it names a spawn tool it
    // cannot reach the inherited built-in sub-agent roster.
    let declares_subagents = !parts.subagents.is_empty();
    if matches!(definition.tools, tinyagents_definition::ToolScope::Named(_))
        && !definition.tools.names_a_spawn_tool()
        && !definition.subagents.is_empty()
    {
        log::debug!(
            "[embed][agent] id={id} named scope names no spawn tool; dropping {} inherited sub-agent(s)",
            definition.subagents.len()
        );
        definition.subagents.clear();
    }
    if !host_only && declares_subagents {
        opt_named_belt_into_spawn(&mut definition.tools);
    }
    let definitions = own_catalogue(&catalogue, &id, &mut definition, parts.subagents)?;

    // ── narrowing ────────────────────────────────────────────────────────
    let domains = match parts.domains {
        Some(requested) => {
            check_domains_narrow(requested, runtime.domains())?;
            requested
        }
        None => runtime.domains(),
    };
    let tool_groups = match parts.tool_groups {
        Some(requested) => {
            check_tool_groups_narrow(&requested, runtime.tool_groups())?;
            requested
        }
        None => runtime.tool_groups().clone(),
    };

    // ── context ──────────────────────────────────────────────────────────
    let mut context_config = config.clone();
    context_config.ephemeral_route = provider.route().and_then(|route| {
        openhuman_core::config::schema::EphemeralRoute::from_params(
            Some(route.base_url.clone()),
            Some(route.api_key.clone()),
        )
        .map(|scoped| {
            scoped
                .with_headers(route.headers.clone())
                .with_provider_options(route.provider_options.clone())
                .with_reasoning_effort(
                    route
                        .reasoning_effort
                        .map(|effort| effort.as_str().to_string()),
                )
        })
    });
    let mut overrides = openhuman_core::agent::host_overrides::HostOverrides::default();
    overrides.parent = runtime.core_runtime().context().host_overrides();
    let lifecycle = super::lifecycle::Lifecycle::new();
    overrides.approval_scope = Some(lifecycle.approval_scope());
    overrides.model = provider.custom_model();
    overrides.role_models = provider.role_models().clone();
    overrides.session_store = parts.session_store;
    if let tinyagents_definition::ToolScope::Named(names) = &definition.tools {
        overrides.named_tools = Some(std::sync::Arc::new(names.iter().cloned().collect()));
    }
    let overrides = std::sync::Arc::new(overrides);
    for (index, hook) in parts.post_turn_hooks.into_iter().enumerate() {
        overrides.post_turn_hook(&format!("agent.learning_sink.{index:020}"), Some(hook));
    }
    for hook in parts.tool_hooks {
        overrides.tool_hook(hook.name(), Some(hook.clone()));
    }
    let overlay = ContextOverlay {
        host_overrides: Some(overrides.clone()),
        config: context_config,
        domains,
        tool_groups,
        user_skill_roots: include_user_skills,
        // A host session store keeps each agent's conversations apart by id.
        session_agent: Some(id.to_string()),
        profile: None,
        agent_policy: Some(std::sync::Arc::new(
            openhuman_core::security::SecurityPolicy::from_config(
                &config.autonomy,
                &config.workspace_dir,
                &config.action_dir,
            )
            .with_privacy_mode(config.privacy.mode),
        )),
        autonomy_tier_source: Some(openhuman_core::core::runtime::AutonomyTierSource::Captured),
        autonomy_tier_ceiling: host_only
            .then_some(openhuman_core::security::AutonomyLevel::ReadOnly),
        approvals_disabled: !access.approval_gate_enabled(),
        definitions,
    };
    let ctx = runtime
        .core_runtime()
        .context()
        .derive_with_parent_config(base, overlay);
    let approval_subscription = parts.approval_handler.map(|handler| {
        super::approval_handler::ApprovalSubscription::new(
            &id,
            handler,
            lifecycle.removed(),
            lifecycle.approval_state(),
            Some(std::sync::Arc::downgrade(&ctx)),
        )
    });
    openhuman_core::core::runtime::AgentContextRegistry::register(&id, &ctx);

    log::debug!(
        "[embed][agent] instantiated id={id} action_dir={} routed={} access_origin={} \
         user_skills={} tier={:?} approval_gate={}",
        config.action_dir.display(),
        provider.is_routed(),
        access.turn_origin().is_some(),
        include_user_skills,
        config.autonomy.level,
        access.approval_gate_enabled()
    );

    Ok(AgentInner {
        registry: runtime.agent_registry(),
        overrides,
        _approval_subscription: approval_subscription,
        id,
        runtime_id: runtime.runtime_id().to_owned(),
        attachments: Default::default(),
        _runtime_guard: runtime.guard(),
        runtime: runtime.core_runtime().clone(),
        ctx,
        config,
        definition,
        provider,
        model_defaults,
        access,
        layout,
        host_tools: parts.host_tools,
        hooks: parts.hooks,
        lifecycle,
        mcp_cleanup: Default::default(),
        host_only,
    })
}

/// The process catalogue: the booted registry, or the built-ins when none
/// was initialised.
fn process_catalogue() -> std::sync::Arc<AgentDefinitionRegistry> {
    AgentDefinitionRegistry::global_arc()
        .unwrap_or_else(|| std::sync::Arc::new(AgentDefinitionRegistry::builtins_only()))
}

/// The catalogue an agent with its own sub-agents delegates through: the
/// process catalogue plus the agent and its sub-agents. `None` (resolve
/// through the process catalogue) for an agent without sub-agents.
fn own_catalogue(
    catalogue: &AgentDefinitionRegistry,
    id: &str,
    definition: &mut AgentDefinition,
    subagents: Vec<(String, super::AgentDefinitionSpec)>,
) -> Result<Option<std::sync::Arc<AgentDefinitionRegistry>>, AgentError> {
    if subagents.is_empty() {
        return Ok(None);
    }
    let mut own = Vec::with_capacity(subagents.len() + 1);
    let mut seen = std::collections::HashSet::new();
    for (sub_id, spec) in subagents {
        validate_agent_id(&sub_id).map_err(|reason| AgentError::InvalidId {
            id: sub_id.clone(),
            reason,
        })?;
        if catalogue.get(&sub_id).is_some() {
            return Err(AgentError::ReservedId(sub_id));
        }
        if sub_id == id || !seen.insert(sub_id.clone()) {
            return Err(AgentError::DuplicateId(sub_id));
        }
        definition
            .subagents
            .push(SubagentEntry::AgentId(sub_id.clone()));
        own.push(spec.into_subagent_core(&sub_id)?);
    }
    own.push(definition.clone());
    log::debug!(
        "[embed][agent] id={id} owns a catalogue with {} sub-agent(s)",
        own.len() - 1
    );
    Ok(Some(std::sync::Arc::new(catalogue.with_definitions(own))))
}

/// Adds `tool_search` to a named belt that lacks it. A wildcard belt already
/// has discovery.
#[cfg(feature = "mcp")]
fn opt_named_belt_into_discovery(scope: &mut tinyagents_definition::ToolScope) {
    use tinyagents_definition::ToolScope;
    const TOOL_SEARCH: &str = "tool_search";
    if let ToolScope::Named(names) = scope {
        if !names.iter().any(|name| name == TOOL_SEARCH) {
            names.push(TOOL_SEARCH.to_string());
            log::debug!("[embed][agent] declared MCP servers opt the named belt into tool_search");
        }
    }
}

/// Lets a named-scope agent reach only the child agents it explicitly owns.
/// Apply the existing inherited-roster policy first and exclude HostOnly
/// agents, whose named empty belt is a hard prohibition on acting tools.
fn opt_named_belt_into_spawn(scope: &mut tinyagents_definition::ToolScope) {
    use tinyagents_definition::ToolScope;
    const SPAWN_SUBAGENT: &str = "spawn_subagent";
    if let ToolScope::Named(names) = scope {
        if !names.iter().any(|name| name == SPAWN_SUBAGENT) {
            names.push(SPAWN_SUBAGENT.to_string());
            log::debug!(
                "[embed][agent] declared sub-agents opt the named belt into spawn_subagent"
            );
        }
    }
}

fn validate_agent_id(id: &str) -> Result<(), String> {
    let bytes = id.as_bytes();
    if bytes.is_empty() || bytes.len() > 64 {
        return Err("must be 1 to 64 characters".to_string());
    }
    if !bytes[0].is_ascii_lowercase() && !bytes[0].is_ascii_digit() {
        return Err("must start with a lowercase letter or digit".to_string());
    }
    if bytes.iter().any(|byte| {
        !byte.is_ascii_lowercase() && !byte.is_ascii_digit() && *byte != b'_' && *byte != b'-'
    }) {
        return Err("may contain only lowercase letters, digits, '_' and '-'".to_string());
    }
    Ok(())
}

/// Every family the agent asks for must be one the runtime registered.
pub(crate) fn check_domains_narrow(
    requested: DomainSet,
    runtime: DomainSet,
) -> Result<(), AgentError> {
    let widened: Vec<String> = DomainGroup::ALL
        .iter()
        .filter(|group| requested.allows(**group) && !runtime.allows(**group))
        .map(|group| format!("{group:?}").to_lowercase())
        .collect();
    if widened.is_empty() {
        Ok(())
    } else {
        Err(AgentError::WidensRuntime(format!(
            "domain families not registered by the runtime: {}",
            widened.join(", ")
        )))
    }
}

/// A group may only be as exposed as the runtime exposes it:
/// `Off` ⊂ `Withheld` ⊂ `Advertised`.
pub(crate) fn check_tool_groups_narrow(
    requested: &ToolGroups,
    runtime: &ToolGroups,
) -> Result<(), AgentError> {
    fn exposure(mode: GroupMode) -> u8 {
        match mode {
            GroupMode::Off => 0,
            GroupMode::Withheld => 1,
            GroupMode::Advertised => 2,
        }
    }
    let widened: Vec<&str> = ToolGroups::ids()
        .filter(|id| exposure(requested.mode(id)) > exposure(runtime.mode(id)))
        .collect();
    if widened.is_empty() {
        Ok(())
    } else {
        Err(AgentError::WidensRuntime(format!(
            "tool groups more exposed than the runtime's: {}",
            widened.join(", ")
        )))
    }
}

#[cfg(feature = "skills")]
fn map_harness_err(err: crate::HarnessError) -> AgentError {
    match err {
        crate::HarnessError::Workspace { what, source } => AgentError::Workspace { what, source },
        crate::HarnessError::Invalid(msg) => AgentError::Invalid(msg),
        crate::HarnessError::Call(e) => AgentError::Call(e),
        crate::HarnessError::McpCleanup(e) => AgentError::McpCleanup(e),
        crate::HarnessError::Build(e) => AgentError::Invalid(format!("{e:#}")),
        crate::HarnessError::AlreadyRunning => AgentError::Invalid(err.to_string()),
    }
}

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