Files
luxe/crates/luxe-tools/src/bash.rs

502 lines
22 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! `bash` tool — execute shell commands with timeout and output truncation.
//!
//! Supports:
//! - Executing shell commands via tokio::process
//! - Timeout enforcement (kills child on timeout)
//! - Output truncation (keeps head+tail, notes truncation)
//! - Exit code reporting
//!
//! The call ends when the **command** does. A process it deliberately left running is not the
//! command, however long it holds the output pipe. Running, capturing and reaping are
//! `crate::process`'s, shared with `test`.
//!
//! A command that printed files — `cat`, `head`, `tail`, `nl`, `sed -n` — counts as reading them
//! for the read-before-edit guard; see `seen`.
pub(crate) mod seen;
use async_trait::async_trait;
use luxe_core::compression::{
compress, CommandInvocation, CommandOutput, CompressionConfig, ReducerRegistry, TestReducer,
};
use luxe_core::{ContentBlock, Tool, ToolContext, ToolResultData, ToolSchema};
use serde_json::json;
use std::time::Duration;
use tracing::{debug, warn};
/// Default timeout for bash commands (30 seconds).
const DEFAULT_TIMEOUT_SECS: u64 = 30;
/// Ceiling on the model-supplied `timeout`, in seconds (one hour).
///
/// The argument exists because a build or a suite legitimately needs longer than the default, and
/// the model is the one who knows which. It is clamped because it is also the one number a model can
/// set that removes its own safety net — `timeout: 99999999` is not a considered choice about a
/// build, and there is no repo task on the other side of an hour that a fresh call cannot resume.
const MAX_TIMEOUT_SECS: u64 = 3_600;
/// Final safety clamp on the model-facing body, guarding the pathological single huge line the
/// line-based compressor cannot shrink (a minified bundle, a one-line JSON response).
///
/// The compressor handles *volume* beautifully — 200,000 lines of `seq` come back as ~550
/// characters — but it works per line, so one 500 KB line passes straight through, and a 1 MB
/// ceiling is no guard at any real context window (roughly 250,000 tokens).
/// Clamping hard is safe precisely because oversized output is *also* teed to `.luxe/artifacts/`
/// with its path in the result: nothing is lost, only deferred. The same ceiling `read` keeps, so
/// one long line costs the same whichever tool printed it.
const MAX_OUTPUT_BYTES: usize = luxe_core::output_limit::RESULT_MAX_CHARS;
/// Resolves the compression config, honoring the `LUXE_COMPRESS=0` opt-out.
fn compression_config() -> CompressionConfig {
let disabled = std::env::var("LUXE_COMPRESS").map(|v| v == "0").unwrap_or(false);
CompressionConfig { enabled: !disabled, ..CompressionConfig::default() }
}
/// Command-specific reducers applied to bash output. The structured test reducer turns test-runner
/// noise into a pass/fail summary; unmatched commands take the generic pipeline.
fn reducer_registry() -> ReducerRegistry {
let mut registry = ReducerRegistry::new();
registry.register(Box::new(TestReducer));
registry
}
/// Head+tail byte clamp — the last-resort guard when compression can't shrink a huge single line.
///
/// Cut on char boundaries: a byte offset can land inside a multi-byte character, and slicing there
/// panicked on any long enough line of non-ASCII output.
fn clamp_bytes(text: &str, max: usize) -> String {
if text.len() <= max {
return text.to_string();
}
let head = &text[..crate::output_limit::floor_boundary(text, max / 2)];
let tail = &text[crate::output_limit::ceil_boundary(text, text.len() - max / 2)..];
format!("{head}\n-- clamped {} bytes --\n{tail}", text.len() - head.len() - tail.len())
}
/// JSON-schema for the bash tool arguments.
fn bash_schema() -> ToolSchema {
ToolSchema {
name: "bash".to_string(),
description: "Execute a shell command with a timeout, for what the other tools do not \
cover: builds, scripts, package managers, running the program.\n\
Do not use it for what a tool here does better, because the tool's output \
is bounded and structured, the person watching sees what you did, and edits \
are checked and formatted:\n\
- reading files (cat, head, tail, sed -n): `read`, which takes several \
paths in one call\n\
- listing and finding files (ls, find): `glob`; searching inside them \
(grep, rg): `grep`\n\
- changing files (heredocs, sed -i, echo >): `edit` and `write`\n\
- git and GitHub (git, gh): `git`, including issues and pull requests\n\
- running the tests: `test`\n\
Calls in one reply run in a single round trip, so several tool calls cost no \
more than one shell line doing the same.\n\
Each call gets a fresh shell already rooted at the project directory, so \
there is nothing to `cd` into first and a `cd` does not carry to the next \
call. Noisy output is deterministically compressed before it reaches you — \
ANSI/progress/duplicate lines are stripped and long logs are truncated while \
errors, warnings, failing tests, and file:line locations are always kept. \
When output is reduced, the untouched output is saved to .luxe/artifacts/ \
(each stream whole up to 8 MB, or its first and last 4 MB past that) and its path is \
included, so you can read it if you need the detail."
.to_string(),
parameters: json!({
"type": "object",
"properties": {
// First, so the model writes it before the command and the card is named by it
// from the start rather than renamed when the call lands
"description": {
"type": "string",
"description": "What the command does, in 5–10 plain words, for the person \
watching: \"Run the forms tests\", not the command's own text. \
Their card shows this in place of the command."
},
"command": {
"type": "string",
"description": "Shell command to execute, from the project directory"
},
"timeout": {
"type": "integer",
"description": "Timeout in seconds (optional, defaults to 30)"
}
},
"required": ["command"]
}),
}
}
/// The `bash` tool implementation.
pub struct BashTool {
/// Shared read tracker; a file a command printed is recorded as read
tracker: Option<std::sync::Arc<luxe_core::read_tracker::ReadTracker>>,
}
impl BashTool {
/// Create a new bash tool instance.
pub fn new() -> Self {
Self { tracker: None }
}
/// Attach the shared read tracker, so a `cat` of a file satisfies the edit guards.
pub fn with_tracker(
mut self,
tracker: std::sync::Arc<luxe_core::read_tracker::ReadTracker>,
) -> Self {
self.tracker = Some(tracker);
self
}
}
impl Default for BashTool {
fn default() -> Self {
Self::new()
}
}
/// Most surviving processes a timeout names before the rest become a count.
const MAX_SURVIVORS_LISTED: usize = 10;
/// Longest command line a timeout shows for one surviving process.
const SURVIVOR_COMMAND_CHARS: usize = 120;
/// What follows a timeout's output: the processes still running, and what to do next.
///
/// A suspended process changes the advice: it was never going to finish, so a longer `timeout`
/// would only wait longer. Commands start without a terminal, so a spinner or a prompt cannot cause
/// it; a `SIGSTOP` or a debugger still can.
fn timeout_advice(survivors: &[luxe_core::program::GroupMember]) -> String {
let mut out = String::new();
if !survivors.is_empty() {
out.push_str("\n\nStill running when it was stopped (pid, state, command):");
for member in survivors.iter().take(MAX_SURVIVORS_LISTED) {
let command: String = member.command.chars().take(SURVIVOR_COMMAND_CHARS).collect();
let cut =
if member.command.chars().count() > SURVIVOR_COMMAND_CHARS { "…" } else { "" };
out.push_str(&format!("\n {} {} {command}{cut}", member.pid, member.state));
}
if survivors.len() > MAX_SURVIVORS_LISTED {
out.push_str(&format!("\n … +{} more", survivors.len() - MAX_SURVIVORS_LISTED));
}
}
if survivors.iter().any(luxe_core::program::GroupMember::is_stopped) {
out.push_str(
"\n\nState T means suspended, not slow: something stopped it (a `SIGSTOP`, a job-control \
signal, a debugger) and it will not continue on its own. More time will not help; find \
what stops it, or ask the user to run it in their own terminal.",
);
} else {
out.push_str(&format!(
"\n\nFor a command that needs longer, pass `timeout` (up to {MAX_TIMEOUT_SECS} \
seconds); to leave one running, start it in the background with `&` and its output \
redirected to a file."
));
}
out
}
#[async_trait]
impl Tool for BashTool {
/// No engine-side deadline: this tool spawns its command as its own **process group** and kills
/// the whole tree itself, which the engine cannot do (dropping the future reaps the direct
/// child and orphans everything it started). It owns the bound because it owns the kill — the
/// `timeout` argument, defaulted and clamped in [`Self::run`], and `crate::process`'s tree
/// guard for every other way the call can end.
fn timeout(&self) -> Option<Duration> {
None
}
fn name(&self) -> &str {
"bash"
}
fn schema(&self) -> ToolSchema {
bash_schema()
}
async fn run(&self, args: serde_json::Value, cx: &ToolContext) -> ToolResultData {
let Some(command) = args.get("command").and_then(|v| v.as_str()) else {
return ToolResultData::error("Error: 'command' argument is required");
};
let timeout_secs = timeout_secs(&args);
debug!(command, timeout = timeout_secs, "executing bash command");
let timeout = Duration::from_secs(timeout_secs);
match crate::process::run_captured(command, &cx.cwd, timeout).await {
Ok(crate::process::Outcome::Finished(output)) => self.finish(command, cx, output),
Ok(crate::process::Outcome::TimedOut(stopped)) => {
warn!(command, timeout = timeout_secs, "command timed out");
timed_out(timeout_secs, &stopped)
}
Err(error) => {
warn!(command, %error, "failed to run command");
ToolResultData::error(format!("Error running command: {error}"))
}
}
}
}
/// The model's `timeout`, defaulted and clamped.
///
/// A negative or absent value takes the default; anything past the ceiling is clamped rather than
/// refused, since the intent ("this one is slow") is still worth honoring.
fn timeout_secs(args: &serde_json::Value) -> u64 {
args.get("timeout")
.and_then(|v| v.as_i64())
.and_then(|secs| u64::try_from(secs).ok())
.filter(|secs| *secs > 0)
.unwrap_or(DEFAULT_TIMEOUT_SECS)
.min(MAX_TIMEOUT_SECS)
}
/// A timeout's reply: what the command had printed, which is the evidence of where it got to, and
/// the way out. A bare "timed out" left the agent to guess both, and usually to run it again.
fn timed_out(timeout_secs: u64, stopped: &crate::process::TimedOut) -> ToolResultData {
let printed = match stopped.printed.is_empty() {
true => "It printed nothing before it was stopped.".to_string(),
false => format!("Output before it was stopped:\n{}", stopped.printed),
};
ToolResultData::error(format!(
"Command timed out after {timeout_secs} seconds and was stopped. {printed}{}",
timeout_advice(&stopped.survivors)
))
}
impl BashTool {
/// The reply for a command that ran to its end.
fn finish(
&self,
command: &str,
cx: &ToolContext,
output: crate::process::Captured,
) -> ToolResultData {
let crate::process::Captured { stdout, stderr, status, detached_writer } = output;
// A failed command may have printed half of what it was asked to, so only a clean exit counts
if let Some(tracker) = self.tracker.as_ref().filter(|_| status.success()) {
for path in seen::files_shown(command, &cx.cwd, &stdout) {
tracker.record(&cx.session_id, &path);
}
}
let exit = status.code();
if detached_writer {
debug!(command, "a process outlived the shell still holding its pipe");
}
let mut body = compressed_body(command, cx, (&stdout, &stderr, exit));
if detached_writer {
body.push_str(crate::process::DETACHED_WRITER_NOTE);
}
// A failure on a Windows box with no POSIX shell is usually about the *shell*, not the
// command. Said once, on failure only, so `cargo test` through `cmd` stays quiet.
if !crate::process::posix_shell() && !status.success() {
body.push_str(NO_POSIX_SHELL_NOTE);
}
// `grep` and `rg` exit 1 for "nothing matched", which is an answer rather than a failure,
// when the search ends the command and said nothing at all
let no_match = exit == Some(1)
&& stdout.trim().is_empty()
&& stderr.trim().is_empty()
&& ends_in_search(command);
let exit_note = if no_match {
" — the search matched nothing, which is what exit code 1 means for it"
} else {
""
};
ToolResultData {
content: vec![ContentBlock::Text(format!(
"{body}\n\nExit code: {}{exit_note}",
exit.unwrap_or(-1)
))],
is_error: !status.success() && !no_match,
}
}
}
/// The output as the model reads it: compressed, led by a test run's regressions, pointed at the
/// untouched copy whenever anything was dropped, and clamped last.
fn compressed_body(
command: &str,
cx: &ToolContext,
(stdout, stderr, exit): (&str, &str, Option<i32>),
) -> String {
// Noisy output keeps its signal — errors, warnings, failing tests, file:line, exit codes — and
// the test reducer turns `cargo test`/`pytest` output into a pass/fail summary.
let invocation = CommandInvocation::parse(command);
let captured =
CommandOutput { stdout: stdout.to_owned(), stderr: stderr.to_owned(), exit_code: exit };
let result = compress(&invocation, &captured, &compression_config(), &reducer_registry());
let mut body =
if result.output.is_empty() { "(no output)".to_string() } else { result.output.clone() };
if let Some(note) = test_delta(command, cx, &invocation, stdout, stderr) {
body = format!("{note}{body}");
}
// A body too long to send whole is a reduction too, so its untouched output is saved the same
// way, or the clamp below would drop text with no path back to it
if result.was_reduced() || body.len() > MAX_OUTPUT_BYTES {
// The schema promises the untouched output is recoverable whenever this reduces, so a tee
// that could not write has to say so rather than leave the reader looking for a path
match crate::process::tee_artifact(&cx.cwd, "cmd", command, (stdout, stderr, exit)) {
Some(path) => {
body.push_str(&format!("\n\nFull output: {}", luxe_core::paths::display(&path)))
}
None => body.push_str(
"\n\nThe full output could not be saved to .luxe/artifacts/ — re-run with a \
narrower command if you need the part that was dropped.",
),
}
if let Some(footer) = result.footer().filter(|_| result.was_reduced()) {
body.push('\n');
body.push_str(&footer);
}
}
clamp_bytes(&body, MAX_OUTPUT_BYTES)
}
/// A suite run through the shell gets the `test` tool's "what broke since last time" too. Keyed by
/// the whole command, so each subset a model runs is compared only with itself.
fn test_delta(
command: &str,
cx: &ToolContext,
invocation: &CommandInvocation,
stdout: &str,
stderr: &str,
) -> Option<String> {
if !luxe_core::compression::is_test_command(invocation) {
return None;
}
let summary = luxe_core::compression::parse_test_output(stdout, stderr)?;
let failing = summary.failures.iter().map(|f| f.name.clone()).collect();
crate::test_baseline::diff_and_record(
&cx.cwd,
command,
&failing,
summary.passed,
summary.failed,
false,
)
.render()
}
/// `cmd`'s complaint about a pipe or a quote reads like the command was wrong.
const NO_POSIX_SHELL_NOTE: &str = "\n\nNote: no POSIX shell was found, so this ran through \
cmd.exe, which does not understand `|`, `&&`, single quotes, `$VAR` or unix tool names. \
Install Git for Windows (its `bash` is picked up automatically) to run commands as written.";
/// Whether the last command `command` runs is a search whose exit 1 means "no match".
///
/// The last one, because that is whose status the shell reports: `npm test | grep x` exits as
/// `grep` did. Quotes are respected — a pattern like `"^ok|^not ok"` is full of pipes — and anything
/// unclear after the search, like a redirection's `2>&1`, makes this false, which keeps the call
/// reported exactly as it was.
fn ends_in_search(command: &str) -> bool {
let bytes = command.as_bytes();
let (mut single, mut double, mut start) = (false, false, 0);
let mut index = 0;
while index < bytes.len() {
match bytes[index] {
b'\'' if !double => single = !single,
b'"' if !single => double = !double,
b'\\' if !single => index += 1,
b'|' | b';' | b'&' | b'\n' if !single && !double => start = index + 1,
_ => {}
}
index += 1;
}
let Some(words) = shlex::split(&command[start..]) else { return false };
let program = words
.iter()
.find(|word| !word.contains('='))
.map(|word| word.rsplit('/').next().unwrap_or(word));
matches!(program, Some("grep" | "egrep" | "fgrep" | "rg"))
}
#[cfg(test)]
mod tests;
/// A cancelled command has to stop, and so does everything it started.
///
/// The engine cancels a tool by dropping its future, and `kill_on_drop` reaps only the shell — so
/// this is the one property no amount of testing the timeout path establishes. Both endings are
/// here, because they are the same obligation reached two different ways.
#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tree_teardown {
use super::*;
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::{mpsc, watch};
fn context(cwd: &std::path::Path) -> ToolContext {
let (event_tx, _event_rx) = mpsc::channel(64);
let (_cancel_tx, cancel_rx) = watch::channel(false);
ToolContext {
cwd: cwd.to_path_buf(),
session_id: "tree-teardown".to_string(),
cancelled: Arc::new(cancel_rx),
event_tx,
hook_ctx: None,
question_broker: None,
}
}
/// A shell that backgrounds a grandchild and waits on it. Killing the shell alone leaves the
/// grandchild touching `marker` — which is how a survivor makes itself known. Forward slashes,
/// which Git Bash takes on Windows, where a backslash would be an escape.
fn script(marker: &std::path::Path) -> String {
let marker = marker.display().to_string().replace('\\', "/");
format!("(for _ in $(seq 1 40); do touch '{marker}'; sleep 0.25; done) & wait")
}
/// Whether anything is still touching `marker`, the loop, once a touch that was already under
/// way has had its moment.
///
/// The kill reaches the whole group at once, but a `touch` forked as it lands can finish one
/// write after it, and on macOS's slower teardown that write can follow the first clear. One
/// straggling write is not a survivor; a loop still running touches again within a quarter
/// second of the second clear.
async fn survivor_still_running(marker: &std::path::Path) -> bool {
let _ = std::fs::remove_file(marker);
tokio::time::sleep(Duration::from_millis(300)).await;
let _ = std::fs::remove_file(marker);
tokio::time::sleep(Duration::from_millis(1_000)).await;
marker.exists()
}
#[tokio::test]
async fn a_dropped_call_takes_the_whole_tree_with_it() {
// The script is a POSIX one: Git Bash runs it on Windows, where the tree is a job's
if !luxe_core::program::has_posix_shell() {
return;
}
let dir = tempfile::tempdir().expect("tempdir");
let marker = dir.path().join("alive");
let cx = context(dir.path());
{
let tool = BashTool::new();
let run = tool.run(serde_json::json!({"command": script(&marker)}), &cx);
tokio::pin!(run);
// Poll far enough to spawn the tree, then drop it — exactly what a cancel does.
let _ = tokio::time::timeout(Duration::from_millis(900), &mut run).await;
}
assert!(
!survivor_still_running(&marker).await,
"a cancelled command left its grandchild running"
);
}
#[tokio::test]
async fn a_timed_out_call_takes_the_whole_tree_with_it() {
if !luxe_core::program::has_posix_shell() {
return;
}
let dir = tempfile::tempdir().expect("tempdir");
let marker = dir.path().join("alive");
let cx = context(dir.path());
let result = BashTool::new()
.run(serde_json::json!({"command": script(&marker), "timeout": 1}), &cx)
.await;
assert!(result.is_error, "a command that outlives its timeout is an error");
assert!(
!survivor_still_running(&marker).await,
"a timed-out command left its grandchild running"
);
}
}