Skip to content

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

13.3 KB
Raw Blame
//! A runtime-owned agent: one fully described, independently configured
//! participant on a [`Runtime`](crate::Runtime).
//!
//! An [`Agent`] is a cheap clone handle over the state
//! [`Runtime::agent`](crate::Runtime::agent) assembled from an
//! [`AgentSpec`]: its own `Config` (provider route and model, MCP servers,
//! autonomy tier, `action_dir`), its
//! [`AgentDefinition`](openhuman_core::agent_registry::host_definition::AgentDefinition)
//! (system prompt, tool scope, sandbox mode), its
//! derived
//! [`CoreContext`](openhuman_core::core::runtime::CoreContext) every turn
//! dispatches under. Two agents on one runtime never read each other's
//! settings: each turn is scoped to its own context, and the core's config
//! loader, DomainSet gate, tool-group filter and skill discovery all read
//! the ambient context.

mod approval_handler;
mod approvals;
pub use approval_handler::{ApprovalHandler, ApprovalSubscription};
mod attachments;
mod compact;
pub use compact::{CompactOptions, CompactOutcome};
pub(crate) mod lifecycle;
pub(crate) mod mcp_cleanup;
pub use approvals::{ApprovalDecision, Approvals, ApprovalsError, PendingApproval};
pub use attachments::ToolAttachmentError;
pub(crate) mod build;
mod definition;
mod layout;
pub(crate) mod spec;

pub use definition::{
    AgentDefinitionSpec, DefinitionBase, MemoryBlockSpec, SandboxModeSpec, ToolScopeSpec,
};
pub use layout::AgentLayout;
pub use spec::{AgentSpec, MemoryBinding};

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

use openhuman_core::agent_registry::host_definition::AgentDefinition;
use openhuman_core::config::Config;
use openhuman_core::core::runtime::{CoreContext, CoreRuntime};

use crate::harness::{Access, Provider};
use crate::turn::{Turn, TurnOutcome, TurnTarget};
use crate::CoreError;

