zesdex/crates/zesdex-backend/src/tool/shell.rs

//! Bash-shell execution tool with safety filters and optional timeout.
//!
//! This module implements the `bash` tool, which runs a shell command via
//! `bash -c <command>`. It supports foreground and background execution,
//! configurable timeouts, and destructive-git-operation gating via
//! `shell_filter::git::check_git_destructive`.
use super::Tool;
use super::ToolCtx;
use anyhow::{anyhow, Result};
use serde_json::{json, Value};
use std::process::Command;
use std::time::Duration;
use tracing;

/// Tool that runs `bash -c <command>`, optionally in the background, with safety
/// filters applied before spawning.
pub struct Bash;

impl Tool for Bash {
    fn name(&self) -> &'static str {
        "bash"
    }

    fn description(&self) -> &'static str {
        "Execute a shell command via bash -c"
    }

    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "command": {
                    "type": "string",
                    "description": "Shell command to execute"
                },
                "description": {
                    "type": "string",
                    "description": "Human-readable description of what the command does"
                },
                "timeout": {
                    "type": "integer",
                    "description": "Timeout in milliseconds (default 120000, max 600000)"
                },
                "run_in_background": {
                    "type": "boolean",
                    "description": "Run the command in the background and return immediately with a job ID"
                }
            },
            "required": ["command"]
        })
    }

    /// Run a bash command (foreground or background) with a safety filter and a timeout.
    ///
    /// Flow: extract args → run `check_git_destructive` (bail if it rejects) → branch on
    ///       `run_in_background`: if true, hand off to the bg-bash subsystem and return the
    ///       job ID; else spawn `bash -c`, poll with `try_wait`, kill on timeout, format
    ///       combined stdout+stderr.
    ///
    /// Why: only destructive git operations are gated here — credential-file reads
    /// (`~/.ssh/id_rsa`, `.netrc`, etc.) are deliberately NOT blocked, since the agent
    /// often needs to read local config for legitimate debugging; the real leak vector
    /// (committing secrets to a remote) is handled by git hooks/user review, not this
    /// tool. `shell_filter::credentials::check_credential_read` exists but is
    /// intentionally not called from here — see its module doc comment. The safety
    /// filter runs unconditionally so background jobs are also gated; the timeout is
    /// enforced by polling the child rather than relying on a libc alarm so cleanup
    /// stays in Rust.
    ///
    /// Return: exit-code + elapsed-seconds summary line (plus captured output) for
    /// foreground runs, or the job ID for background runs.
    fn run(&self, _ctx: &ToolCtx, args: &Value) -> Result<String> {
        let cmd = crate::tool::arg_str(args, "command")?;
        let timeout_ms = args
            .get("timeout")
            .and_then(serde_json::Value::as_u64)
            .unwrap_or(120_000) // default: 2 minutes
            .min(600_000); // max: 10 minutes
        tracing::debug!(cmd_len = cmd.len(), timeout = timeout_ms, "Bash::run invoked");
        // Only gate destructive git operations; credential reads are allowed
        // locally since the AI needs access, and the real threat is committing
        // secrets to a public repo (handled by git pre-commit hooks / user).
        super::shell_filter::git::check_git_destructive(&cmd)
            .map_err(|e| anyhow!("blocked: {e}"))?;
        let run_in_background = args
            .get("run_in_background")
            .and_then(serde_json::Value::as_bool)
            .unwrap_or(false);
        if run_in_background {
            tracing::debug!("spawning background bash job");
            let job = crate::app::bgbash::job::spawn_bash_job(cmd);
            return Ok(format!("Background job: {}", job.id));
        }
        tracing::debug!("spawning foreground bash -c");
        let mut child = Command::new("bash")
            .arg("-c")
            .arg(&cmd)
            .stdout(std::process::Stdio::piped())
            .stderr(std::process::Stdio::piped())
            .spawn()
            .map_err(|e| anyhow!("failed to spawn bash: {e}"))?;
        let start = std::time::Instant::now(); // used for timeout check and elapsed reporting
        let timeout = Duration::from_millis(timeout_ms);
        loop {
            match child.try_wait() {
                Ok(Some(status)) => {
                    let elapsed = start.elapsed().as_secs_f64();
                    let output = child
                        .wait_with_output()
                        .map_err(|e| anyhow!("failed to collect output: {e}"))?;
                    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
                    let stderr = String::from_utf8_lossy(&output.stderr).to_string();
                    let combined = if stderr.is_empty() {
                        stdout
                    } else {
                        format!("{stdout}\n{stderr}")
                    };
                    let trimmed = combined.trim().to_string();
                    if status.success() {
                        tracing::debug!(elapsed_secs = elapsed, "bash command succeeded");
                        return Ok(if trimmed.is_empty() {
                            format!("Command completed in {elapsed:.2}s (exit code 0)")
                        } else {
                            format!("{trimmed}\n\nExit code: 0 ({elapsed:.2}s)")
                        });
                    }
                    tracing::debug!(elapsed_secs = elapsed, exit_code = status.code().unwrap_or(-1), "bash command finished with non-zero exit");
                    return Ok(format!(
                        "{}\n\nExit code: {} ({:.2}s)",
                        trimmed,
                        status.code().unwrap_or(-1),
                        elapsed
                    ));
                }
                Ok(None) => {
                    if start.elapsed() > timeout {
                        tracing::warn!(timeout_ms = timeout_ms, "bash command timed out, killing");
                        let _ = child.kill();
                        let _ = child.wait();
                        anyhow::bail!("command timed out after {timeout_ms}ms");
                    }
                    std::thread::sleep(Duration::from_millis(10)); // small sleep to avoid busy-wait
                }
                Err(e) => {
                    tracing::error!(error = %e, "bash command wait failed");
                    anyhow::bail!("failed to wait for command: {e}");
                }
            }
        }
    }
}