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
//! One shell command run through TinyBox's `StartNativeShellExec`.
//!
//! The module selects the shell (cmd, or bash with pipefail), builds the safe
//! child environment, owns the per-call scratch directory and, when asked, the
//! native jail. This file only maps a host-authorized command onto that request
//! and drives the resource, process and output lifecycle to a result.
//!
//! Without the `modules` feature there is no execution surface and every run is
//! refused; the host never falls back to spawning a shell itself.
use std::{collections::BTreeMap, path::PathBuf, time::Duration};
use super::shell_live::LiveShell;
use super::types::SandboxExecResult;
use crate::config::Config;
#[cfg(feature = "modules")]
use crate::modules::tinybox::{self, contract};
#[cfg(test)]
#[path = "shell_exec_fixture.rs"]
pub(crate) mod fixture;
/// Everything one native shell run needs, owned so the worker can outlive the caller.
pub(crate) struct NativeShellRun {
/// Shell text, already authorized by the host.
pub(crate) command: String,
/// Directory the resource is rooted at.
pub(crate) workspace: PathBuf,
/// Working directory of the command.
pub(crate) cwd: PathBuf,
/// Approved overrides on the module's safe environment snapshot.
pub(crate) env: BTreeMap<String, String>,
/// Existing private directory the module creates per-call scratch under.
pub(crate) state_dir: PathBuf,
/// Runtime budget, clamped by the module to at most twenty-four hours.
pub(crate) timeout: Duration,
/// Keep the shell's own last-stage pipeline status instead of `pipefail`.
pub(crate) preserve_pipeline_status: bool,
/// Default the Python UTF-8 variables unless the parent environment sets them.
pub(crate) python_utf8: bool,
/// Windows only: start the child without a console window.
pub(crate) hide_window: bool,
/// Whether the resource keeps default network isolation; `false` is open.
pub(crate) isolate_network: bool,
/// Receives the command's output as it streams, for progress reporting.
pub(crate) meter: Option<super::shell_progress::ShellOutputMeter>,
/// Return with the process still running once it has run this long,
/// instead of waiting for it (the shell tool's yield point). `None`
/// waits for the command to end or its runtime budget to stop it.
pub(crate) yield_after: Option<Duration>,
/// Native confinement; `None` is ordinary local execution.
#[cfg(feature = "modules")]
pub(crate) jail: Option<contract::NativeJailConfig>,
}
impl NativeShellRun {
/// A host-authorized command run in `cwd` with default shell semantics.
pub(crate) fn new(
command: &str,
cwd: &std::path::Path,
state_dir: &std::path::Path,
timeout: Duration,
) -> Self {
Self {
command: command.to_owned(),
workspace: cwd.to_path_buf(),
cwd: cwd.to_path_buf(),
env: BTreeMap::new(),
state_dir: state_dir.to_path_buf(),
timeout,
preserve_pipeline_status: false,
python_utf8: false,
hide_window: false,
isolate_network: false,
meter: None,
yield_after: None,
#[cfg(feature = "modules")]
jail: None,
}
}
#[cfg(test)]
fn is_jailed(&self) -> bool {
#[cfg(feature = "modules")]
{
self.jail.is_some()
}
#[cfg(not(feature = "modules"))]
{
false
}
}
}
/// Switches the unjailed path between the module and the in-process test
/// fixture. Tests do not load a native TinyBox artifact; the released-artifact
/// test turns the fixture off to drive the real bus lifecycle.
#[cfg(test)]
pub(crate) static USE_FIXTURE: std::sync::atomic::AtomicBool =
std::sync::atomic::AtomicBool::new(true);
/// How a shell call that may come back before its command ends wants a
/// sandboxed command run.
#[derive(Clone, Copy, Debug, Default)]
pub(crate) struct ComeBack {
/// Return with the command still running once it has run this long. Only
/// the native backends (no sandbox, native jail) can.
pub(crate) yield_after: Option<Duration>,
/// For a backend that cannot leave a command running (Docker): the
/// caller's own come-back time, enforced as a deadline instead, as the
/// model's `timeout_secs` was before it yielded.
pub(crate) deadline_instead: Option<Duration>,
}
/// How a run came back: the command ended, or it was still running at its
/// yield point and is handed over to be followed.
pub(crate) enum ShellRunOutcome {
Finished(SandboxExecResult),
Running(LiveShell),
}
/// Run `run` through the module and collect its output, waiting for the
/// command to end (any yield point is ignored).
pub(crate) async fn run(
ctx: &crate::core::runtime::DispatchCtx,
config: &Config,
mut run: NativeShellRun,
) -> anyhow::Result<SandboxExecResult> {
run.yield_after = None;
match run_yielding(ctx, config, run).await? {
ShellRunOutcome::Finished(result) => Ok(result),
ShellRunOutcome::Running(_) => {
anyhow::bail!("a shell run without a yield point returned while running")
}
}
}
/// Run `run` through the module. With a yield point, a command still running
/// there comes back as [`ShellRunOutcome::Running`] and keeps running.
///
/// A worker owns cancellation and resource cleanup if the caller drops its wait.
pub(crate) async fn run_yielding(
ctx: &crate::core::runtime::DispatchCtx,
config: &Config,
mut run: NativeShellRun,
) -> anyhow::Result<ShellRunOutcome> {
#[cfg(test)]
if !run.is_jailed() && USE_FIXTURE.load(std::sync::atomic::Ordering::SeqCst) {
let _ = (ctx, config);
return fixture::run(run).await;
}
#[cfg(feature = "modules")]
{
let config = config.clone();
// Taken before the spawn: the worker task owns the meter.
let meter = run.meter.take();
tracing::debug!(
jailed = run.jail.is_some(),
timeout_ms = run.timeout.as_millis() as u64,
yield_after_ms = run.yield_after.map(|after| after.as_millis() as u64),
"[sandbox:shell] starting native shell through TinyBox"
);
// A cancelled turn drops this wait mid-command. The worker then cancels
// the command (`_caller` closes `abandoned`) and holds the turn's
// cleanup open until TinyBox has stopped it, so an awaited turn
// cancellation is acknowledged only after the command is gone.
let hold = tinyagents_harness_tools::exec::timeout::ProcessCleanup::hold();
let (_caller, abandoned) = tokio::sync::oneshot::channel::<std::convert::Infallible>();
ctx.spawn(async move {
let _hold = hold;
run_owned(&config, run, abandoned, meter).await
})
.await
.map_err(|_| anyhow::anyhow!("TinyBox shell worker did not finish"))?
}
#[cfg(not(feature = "modules"))]
{
let _ = (ctx, config, run);
anyhow::bail!("TinyBox module support is disabled; command execution is unavailable")
}
}
#[cfg(feature = "modules")]
async fn run_owned(
config: &Config,
run: NativeShellRun,
abandoned: tokio::sync::oneshot::Receiver<std::convert::Infallible>,
meter: Option<super::shell_progress::ShellOutputMeter>,
) -> anyhow::Result<ShellRunOutcome> {
let resource = tinybox::reserve(config, contract::ReserveRequest::Resource)
.await
.map_err(|_| anyhow::anyhow!("TinyBox could not reserve a command resource"))?;
let timeout = run.timeout;
// A yield point only counts when it comes before the command's own
// deadline; otherwise the run ends the usual way.
let yield_at = run
.yield_after
.filter(|after| *after < timeout)
.map(|after| tokio::time::Instant::now() + after);
let result = async {
tinybox::create(
config,
contract::CreateRequest {
resource: resource.clone(),
backend: "passthrough".to_owned(),
host: contract::HostConfig::Local,
workspace: contract::Workspace::Directory(path_string(
&run.workspace,
"command workspace",
)?),
network: if run.isolate_network {
contract::NetworkPolicy::default()
} else {
contract::NetworkPolicy::Open
},
resources: contract::ResourceLimits::default(),
ports: Vec::new(),
env: BTreeMap::new(),
},
)
.await
.map_err(|error| {
tracing::warn!(
error = ?error,
"[sandbox:shell] TinyBox refused to create a command resource"
);
anyhow::anyhow!("TinyBox could not create a command resource")
})?;
let process = tinybox::reserve(config, contract::ReserveRequest::Process(resource.clone()))
.await
.map_err(|_| anyhow::anyhow!("TinyBox could not reserve a command process"))?;
let request = shell_exec_request(process, &resource, run)?;
let process = tinybox::start_native_shell_exec(config, request)
.await
.map_err(|_| anyhow::anyhow!("TinyBox could not start the command process"))?;
collect_process(config, process, timeout, yield_at, abandoned, meter).await
}
.await;
// Still running at its yield point: the process and its resource go to
// the caller, who releases them once it has stopped.
let result = match result {
Ok(Collected::Running {
process,
cursor,
stdout,
stderr,
}) => {
tracing::debug!("[sandbox:shell] command still running at its yield point");
return Ok(ShellRunOutcome::Running(LiveShell {
stdout: String::from_utf8_lossy(&stdout).into_owned(),
stderr: String::from_utf8_lossy(&stderr).into_owned(),
handle: super::shell_live::LiveHandle::TinyBox(
super::shell_live::TinyBoxLive::new(config.clone(), resource, process, cursor),
),
}));
}
Ok(Collected::Done(output)) => Ok(ShellRunOutcome::Finished(output)),
Err(error) => Err(error),
};
let close = tinybox::close(config, resource).await;
match (result, close) {
(Ok(output), Ok(())) => Ok(output),
(Err(error), Ok(())) => Err(error),
(Ok(_), Err(_)) => anyhow::bail!("TinyBox did not acknowledge command cleanup"),
(Err(error), Err(_)) => Err(error),
}
}
/// Map a host-authorized command onto TinyBox's `StartNativeShellExec` request.
///
/// The host supplies only the command, working directory, approved environment
/// overrides and policy. Shell selection, the child environment and scratch
/// belong to the module.
#[cfg(feature = "modules")]
pub(crate) fn shell_exec_request(
process: contract::ResourceId,
resource: &contract::ResourceId,
run: NativeShellRun,
) -> anyhow::Result<contract::ShellExecRequest> {
Ok(contract::ShellExecRequest {
process,
resource: resource.clone(),
shell: contract::SelectShellRequest {
command: run.command,
preserve_pipeline_status: run.preserve_pipeline_status,
runtime_path: None,
python_utf8: run.python_utf8,
},
cwd: Some(path_string(&run.cwd, "command working directory")?),
extra_env: run.env,
state_dir: path_string(&run.state_dir, "command state directory")?,
timeout_ms: u64::try_from(run.timeout.as_millis())
.unwrap_or(u64::MAX)
.clamp(1, 86_400_000),
stdin: None,
jail: run.jail,
hide_window: run.hide_window,
})
}
/// What [`collect_process`] read: the whole run, or the run so far when it was
/// still going at its yield point.
#[cfg(feature = "modules")]
enum Collected {
Done(SandboxExecResult),
Running {
process: contract::ProcessRef,
cursor: u64,
stdout: Vec<u8>,
stderr: Vec<u8>,
},
}
#[cfg(feature = "modules")]
async fn collect_process(
config: &Config,
process: contract::ProcessRef,
timeout: Duration,
yield_at: Option<tokio::time::Instant>,
mut abandoned: tokio::sync::oneshot::Receiver<std::convert::Infallible>,
meter: Option<super::shell_progress::ShellOutputMeter>,
) -> anyhow::Result<Collected> {
use contract::{ExecutionState, OutputStream};
use tokio::sync::oneshot::error::TryRecvError;
let deadline = tokio::time::Instant::now() + timeout;
let mut cursor = 0;
let mut stdout = Vec::new();
let mut stderr = Vec::new();
let mut requested_cancel = false;
let timed_out = loop {
let caller_gone = matches!(abandoned.try_recv(), Err(TryRecvError::Closed));
if !requested_cancel && (caller_gone || tokio::time::Instant::now() >= deadline) {
if caller_gone {
tracing::debug!("[sandbox:shell] caller dropped its wait; cancelling the command");
}
tinybox::cancel(config, process.clone())
.await
.map_err(|_| {
anyhow::anyhow!("TinyBox could not acknowledge process cancellation")
})?;
requested_cancel = true;
}
let batch = tinybox::read_output(config, process.clone(), cursor)
.await
.map_err(|_| anyhow::anyhow!("TinyBox could not read command output"))?;
if !batch.chunks.is_empty() && batch.next_sequence <= cursor {
anyhow::bail!("TinyBox returned an invalid output cursor");
}
let has_chunks = !batch.chunks.is_empty();
let state = batch.state;
for chunk in batch.chunks {
if let Some(meter) = &meter {
meter.record(&chunk.bytes);
}
match chunk.stream {
OutputStream::Stdout => stdout.extend_from_slice(&chunk.bytes),
OutputStream::Stderr => stderr.extend_from_slice(&chunk.bytes),
}
}
cursor = batch.next_sequence;
match state {
ExecutionState::Running => {
if !requested_cancel && yield_at.is_some_and(|at| tokio::time::Instant::now() >= at)
{
return Ok(Collected::Running {
process,
cursor,
stdout,
stderr,
});
}
tokio::time::sleep(Duration::from_millis(20)).await
}
ExecutionState::Exited { .. } if has_chunks => continue,
ExecutionState::Exited { exit_code } => {
tinybox::release_output(config, process)
.await
.map_err(|_| anyhow::anyhow!("TinyBox could not release command output"))?;
return Ok(Collected::Done(SandboxExecResult {
exit_code,
stdout: String::from_utf8_lossy(&stdout).into_owned(),
stderr: String::from_utf8_lossy(&stderr).into_owned(),
timed_out: false,
}));
}
ExecutionState::Cancelled if has_chunks => continue,
ExecutionState::Cancelled => break requested_cancel,
ExecutionState::Failed { .. } if has_chunks => continue,
ExecutionState::Failed { code } => {
tracing::debug!(?code, "[sandbox:shell] TinyBox reported a failed execution");
break failure_timed_out(code)?;
}
}
};
tinybox::release_output(config, process)
.await
.map_err(|_| anyhow::anyhow!("TinyBox could not release command output"))?;
// What the command printed before it was stopped, both streams: a build
// or test killed at its deadline has usually written its progress and
// first errors by then. `timed_out` says why it stopped; the shell tool
// writes the timeout line.
Ok(Collected::Done(SandboxExecResult {
exit_code: -1,
stdout: String::from_utf8_lossy(&stdout).into_owned(),
stderr: String::from_utf8_lossy(&stderr).into_owned(),
timed_out,
}))
}
/// What a terminal TinyBox failure means for the command. The module enforces
/// the same runtime budget the host waits for, so a command that runs to its
/// limit usually ends as `TimedOut` before the host's own cancel lands: that is
/// the command's timeout, reported like one (`Ok(true)`). Anything else is a
/// real sandbox failure, named by its code.
#[cfg(feature = "modules")]
pub(super) fn failure_timed_out(code: contract::ExecutionFailure) -> anyhow::Result<bool> {
use contract::ExecutionFailure;
match code {
ExecutionFailure::TimedOut => Ok(true),
ExecutionFailure::CleanupFailed => {
anyhow::bail!("TinyBox retained native process cleanup for retry")
}
ExecutionFailure::OutputLimit => anyhow::bail!(
"TinyBox stopped the command: its output exceeded the execution output limit"
),
ExecutionFailure::StartFailed => {
anyhow::bail!("TinyBox native shell execution failed: the command could not start")
}
other => anyhow::bail!("TinyBox native shell execution failed ({other:?})"),
}
}
#[cfg(feature = "modules")]
pub(crate) fn path_string(path: &std::path::Path, label: &str) -> anyhow::Result<String> {
path.to_str()
.map(str::to_owned)
.ok_or_else(|| anyhow::anyhow!("{label} path is not UTF-8"))
}
/// Run a host-authorized command with the host's own network and no jail. Used
/// by cron and by the unsandboxed backend, which keep host execution semantics.
///
/// `preserve_pipeline_status` keeps a pipeline's default exit status for
/// callers whose retry or settlement behavior depends on it (cron).
pub(crate) async fn run_host(
ctx: &crate::core::runtime::DispatchCtx,
config: &Config,
command: &str,
cwd: &std::path::Path,
state_dir: &std::path::Path,
env: BTreeMap<String, String>,
timeout: Duration,
preserve_pipeline_status: bool,
meter: Option<super::shell_progress::ShellOutputMeter>,
) -> anyhow::Result<SandboxExecResult> {
let mut shell = NativeShellRun::new(command, cwd, state_dir, timeout);
shell.meter = meter;
shell.env = env;
shell.preserve_pipeline_status = preserve_pipeline_status;
run(ctx, config, shell).await
}
#[cfg(test)]
#[path = "shell_exec_tests.rs"]
mod tests;