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
use super::shell_description::{command_param_description, shell_description};
use super::shell_run::{audit_once, run_in_policy, run_native, AuditOnce, YieldRequest};
#[cfg(feature = "modules")]
use super::shell_support::container_environment;
use super::shell_support::{command_failure, tool_timeout_message};
use crate::agent::tinyagents::host::run_context::{
command_environment_for_tool, dispatch_ctx_for_tool,
};
use crate::config::Config;
use crate::core::runtime::DispatchCtx;
use crate::modules::tinybox::host_runtime::RuntimeAdapter;
use crate::security::{AuditLogger, CommandExecutionLog, SecurityPolicy};
use async_trait::async_trait;
use serde_json::json;
use std::path::{Path, PathBuf};
use std::sync::{Arc, PoisonError};
use std::time::{Duration, Instant};
use tinytools::ToolRunContext;
use tinytools::{PermissionLevel, Tool, ToolCallOptions, ToolResult, ToolTimeout};
/// Maximum output size in bytes (1MB).
const MAX_OUTPUT_BYTES: usize = 1_048_576;
#[cfg(feature = "modules")]
fn docker_module_result(
output: crate::modules::tinybox::contract::DockerRunOutput,
explicit_timeout: Option<Duration>,
) -> ToolResult {
let mut stdout = output.stdout;
let mut stderr = output.stderr;
if stdout.len() > MAX_OUTPUT_BYTES {
stdout.truncate(crate::util::floor_char_boundary(&stdout, MAX_OUTPUT_BYTES));
stdout.push_str("\n... [output truncated at 1MB]");
}
if stderr.len() > MAX_OUTPUT_BYTES {
stderr.truncate(crate::util::floor_char_boundary(&stderr, MAX_OUTPUT_BYTES));
stderr.push_str("\n... [stderr truncated at 1MB]");
}
if output.timed_out {
let secs = explicit_timeout
.map(|duration| duration.as_secs())
.unwrap_or(0);
let mut message = tool_timeout_message(secs);
if !stdout.is_empty() {
message.push_str("\n[stdout]\n");
message.push_str(&stdout);
}
if !stderr.is_empty() {
message.push_str("\n[stderr]\n");
message.push_str(&stderr);
}
ToolResult::error(message)
} else if output.exit_code == 0 {
if stderr.is_empty() {
ToolResult::success(stdout)
} else {
ToolResult::success(format!("{stdout}\n[stderr]\n{stderr}"))
}
} else {
command_failure(Some(output.exit_code), &stdout, &stderr)
}
}
/// Shell command execution tool with sandboxing
pub struct ShellTool {
security: Arc<SecurityPolicy>,
runtime: Arc<dyn RuntimeAdapter>,
audit: Arc<AuditLogger>,
analysis_config: Option<Arc<Config>>,
}
impl ShellTool {
pub fn new(
security: Arc<SecurityPolicy>,
runtime: Arc<dyn RuntimeAdapter>,
audit: Arc<AuditLogger>,
) -> Self {
Self {
security,
runtime,
audit,
analysis_config: None,
}
}
/// Builds a shell tool whose command facts come from the configured
/// TinyBox module before host authorization and execution.
pub fn with_config(
security: Arc<SecurityPolicy>,
runtime: Arc<dyn RuntimeAdapter>,
audit: Arc<AuditLogger>,
config: Arc<Config>,
) -> Self {
Self {
security,
runtime,
audit,
analysis_config: Some(config),
}
}
/// Resolve the working directory for this shell invocation.
///
/// Returns the per-worker git-worktree checkout when the tinyagents harness
/// threaded a [`WorkspaceDescriptor`] into this call's
/// [`ToolExecutionContext`](tinyagents_harness::tool::ToolExecutionContext) — an edit-capable worker running with
/// `isolation = "worktree"`, whose isolated worktree root is carried on the
/// run context (`RunContext::with_workspace`) and surfaced per tool call via
/// `ToolExecutionContext::from_run_context`. Otherwise falls back to the
/// shared `self.security.action_dir`, which preserves the non-isolated
/// behaviour exactly. See #3376, #4249 (08.5).
fn effective_action_dir_for_context(&self, context: Option<&dyn ToolRunContext>) -> PathBuf {
if let Some(workspace) = context.and_then(|ctx| ctx.workspace()) {
tracing::debug!(
workspace_root = %workspace.root.display(),
policy_id = %workspace.policy_id,
"[shell] using TinyAgents workspace descriptor as action dir"
);
return workspace.root.clone();
}
self.security.action_dir.clone()
}
/// The explicit wall-clock budget for this invocation, or `None` to run
/// unbounded.
///
/// Shell commands run scripts — builds, test suites, solvers — that
/// legitimately take minutes, so there is **no** default timeout: a
/// deadline applies only when the caller passes `timeout_secs` (issue
/// #4023). A `0` explicitly disables it. Any positive value is clamped to
/// `1..=3600`. See
/// `tinyagents_harness_tools::exec::timeout::explicit_call_timeout_duration`.
fn explicit_timeout(&self, requested: Option<u64>) -> Option<Duration> {
tinyagents_harness_tools::exec::timeout::explicit_call_timeout_duration(
requested,
tinyagents_harness_tools::exec::timeout::MAX_TIMEOUT_SECS,
)
}
}
#[async_trait]
impl Tool for ShellTool {
fn name(&self) -> &str {
"shell"
}
fn description(&self) -> &str {
shell_description(self.runtime.shell_flavor())
}
fn parameters_schema(&self) -> serde_json::Value {
json!({
"type": "object",
"properties": {
"command": {
"type": "string",
"description": command_param_description(self.runtime.shell_flavor())
},
"category": {
"type": "string",
"enum": ["read", "write", "network", "install", "destructive"],
"description": "Optional self-declared risk; can only raise the approval requirement."
},
"timeout_secs": {
"type": "integer",
"minimum": 0,
"maximum": 3600,
"description": "Optional: how long (seconds) to wait before coming back. A command still running then returns its output so far and keeps running as a process you follow with `shell_process`. Default 120, at most 600; 0 waits for the command to end. Only where a command cannot be left running (four already are, or a Docker sandbox) is it stopped at this time instead. To stop a command after a time, put `timeout N` in the command."
}
},
"required": ["command"]
})
}
/// Cap shell output at ~30k chars before threading into history.
/// Verbose commands (`find /`, dependency installs, log dumps)
/// can otherwise blow past 100k chars in one call. The agent
/// rarely needs the full firehose — a head/tail/grep follow-up is
/// the right move when it does.
fn max_result_size_chars(&self) -> Option<usize> {
Some(30_000)
}
/// Shell runs scripts that legitimately take a long time, so it runs
/// unbounded unless the caller passes an explicit `timeout_secs`. This
/// keeps the harness from hard-killing a long command at the global tool
/// timeout (issue #4023).
fn timeout_policy(&self, args: &serde_json::Value) -> ToolTimeout {
match args.get("timeout_secs").and_then(|v| v.as_u64()) {
// `0` (or absent) means "no deadline".
None | Some(0) => ToolTimeout::Unbounded,
Some(secs) => ToolTimeout::Millis(secs.saturating_mul(1000)),
}
}
fn permission_level(&self) -> PermissionLevel {
PermissionLevel::Execute
}
/// Whether this shell call must be approved by the human before it runs.
/// True for any command the current tier prompts on (Write / Network /
/// Destructive in ask-before-edit; Network / Destructive in Full). The
/// harness routes these through the `ApprovalGate`; the read-only `Block`
/// and the structural guard are enforced in `run_with_security`.
fn external_effect_with_args(&self, args: &serde_json::Value) -> bool {
let command = args.get("command").and_then(|v| v.as_str()).unwrap_or("");
// This synchronous declaration cannot consult TinyBox. Be
// conservative here; the host authorization gate uses the exact
// per-call TinyBox analysis and applies the configured tier.
!command.is_empty()
}
async fn prepare_authorization(
&self,
args: &serde_json::Value,
) -> anyhow::Result<Option<serde_json::Value>> {
#[cfg(feature = "modules")]
{
let config = self
.analysis_config
.as_deref()
.ok_or_else(|| anyhow::anyhow!("command analysis is unavailable"))?;
let command = args
.get("command")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| anyhow::anyhow!("command analysis is unavailable"))?;
let analysis = crate::modules::tinybox::analyze_command(config, command.to_owned())
.await
.map_err(|_| anyhow::anyhow!("command analysis is unavailable"))?;
let analysis = serde_json::to_value(analysis)
.map_err(|_| anyhow::anyhow!("command analysis is unavailable"))?;
return Ok(Some(json!({ "analysis": analysis })));
}
#[cfg(not(feature = "modules"))]
{
let _ = args;
Err(anyhow::anyhow!("command analysis is unavailable"))
}
}
async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
self.execute_in_context(&dispatch_ctx_for_tool(None), args, None)
.await
}
async fn execute_with_context(
&self,
args: serde_json::Value,
_options: ToolCallOptions,
context: Option<&dyn ToolRunContext>,
) -> anyhow::Result<ToolResult> {
self.execute_in_context(&dispatch_ctx_for_tool(context), args, context)
.await
}
}
impl ShellTool {
async fn execute_in_context(
&self,
ctx: &DispatchCtx,
args: serde_json::Value,
context: Option<&dyn ToolRunContext>,
) -> anyhow::Result<ToolResult> {
let command = args
.get("command")
.and_then(|v| v.as_str())
.ok_or_else(|| anyhow::anyhow!("Missing 'command' parameter"))?;
// The command's deadline: in a turn, what TinyAgents' turn-budget clamp
// wrote (the model's own `timeout_secs` is its yield point, moved to
// `YIELD_AFTER_ARG` by `middleware::shell_yield`); outside a turn, the
// caller's. `None`/`0` ⇒ unbounded (issue #4023).
let requested_timeout = args.get("timeout_secs").and_then(|v| v.as_u64());
let come_back = YieldRequest::from_args(&args);
// Whether a human approved the call is the harness ApprovalGate's
// decision, which the gate records separately; that yes/no is not
// threaded into tools, so this row never claims an approval
// (`approved=false`). A command left running is audited when it ends,
// with its real outcome.
let approved = false;
let audit = audit_once(self.audit.clone(), command.to_owned(), approved);
let start = Instant::now();
let (allowed, result) = crate::sandbox::shell_progress::with_shell_progress(
context,
crate::sandbox::shell_progress::HEARTBEAT_INTERVAL,
|meter| {
self.run_with_security_in_context(
ctx,
command,
requested_timeout,
come_back,
context,
meter,
&audit,
)
},
)
.await;
let duration_ms = u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX);
// `allowed` = passed the in-tool security checks.
let hook = audit.lock().unwrap_or_else(PoisonError::into_inner).take();
if let Some(hook) = hook {
hook(allowed, !result.is_error, duration_ms);
}
Ok(result)
}
}
impl ShellTool {
/// Run the command through the security policy and runtime. Returns
/// `(allowed, result)` where `allowed=false` means the policy or rate
/// limiter blocked execution before the command was launched.
///
/// Exposed as `pub(crate)` so workflow phase scripts can reuse the
/// same gated execution path as the `shell` tool — all security
/// checks (rate limits, path guards, approval gate routing) apply
/// identically to workflow-triggered commands.
pub(crate) async fn run_with_security(
&self,
ctx: &DispatchCtx,
command: &str,
requested_timeout: Option<u64>,
) -> (bool, ToolResult) {
let come_back = YieldRequest::default();
let audit = std::sync::Mutex::new(None);
self.run_with_security_in_context(
ctx,
command,
requested_timeout,
come_back,
None,
None,
&audit,
)
.await
}
async fn run_with_security_in_context(
&self,
ctx: &DispatchCtx,
command: &str,
requested_timeout: Option<u64>,
come_back: YieldRequest,
context: Option<&dyn ToolRunContext>,
meter: Option<crate::sandbox::shell_progress::ShellOutputMeter>,
audit: &AuditOnce,
) -> (bool, ToolResult) {
let command_environment = command_environment_for_tool(context);
// Revalidate facts immediately before execution. The authorization
// hook supplies the same module-owned parser to the harness gate; this
// second call keeps direct/workflow execution on the same contract and
// fails closed if the module disappeared after approval.
#[cfg(feature = "modules")]
if let Some(config) = self.analysis_config.as_deref() {
let analysis =
match crate::modules::tinybox::analyze_command(config, command.to_owned()).await {
Ok(analysis) => analysis,
Err(_) => {
return (false, ToolResult::error("Command analysis is unavailable."));
}
};
if let Err(reason) = self.security.check_gated_command_analysis(&analysis) {
return (false, ToolResult::error(reason));
}
} else {
#[cfg(test)]
if let Err(reason) = self.security.check_gated_command(command) {
// Unit tests exercise the standalone policy helper without
// booting TinyBus. Production constructors always carry the
// module config and never use this compatibility path.
return (false, ToolResult::error(reason));
}
#[cfg(not(test))]
return (false, ToolResult::error("Command analysis is unavailable."));
}
#[cfg(not(feature = "modules"))]
{
let _ = &self.analysis_config;
let _ = command;
#[cfg(test)]
if let Err(reason) = self.security.check_gated_command(command) {
return (false, ToolResult::error(reason));
}
#[cfg(not(test))]
return (false, ToolResult::error("Command analysis is unavailable."));
}
let _cwd = self.effective_action_dir_for_context(context);
if self.security.is_rate_limited() {
return (
false,
ToolResult::error("Rate limit exceeded: too many actions in the last hour"),
);
}
if !self.security.record_action() {
return (
false,
ToolResult::error("Rate limit exceeded: action budget exhausted"),
);
}
// SaaS: every command runs in the user's container, whatever the
// agent's sandbox mode says, and never on the host.
let saas_action_dir = self.effective_action_dir_for_context(context);
if let Some(resolved) =
super::shell_saas::saas_sandbox_with(crate::core::runtime::is_saas(), || {
crate::profiles::tools::sandbox_policy(
&saas_action_dir,
&self.security.workspace_dir,
)
})
{
let action_dir = saas_action_dir;
return match resolved {
Ok(policy) => {
let (timeout, dir) = (requested_timeout, &action_dir);
run_in_policy(
ctx, policy, command, timeout, come_back, dir, context, meter, audit,
)
.await
}
Err(why) => {
tracing::warn!(reason = %why, "[shell] SaaS sandbox refused the command");
// Nothing ran: report it as not allowed.
super::shell_saas::saas_sandbox_refusal(&why)
}
};
}
// A sandboxed agent or an explicit operator backend uses the sandbox
// execution path. Security checks above still apply.
let sandbox_required = match crate::sandbox::command_requires_sandbox(
ctx,
crate::agent::tinyagents::host::run_context::sandbox_mode_for_tool(context),
)
.await
{
Ok(required) => required,
Err(err) => {
return (
false,
ToolResult::error(format!("Cannot read sandbox configuration: {err}")),
);
}
};
if sandbox_required {
let action_dir = self.effective_action_dir_for_context(context);
let timeout = requested_timeout;
return self
.run_sandboxed(
ctx,
command,
timeout,
come_back,
&action_dir,
context,
meter,
audit,
)
.await;
}
// Clear the environment to prevent leaking API keys and other secrets
// (CWE-200), then re-add only safe, functional variables.
let action_dir = self.effective_action_dir_for_context(context);
#[cfg(feature = "modules")]
if let Some((mut request, mount_workspace)) =
self.runtime.build_docker_request(command, &action_dir)
{
let Some(config) = self.analysis_config.as_deref() else {
return (
false,
ToolResult::error("Docker module execution is unavailable."),
);
};
// Docker cannot leave a command running: the model's come-back
// time stays its deadline here.
let explicit_timeout =
self.explicit_timeout(come_back.deadline_instead(requested_timeout));
if let Some(timeout) = explicit_timeout {
let timeout_ms = timeout
.as_nanos()
.saturating_add(999_999)
.checked_div(1_000_000)
.unwrap_or(0)
.max(1);
let Ok(timeout_ms) = u64::try_from(timeout_ms) else {
return (
false,
ToolResult::error("Docker timeout exceeds the supported limit."),
);
};
if timeout_ms > crate::modules::tinybox::contract::MAX_DOCKER_RUN_TIMEOUT_MS {
return (
false,
ToolResult::error("Docker timeout exceeds the supported limit."),
);
}
request.timeout_ms = timeout_ms;
}
let Some(mut env) = container_environment(command_environment.as_deref()) else {
return (
false,
ToolResult::error("Docker environment contains a non-UTF-8 value."),
);
};
for (name, value) in tinyagents_harness_tools::fs::filesystem::shell_git_env() {
let (Ok(name), Ok(value)) = (name.into_string(), value.into_string()) else {
return (
false,
ToolResult::error("Docker environment contains a non-UTF-8 value."),
);
};
env.insert(name, value);
}
let scratch_dir = crate::security::openhuman_scratch_dir();
if scratch_dir.is_dir() {
let Some(scratch_dir) = scratch_dir.to_str() else {
return (
false,
ToolResult::error("Docker scratch directory is not valid UTF-8."),
);
};
for name in ["TMPDIR", "TMP", "TEMP"] {
env.insert(name.to_owned(), scratch_dir.to_owned());
}
}
request.env = env;
let result = if mount_workspace {
crate::modules::tinybox::run_docker(config, request).await
} else {
crate::modules::tinybox::run_docker_without_workspace(config, request).await
};
let result = match result {
Ok(output) => docker_module_result(output, explicit_timeout),
Err(_) => ToolResult::error("Docker module execution failed."),
};
return (true, result);
}
// The module spawns the shell: it selects cmd or bash, starts from its
// own safe environment (no API keys or other secrets, CWE-200) and owns
// the per-call scratch directory. The host adds only what it approves.
if let Err(e) = crate::config::ensure_usable_cwd(&action_dir) {
return (
true,
ToolResult::error(format!("Failed to build shell command: {e}")),
);
}
let mut env = std::collections::BTreeMap::new();
if let Some(overrides) = command_environment.as_deref() {
env.extend(
overrides
.iter()
.map(|(name, value)| (name.clone(), value.clone())),
);
}
// A turn that owns its child environment (library agents) keeps it: the
// module starts from the process snapshot, so the turn's own values for
// the functional variables are passed as approved overrides.
if tinyagents_harness_tools::exec::timeout::CommandEnvironment::is_active() {
for name in crate::sandbox::ops::SANDBOX_ENV_PASSTHROUGH {
if let Some(value) =
tinyagents_harness_tools::exec::timeout::CommandEnvironment::var_os(name)
{
let Ok(value) = value.into_string() else {
return (
false,
ToolResult::error("Shell environment contains a non-UTF-8 value."),
);
};
env.insert((*name).to_owned(), value);
}
}
}
// Keep command-valued repository Git settings from executing host
// programs when a shell command happens to invoke git.
for (key, value) in tinyagents_harness_tools::fs::filesystem::shell_git_env() {
let (Ok(key), Ok(value)) = (key.into_string(), value.into_string()) else {
return (
false,
ToolResult::error("Shell environment contains a non-UTF-8 value."),
);
};
env.insert(key, value);
}
super::shell_support::use_scratch_tmp(&mut env);
// No default deadline — only a caller-supplied `timeout_secs` bounds the
// run (issue #4023). TinyBox needs a finite budget, so an unbounded call
// gets the module's ceiling.
let explicit_timeout = self.explicit_timeout(requested_timeout);
let effective = explicit_timeout.unwrap_or_else(|| {
Duration::from_secs(tinyagents_harness_tools::exec::timeout::SANDBOX_UNBOUNDED_CAP_SECS)
});
tracing::debug!(
timeout_secs = effective.as_secs(),
requested_timeout_secs = ?requested_timeout,
unbounded = explicit_timeout.is_none(),
"[shell] starting command through TinyBox"
);
let config = match self.analysis_config.as_deref() {
Some(config) => config.clone(),
None => match ctx.load_config().await {
Ok(config) => config,
Err(e) => {
return (
true,
ToolResult::error(format!("Cannot read module configuration: {e}")),
);
}
},
};
let mut run = crate::sandbox::shell_exec::NativeShellRun::new(
command,
&action_dir,
&self.security.workspace_dir,
effective,
);
run.env = super::shell_support::with_unbuffered_python(env, command_environment.is_some());
run.python_utf8 = true;
run.hide_window = self.runtime.hide_window();
run.meter = meter;
(
true,
run_native(ctx, &config, run, come_back, context, audit).await,
)
}
/// Execute a command through the sandbox backend. Called when the
/// agent's `SandboxMode` is `Sandboxed`.
async fn run_sandboxed(
&self,
ctx: &DispatchCtx,
command: &str,
requested_timeout: Option<u64>,
come_back: YieldRequest,
action_dir: &Path,
context: Option<&dyn ToolRunContext>,
meter: Option<crate::sandbox::shell_progress::ShellOutputMeter>,
audit: &AuditOnce,
) -> (bool, ToolResult) {
let config = crate::config::RuntimeConfig::default();
let policy = crate::sandbox::resolve_sandbox_policy(
ctx,
tinyagents_definition::SandboxMode::Sandboxed,
action_dir,
&self.security.workspace_dir,
&config,
false,
);
let timeout = requested_timeout;
run_in_policy(
ctx, policy, command, timeout, come_back, action_dir, context, meter, audit,
)
.await
}
}
/// Emit a single `CommandExecution` audit event. A write failure is logged as
/// a structured warning but not propagated — audit must never block or fail a
/// tool call, yet a silently broken audit trail must not go unnoticed.
pub(super) fn record_audit(
audit: &AuditLogger,
command: &str,
approved: bool,
allowed: bool,
success: bool,
duration_ms: u64,
) {
if let Err(error) = audit.log_command_event(CommandExecutionLog {
channel: "tool:shell",
command,
risk_level: "unknown",
approved,
allowed,
success,
duration_ms,
}) {
tracing::warn!(
error = %error,
channel = "tool:shell",
"[shell] failed to persist command execution audit event"
);
}
}
#[cfg(test)]
#[path = "shell_tests.rs"]
mod tests;