/// Error from instantiating or driving an [`Agent`].
#[derive(Debug, thiserror::Error)]
pub enum AgentError {
    /// A turn failed. See [`CoreError`] for the distinctions.
    #[error(transparent)]
    Call(#[from] CoreError),

    /// An agent with this id is already alive on the runtime.
    #[error("agent id {0:?} is already registered on this runtime")]
    DuplicateId(String),

    /// The id does not match `^[a-z0-9][a-z0-9_-]{0,63}$`.
    #[error("invalid agent id {id:?}: {reason}")]
    InvalidId {
        /// The offending id.
        id: String,
        /// Why it was refused.
        reason: String,
    },

    /// The spec asked for a domain family or tool group the runtime did not
    /// register. Agents can only narrow the runtime's surface.
    #[error("agent widens the runtime's surface: {0}")]
    WidensRuntime(String),

    /// A filesystem operation laying out the agent failed.
    #[error("failed to {what}")]
    Workspace {
        /// What was being attempted, phrased to complete "failed to …".
        what: &'static str,
        /// The underlying I/O error.
        #[source]
        source: std::io::Error,
    },

    /// A module-owned agent resource did not acknowledge cleanup, so its
    /// workspace could not be purged safely.
    #[error("agent cleanup is still pending; its workspace was retained")]
    CleanupPending,

    /// A spec input could not be honoured.
    #[error("{0}")]
    Invalid(String),

    /// The id names a built-in agent definition (`orchestrator`, `planner`,
    /// …), which the delegation catalogue would resolve instead of this agent.
    #[error("agent id {0:?} is reserved for a built-in agent definition")]
    ReservedId(String),

    /// The runtime already hosts its configured maximum of live agents
    /// ([`RuntimeBuilder::max_agents`](crate::RuntimeBuilder::max_agents)).
    #[error("the runtime already hosts its limit of {limit} agents")]
    AgentLimit {
        /// The configured maximum.
        limit: usize,
    },

    /// No live agent with this id is registered on the runtime.
    #[error("no agent {0:?} is registered on this runtime")]
    UnknownId(String),
    /// A named template was not registered on this runtime.
    #[error("unknown agent template {0:?}")]
    UnknownTemplate(String),
    /// A named built-in definition does not exist.
    #[error("unknown built-in agent definition {0:?}")]
    UnknownDefinition(String),
    /// The agent is removed, but its original MCP owner still needs cleanup.
    /// Its id and home remain reserved while detached cleanup retries.
    #[error("agent MCP cleanup is still pending: {0}")]
    McpCleanup(#[source] tinybus::module::ModuleCallError),
}

/// The assembled state behind an [`Agent`], shared by every clone of it and
/// by every [`Turn`] it issues.
pub(crate) struct AgentInner {
    pub(crate) id: String,
    /// A dead weak entry remains reserved until this instance finishes teardown.
    registry: Arc<crate::runtime::AgentMap>,
    pub(crate) overrides: Arc<openhuman_core::agent::host_overrides::HostOverrides>,
    _approval_subscription: Option<ApprovalSubscription>,
    pub(crate) runtime_id: String,
    pub(crate) attachments: attachments::Attachments,
    /// Keeps the runtime's core and (for an ephemeral workspace) its
    /// directory alive for as long as this agent is, even after the host
    /// drops its `Runtime` handle. See
    /// [`CoreGuard`](crate::runtime::CoreGuard).
    pub(crate) _runtime_guard: Arc<crate::runtime::CoreGuard>,
    pub(crate) runtime: Arc<CoreRuntime>,
    pub(crate) ctx: Arc<CoreContext>,
    pub(crate) config: Config,
    pub(crate) definition: AgentDefinition,
    pub(crate) provider: Provider,
    pub(crate) model_defaults: crate::ModelDefaults,
    pub(crate) access: Access,
    pub(crate) layout: AgentLayout,
    /// The agent's own in-process tools, rebuilt per turn. See
    /// [`AgentSpec::tools`](super::AgentSpec::tools) for why it is a factory.
    pub(crate) host_tools: Option<openhuman_core::agent::HostTools>,
    pub(crate) hooks: tinyagents_hooks::scope::HookScope<
        openhuman_core::agent::tinyagents::host::OpenHumanRunContext,
        tinyagents_harness::cost::TurnCost,
    >,
    pub(crate) lifecycle: lifecycle::Lifecycle,
    pub(crate) mcp_cleanup: std::sync::Mutex<Option<openhuman_core::mcp::host::AgentMcpCleanup>>,
    /// Built from [`ToolScopeSpec::HostOnly`]: every turn's session is built
    /// from the host tools alone.
    pub(crate) host_only: bool,
}

impl AgentInner {
    /// Denies parked approvals, clears state slots and deregisters the context.
    /// Captures the original MCP owner's cleanup without creating a client;
    /// explicit removal awaits it and final drop schedules it. Runs once.
    pub(crate) fn teardown(&self, resolution: &str) {
        if !self.lifecycle.begin_teardown() {
            return;
        }
        self.lifecycle.mark_removed(resolution);
        self._runtime_guard.events.emit(
            Some(self.id.clone()),
            None,
            crate::RuntimeEventKind::AgentRemoved,
        );
        self.deny_approvals(resolution);
        self.ctx.agent_state().clear();
        *self
            .mcp_cleanup
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner) =
            openhuman_core::mcp::host::take_agent_cleanup(&self.config.workspace_dir, &self.id);
        openhuman_core::core::runtime::AgentContextRegistry::deregister(&self.id, &self.ctx);
        log::debug!("[embed][agent] teardown complete id={}", self.id);
    }

    /// Denies every approval this agent has parked, with `resolution`.
    pub(crate) fn deny_approvals(&self, resolution: &str) {
        if let Some(scope) = self.ctx.host_overrides().and_then(|o| o.approval_scope()) {
            scope.close(resolution);
        }
        let Some(gate) = openhuman_core::security::approval::ApprovalGate::try_global() else {
            return;
        };
        match gate.deny_all_for_agent(
            &openhuman_core::core::runtime::DispatchCtx::new(Arc::clone(&self.ctx)),
            &self.id,
            resolution,
        ) {
            Ok(denied) => log::debug!(
                "[embed][agent] id={} denied_approvals={denied} resolution={resolution}",
                self.id
            ),
            Err(error) => log::warn!(
                "[embed][agent] id={} could not deny approvals: {error}",
                self.id
            ),
        }
    }
}

impl Drop for AgentInner {
    fn drop(&mut self) {
        self.teardown("agent_dropped");
        self.defer_cleanup(false);
    }
}

/// A handle to one agent on a runtime.
///
/// Cheap to clone; every clone drives the same agent. The id is released for
/// reuse after the last clone's MCP cleanup completes. Dropping an agent does **not** remove
/// its directories — its transcripts and memory persist with the runtime's
/// workspace.
#[derive(Clone)]
pub struct Agent {
    inner: Arc<AgentInner>,
}

impl Agent {
    pub(crate) fn from_inner(inner: Arc<AgentInner>) -> Self {
        Self { inner }
    }

