The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! Which agent tools a user gets in SaaS mode, and where they run.
//!
//! A profile's tool list starts from its domain families
//! ([`host::user_domains`](super::host::user_domains)): memory and thread
//! tools, nothing that reaches the host. Shell and file tools sit in the
//! `Platform` family, which a user context never enables. The operator opts
//! into tools supplied by an embedding host with `tool_allowlist`, one
//! [`SaasToolGroup`] at a time. The allowlist grants admission, not registration:
//! the standalone SaaS CLI has no host-tool adapter and exposes neither group.
//! When an embedding host supplies the corresponding tools:
//!
//! - `host_files`: the file tools. They run in-process, confined by the
//! user's policy (`layout::profile_config`: autonomy on, workspace-only,
//! `action_dir` = the user's `sandbox/`, no other trusted roots).
//! - `host_shell`: the shell. Every command runs in a fresh container
//! ([`sandbox_policy`]) whose only writable mount is the user's `sandbox/`.
//! If the container cannot start, the command fails; it never falls back to
//! the host.
//!
//! Some tools stay out whatever the allowlist says ([`HARD_DENIED`]): they
//! change the process, install code, or reach state shared by every user.
//!
//! There is no per-user approval surface yet, so in SaaS the approval gate
//! does not park: it allows a tool from an allowlisted group, whose reach the
//! sandbox and path policy already bound, and refuses anything else
//! ([`gate_verdict`]).
use std::path::Path;
use crate::core::runtime::saas::SaasSandboxConfig;
use crate::core::runtime::{is_saas, DispatchCtx};
use crate::sandbox::{DockerOverrides, SandboxBackendKind, SandboxPolicy};
/// A group of host tools an operator can opt users into.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SaasToolGroup {
HostFiles,
HostShell,
}
impl SaasToolGroup {
pub const ALL: [Self; 2] = [Self::HostFiles, Self::HostShell];
/// The group named `id` in `tool_allowlist`.
pub fn parse(id: &str) -> Option<Self> {
Self::ALL.into_iter().find(|group| group.id() == id.trim())
}
pub fn id(self) -> &'static str {
match self {
Self::HostFiles => "host_files",
Self::HostShell => "host_shell",
}
}
/// The tools the group opens, by `Tool::name`.
pub fn tools(self) -> &'static [&'static str] {
match self {
Self::HostFiles => &[
"file_read",
"file_write",
"edit",
"apply_patch",
"grep",
"glob",
"list",
"csv_export",
"read_workspace_state",
],
Self::HostShell => &["shell"],
}
}
/// Whether the group runs code, and so needs the container sandbox.
pub fn needs_sandbox(self) -> bool {
matches!(self, Self::HostShell)
}
/// The group owning `tool`, if any.
pub fn of_tool(tool: &str) -> Option<Self> {
Self::ALL
.into_iter()
.find(|group| group.tools().contains(&tool))
}
}
/// Tool name prefixes a user never gets, allowlist or not.
pub const HARD_DENIED_PREFIXES: &[&str] = &[
"service_",
"update_",
"proxy_",
"mcp_registry_",
"skill_registry_",
"hosting_",
"browser",
"computer_",
"desktop_",
"docker_",
"process_",
];
/// Tool names a user never gets, allowlist or not.
pub const HARD_DENIED: &[&str] = &[
"install_tool",
"install_workflow_from_url",
"uninstall_workflow",
"create_skill",
"git_operations",
"curl",
"pushover",
];
/// Tools outside a profile's (or an embedded agent's) domain families that an
/// operator may still admit by naming them in
/// `tool_scope(ToolScopeSpec::Named(..))`: the scheduler (`cron`, bounded by
/// `[cron] agent_jobs_only`) and the two clock tools (`current_time`,
/// `resolve_time`, Platform tools with no reach beyond the wall clock).
/// Nothing else in those families qualifies, and a name not in the scope is
/// never registered. An embedded agent names them in its definition's scope.
pub const OPERATOR_ADMITTABLE: &[&str] = &["cron", "current_time", "resolve_time"];
/// Whether `tool` is hard-denied to users.
pub fn is_hard_denied(tool: &str) -> bool {
HARD_DENIED.contains(&tool)
|| HARD_DENIED_PREFIXES
.iter()
.any(|prefix| tool.starts_with(prefix))
}
/// The groups in an operator's `tool_allowlist`, skipping names that are not
/// groups (the boot guard refuses those).
pub fn parse_allowlist(entries: &[String]) -> Vec<SaasToolGroup> {
entries
.iter()
.filter_map(|entry| SaasToolGroup::parse(entry))
.collect()
}
/// Entries of `tool_allowlist` that name no group.
pub fn unknown_entries(entries: &[String]) -> Vec<String> {
entries
.iter()
.filter(|entry| SaasToolGroup::parse(entry).is_none())
.cloned()
.collect()
}
/// Whether a user may have `tool`, given the allowlisted `groups` and whether
/// its domain family is on (`domain_ok`). Hard-denied tools never pass; tools
/// in a host group pass only when that group is allowlisted; any other tool
/// follows its domain family.
pub fn admits_with(tool: &str, domain_ok: bool, groups: &[SaasToolGroup]) -> bool {
if is_hard_denied(tool) {
return false;
}
match SaasToolGroup::of_tool(tool) {
Some(group) => groups.contains(&group),
None => domain_ok,
}
}
/// The groups the running deployment allowlists; empty outside SaaS.
pub fn allowlisted() -> Vec<SaasToolGroup> {
super::host::host()
.map(|host| parse_allowlist(&host.saas().tool_allowlist))
.unwrap_or_default()
}
/// The tool-list filter. Outside SaaS this is the domain filter, plus the
/// [`OPERATOR_ADMITTABLE`] tools the current agent names in its scope.
pub fn admits(tool: &str, domain_ok: bool) -> bool {
// Transitional (#7801): the tool-list filter has no context of its own yet.
admits_in(&DispatchCtx::ambient(), tool, domain_ok)
}
/// [`admits`] for the agent `ctx` runs for.
pub fn admits_in(ctx: &DispatchCtx, tool: &str, domain_ok: bool) -> bool {
if !is_saas() {
return domain_ok || admitted_by_name(tool, current_named_tools(ctx).as_deref());
}
let mut admitted = admits_with(tool, domain_ok, &allowlisted());
if !admitted
&& !domain_ok
&& !is_hard_denied(tool)
&& super::capabilities::ProfileCapabilities::in_ctx(ctx)
.is_some_and(|caps| caps.names_admittable(tool))
{
admitted = true;
}
if !admitted && domain_ok {
log::debug!("[profiles][tools] withholding `{tool}` from profiles");
}
admitted
}
/// Whether `tool` is one of the [`OPERATOR_ADMITTABLE`] tools and `named`
/// lists it.
pub fn admitted_by_name(tool: &str, named: Option<&std::collections::HashSet<String>>) -> bool {
let admitted =
OPERATOR_ADMITTABLE.contains(&tool) && named.is_some_and(|names| names.contains(tool));
if admitted {
log::debug!("[profiles][tools] admitting named `{tool}` outside its domain family");
}
admitted
}
/// The named tool scope of the agent `ctx` serves, if any.
fn current_named_tools(
ctx: &DispatchCtx,
) -> Option<std::sync::Arc<std::collections::HashSet<String>>> {
ctx.host_overrides()?.named_tools()
}
/// The approval gate's answer in SaaS, where it never parks: `Ok` for a tool
/// in an allowlisted group, otherwise the refusal.
pub fn gate_verdict_with(tool: &str, groups: &[SaasToolGroup]) -> Result<(), String> {
if admits_with(tool, false, groups) {
return Ok(());
}
Err(format!(
"'{tool}' needs an approval, and this deployment has no approval surface for users"
))
}
/// [`gate_verdict_with`] for the running deployment.
pub fn gate_verdict(ctx: &crate::core::runtime::DispatchCtx, tool: &str) -> Result<(), String> {
let verdict = if super::capabilities::ProfileCapabilities::in_ctx(ctx)
.is_some_and(|caps| caps.authorizes_approval(ctx, tool))
{
super::host::ensure_hosted(ctx)
} else {
gate_verdict_with(tool, &allowlisted())
};
log::debug!(
"[profiles][tools] approval gate tool={tool} allowed={}",
verdict.is_ok()
);
verdict
}
/// Whether a Docker network name is the host network (Docker matches it
/// case-insensitively).
pub fn is_host_network(network: &str) -> bool {
network.trim().eq_ignore_ascii_case("host")
}
/// The container policy for a user's shell command. `action_dir` must be a
/// user's `sandbox/` directory under `<root>/users/<profile-id>/`, or the command is
/// refused.
pub fn sandbox_policy_with(
saas_root: &Path,
config: &SaasSandboxConfig,
action_dir: &Path,
state_dir: &Path,
) -> Result<SandboxPolicy, String> {
let users = super::layout::users_dir(saas_root);
let profile_dir = action_dir.parent();
let is_user_sandbox = profile_dir.and_then(Path::parent) == Some(users.as_path())
&& profile_dir
.and_then(Path::file_name)
.and_then(|name| name.to_str())
.is_some_and(|name| super::types::ProfileId::parse(name).is_ok())
&& action_dir.file_name().is_some_and(|name| name == "sandbox");
if !is_user_sandbox {
return Err(format!(
"{} is not a user sandbox directory",
action_dir.display()
));
}
// Resolve symlinks: the directory mounted read-write must really be this
// agent's sandbox, not a link from it to somewhere else on the host.
let resolved = action_dir
.canonicalize()
.map_err(|e| format!("{}: {e}", action_dir.display()))?;
let expected = users
.canonicalize()
.map_err(|e| format!("{}: {e}", users.display()))?
.join(profile_dir.and_then(Path::file_name).unwrap_or_default())
.join("sandbox");
if resolved != expected {
return Err(format!(
"{} resolves outside the user's sandbox",
action_dir.display()
));
}
if is_host_network(&config.network) {
return Err("the sandbox cannot use the host network".to_string());
}
Ok(SandboxPolicy {
backend: SandboxBackendKind::Docker,
workspace_root: resolved,
state_dir: state_dir.to_path_buf(),
read_only_mounts: Vec::new(),
read_write_mounts: Vec::new(),
allow_network: config.network.trim() != "none",
// Nothing from the host's environment: no PATH, HOME or USER.
env_passthrough: Vec::new(),
docker_overrides: Some(DockerOverrides {
image: Some(config.image.clone()),
network: Some(config.network.clone()),
memory_limit_mb: Some(config.memory_limit_mb),
cpu_limit: Some(config.cpu_limit),
read_only_rootfs: Some(true),
extra_caps_drop: Vec::new(),
}),
})
}
/// [`sandbox_policy_with`] for the running deployment.
pub fn sandbox_policy(action_dir: &Path, state_dir: &Path) -> Result<SandboxPolicy, String> {
let host = super::host::host().ok_or("no profile host is installed")?;
let saas = host.saas();
sandbox_policy_with(&saas.root, &saas.sandbox, action_dir, state_dir)
}
#[cfg(test)]
#[path = "tools_tests.rs"]
mod tests;