//! `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>, } 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, ) -> 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 { 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), ) -> 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 { 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. fn script(marker: &std::path::Path) -> String { format!("(for _ in $(seq 1 40); do touch {}; sleep 0.25; done) & wait", marker.display()) } /// Whether anything is still touching `marker` after it is removed. async fn survivor_still_running(marker: &std::path::Path) -> bool { let _ = std::fs::remove_file(marker); tokio::time::sleep(Duration::from_millis(1_200)).await; marker.exists() } #[tokio::test] async fn a_dropped_call_takes_the_whole_tree_with_it() { if !cfg!(unix) { return; // the script is a POSIX one } 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 !cfg!(unix) { 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" ); } }