    /// The id this agent was created with.
    pub fn id(&self) -> &str {
        &self.inner.id
    }

    /// Run one turn and get the reply.
    ///
    /// Each call starts a **new** conversation. Pass the returned
    /// [`TurnOutcome::session_id`] to [`Agent::turn`] + [`Turn::session`] to
    /// continue one.
    pub async fn run(&self, message: impl Into<String>) -> Result<TurnOutcome, AgentError> {
        self.turn(message).send().await.map_err(Into::into)
    }

    /// Begin a turn, to configure before sending.
    ///
    /// The agent's provider route, model and access origin are pre-applied;
    /// anything set on the returned [`Turn`] overrides them for that turn
    /// alone.
    pub fn turn(&self, message: impl Into<String>) -> Turn {
        let mut turn = Turn::new(TurnTarget::Agent(Arc::clone(&self.inner)), message)
            .with_agent_id(&self.inner.id)
            .with_hooks(self.inner.hooks.clone());
        if let Some(route) = self.inner.provider.route() {
            turn = turn.route(route.clone());
        }
        if let Some(model) = self.inner.provider.model_id() {
            turn = turn.model(model);
        }
        if let Some(origin) = self.inner.access.turn_origin() {
            turn = turn.origin(origin.clone());
        }
        if let Some(value) = self.inner.model_defaults.max_tokens {
            turn = turn.max_tokens(value);
        }
        if let Some(value) = self.inner.model_defaults.top_p {
            turn = turn.top_p(value);
        }
        turn
    }

    /// Start a streaming turn; dropping the stream requests cooperative cancellation.
    pub fn stream(&self, message: impl Into<String>) -> crate::TurnStream {
        self.turn(message).stream()
    }

    /// Subscribe a host callback to this agent’s pending approvals.
    /// Removing the agent cancels its callbacks, even if its id is reused.
    pub fn handle_approvals(&self, handler: Arc<dyn ApprovalHandler>) -> ApprovalSubscription {
        ApprovalSubscription::new(
            self.id(),
            handler,
            self.inner.lifecycle.removed(),
            self.inner.lifecycle.approval_state(),
            Some(Arc::downgrade(&self.inner.ctx)),
        )
    }

    /// Add, replace, or remove an agent-local post-turn hook by name.
    pub fn post_turn_hook(&self, name: &str, hook: Option<Arc<dyn crate::seams::LearningSink>>) {
        self.inner.overrides.post_turn_hook(name, hook);
    }

    /// Add, replace, or remove an agent-local tool hook by name.
    pub fn tool_hook(
        &self,
        name: &str,
        hook: Option<Arc<dyn crate::seams::ToolHook<crate::seams::OpenHumanRunContext>>>,
    ) {
        self.inner.overrides.tool_hook(name, hook);
    }

    /// This agent's pending approvals: the requests its turns parked, and
    /// only those.
    pub fn approvals(&self) -> Approvals {
        Approvals::new(
            &self.inner.id,
            self.inner.lifecycle.removed(),
            self.inner.lifecycle.approval_state(),
            Some(Arc::downgrade(&self.inner.ctx)),
        )
    }

    /// The agent's read/write root for acting tools.
    pub fn action_dir(&self) -> &Path {
        &self.inner.config.action_dir
    }

    /// The runtime-wide workspace this agent's state lives under.
    pub fn workspace_dir(&self) -> &Path {
        &self.inner.config.workspace_dir
    }

    /// `<workspace>/agents/<id>/` — the agent's home (SOUL.md, skills/).
    pub fn home_dir(&self) -> &Path {
        &self.inner.layout.home
    }

    /// `<workspace>/agents/<id>/skills/` — where its skill bundles were
    /// copied and the only skills root it sees besides the workspace's own.
    pub fn skills_dir(&self) -> &Path {
        &self.inner.layout.skills
    }

    /// `<workspace>/agents/<id>/session_raw/`, the legacy JSONL import
    /// directory associated with this agent. New transcripts use the runtime's
    /// session-store provider and are not necessarily written to this path.
    pub fn transcripts_dir(&self) -> &Path {
        &self.inner.layout.transcripts
    }

    /// The provider this agent's turns run on.
    pub fn provider(&self) -> &Provider {
        &self.inner.provider
    }

    /// The access tier this agent's turns run with.
    pub fn access(&self) -> &Access {
        &self.inner.access
    }

    /// The config this agent was instantiated with, for inspection.
    pub fn config(&self) -> &Config {
        &self.inner.config
    }
}

impl std::fmt::Debug for Agent {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Agent")
            .field("id", &self.inner.id)
            .finish_non_exhaustive()
    }
}