Skip to content

armgit / agtx

Public Imported from GitHub
0

πŸ„πŸΌβ€β™‚οΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.

24.6 KB
Raw Blame
//! Traits for tmux operations to enable testing with mocks.

use anyhow::Result;

#[cfg(feature = "test-mocks")]
use mockall::automock;

/// Operations for tmux window management
#[cfg_attr(feature = "test-mocks", automock)]
pub trait TmuxOperations: Send + Sync {
    /// Create a new tmux window. `keep_shell_on_exit=true` drops to a shell
    /// after `command` exits (task panes); `false` lets tmux close the window
    /// (orchestrator, where a leftover shell looks like a zombie).
    /// Create a window. `env` is set on the **window** (tmux `-e`), so anything
    /// started in it later β€” a resumed agent, a switched agent β€” inherits it,
    /// which a per-command `env VAR=x` prefix would not.
    fn create_window(
        &self,
        session: &str,
        window_name: &str,
        working_dir: &str,
        command: Option<String>,
        keep_shell_on_exit: bool,
        env: &[(String, String)],
    ) -> Result<()>;

    /// Kill a tmux window
    fn kill_window(&self, target: &str) -> Result<()>;

    /// Check if a window exists
    fn window_exists(&self, target: &str) -> Result<bool>;

    /// This window's tmux pane id (`%7`), for matching `%output` notifications.
    fn pane_id(&self, target: &str) -> Option<String>;

    /// The OS process id of the window's pane β€” the shell tmux started.
    ///
    /// The root for finding what a task spawned. Distinct from
    /// [`pane_id`](Self::pane_id), which is tmux's own `%7` handle and means
    /// nothing to the operating system.
    fn pane_pid(&self, target: &str) -> Option<u32>;

    /// Every window on the server as `session:window`.
    ///
    /// One call answers [`window_exists`](Self::window_exists) for every task on
    /// the board. The per-task form is still the right shape for one-off checks;
    /// this exists because the status refresh asks about every task at once, on a
    /// timer, and N processes for one listing is the difference that shows up in
    /// tmux's CPU as a board grows.
    fn list_window_targets(&self) -> Result<Vec<String>>;

    /// Send keys to a window (with Enter at the end).
    ///
    /// Like [`send_key`](Self::send_key), this goes through
    /// tmux's **key-name** lookup β€” see the note there.
    fn send_keys(&self, target: &str, keys: &str) -> Result<()>;

    /// Send a **key name** to a window, without a trailing Enter.
    ///
    /// This deliberately does *not* pass `-l`, so tmux resolves the argument as a
    /// key when it matches a key name: `"Enter"`, `"C-c"`, `"C-d"`, `"1"`.
    /// Callers answering a dialog or pressing a control key want exactly that.
    ///
    /// Never use it for text, because the same lookup applies: verified against
    /// tmux 3.5a, `"Space"` arrives as `0x20`, `"Escape"` as `ESC`, and `"Up"` as
    /// `\033[A`. Use [`send_text`](Self::send_text) β€” or, for a whole message,
    /// [`paste_text`](Self::paste_text) β€” instead.
    fn send_key(&self, target: &str, keys: &str) -> Result<()>;

    /// Send literal text to a window (`send-keys -l`), without a trailing Enter.
    ///
    /// Unlike [`send_key`](Self::send_key) the argument is never
    /// interpreted as a key name, so text that happens to spell one survives
    /// intact. Use this for anything user- or task-derived.
    fn send_text(&self, target: &str, text: &str) -> Result<()>;

    /// Paste a block of text into a pane using tmux load-buffer + paste-buffer.
    /// This sends proper bracketed paste sequences to the target pane.
    fn paste_text(&self, target: &str, text: &str) -> Result<()>;

    /// Capture pane content
    fn capture_pane(&self, target: &str) -> Result<String>;

    /// Capture pane content with history (returns raw bytes for ANSI parsing)
    fn capture_pane_with_history(&self, target: &str, history_lines: i32) -> Vec<u8>;

    /// Cursor position, pane height, and how much scrollback tmux is holding.
    ///
    /// One `display -p` for all four: the popup refresh runs this often,
    /// so a second process to ask about scrollback would cost more than the
    /// answer is worth.
    fn pane_metrics(&self, target: &str) -> Option<PaneMetrics>;

    /// Resize a tmux window
    fn resize_window(&self, target: &str, width: u16, height: u16) -> Result<()>;

    /// Get the current command running in a pane (e.g. "claude", "bash", "zsh")
    fn pane_current_command(&self, target: &str) -> Option<String>;

    /// Check if a session exists
    fn has_session(&self, session: &str) -> bool;

    /// Create a new detached session
    fn create_session(&self, session: &str, working_dir: &str) -> Result<()>;
}

/// What tmux reports about a pane, in one query.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PaneMetrics {
    pub cursor_x: usize,
    pub cursor_y: usize,
    pub pane_height: usize,
    /// Lines tmux is holding *above* the visible screen.
    ///
    /// Zero for a pane in the **alternate screen**, which is where full-screen
    /// agent UIs live: the alternate screen accumulates no scrollback, so the
    /// session's history belongs to the agent and tmux cannot see any of it.
    /// Measured on Claude Code 2.1.251, which takes the alternate screen shortly
    /// after startup and never gives it back β€” `capture-pane -S -500` then
    /// returns exactly the visible rows, and there is nothing for agtx to
    /// scroll through.
    pub history_size: usize,
}

/// The `display -p` format that yields a [`PaneMetrics`], in field order.
///
/// One constant because two paths send it β€” the subprocess client and the
/// control connection β€” and a field added to one spelling but not the other
/// would silently misparse into the wrong struct fields rather than fail.
///
/// Verified against tmux 3.5a: `-t` is honoured for the expansion, so this
/// reports the *target* pane and not the attached client's active one, which is
/// what makes it usable from a control client attached elsewhere.
pub const PANE_METRICS_FORMAT: &str = "#{cursor_x} #{cursor_y} #{pane_height} #{history_size}";

/// Parse what [`PANE_METRICS_FORMAT`] produces. Anything unexpected is `None`:
/// a half-parsed pane geometry would mistrim the popup's content.
pub fn parse_pane_metrics(line: &str) -> Option<PaneMetrics> {
    let parts: Vec<&str> = line.split_whitespace().collect();
    if parts.len() != 4 {
        return None;
    }
    Some(PaneMetrics {
        cursor_x: parts[0].parse().ok()?,
        cursor_y: parts[1].parse().ok()?,
        pane_height: parts[2].parse().ok()?,
        history_size: parts[3].parse().ok()?,
    })
}

/// What a capture should ask tmux for.
///
/// The popup and the status refresh want different things from the same command,
/// and the difference is not cosmetic: `-e` embeds SGR escapes, which is what
/// the popup renders from and what a *text scan* β€” dialog matching, content
/// hashing β€” must not have to parse around.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CaptureSpec {
    /// Scrollback lines (`-S -<n>`). Zero captures only the visible pane.
    pub history: i32,
    /// Include SGR escapes (`-e`).
    pub escapes: bool,
    /// Also fetch cursor and geometry. A second tmux command, so only the popup
    /// β€” which needs the cursor row to trim β€” pays for it.
    pub metrics: bool,
}

impl CaptureSpec {
    /// What the popup renders: scrollback, colour, and the geometry to trim by.
    pub fn popup(history: i32) -> Self {
        Self {
            history,
            escapes: true,
            metrics: true,
        }
    }

    /// What a text scan needs: the visible pane, no escapes, no geometry.
    /// Matches `TmuxOperations::capture_pane` byte for byte.
    pub fn text() -> Self {
        Self {
            history: 0,
            escapes: false,
            metrics: false,
        }
    }
}

/// One pane capture: its content and the geometry needed to trim it.
///
/// The two are fetched together because they are only consistent together β€” the
/// cursor row is an index *into* the content, so pairing a capture with metrics
/// taken a frame later can trim off a line the user just typed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PaneSnapshot {
    pub content: Vec<u8>,
    pub metrics: Option<PaneMetrics>,
}

impl PaneMetrics {
    /// What [`trim_content_to_cursor`](crate::tui::shell_popup::trim_content_to_cursor) needs.
    ///
    /// It returns the cursor's line index along with the trimmed content: the
    /// row cannot be recovered from the metrics afterwards, because trimming
    /// changes how many lines lie between the cursor and the end.
    pub fn trim_bounds(&self) -> (usize, usize) {
        (self.cursor_y, self.pane_height)
    }
}

/// Wrap `text` as one POSIX single-quoted shell word.
///
/// [`create_window`](TmuxOperations::create_window) nests the agent's launch
/// command inside `sh -c …`, and that command has **already** been quoted by
/// [`compose_command`](crate::agent::spec::compose_command) β€” which single-quotes
/// the task prompt. Interpolating it into another pair of single quotes ends the
/// outer word at the first inner quote, and the shell then parses the prompt as
/// code: verified against tmux 3.5a, `claude --dangerously-skip-permissions
/// '/agtx:plan <id>\n\n<task>'` reached the process as argv
/// `["--dangerously-skip-permissions", "/agtx:plan"]` β€” the id and the whole task
/// silently gone β€” and codex's `$agtx-plan` fared worse still, with `$agtx`
/// expanded to nothing and only `-plan` surviving.
///
/// So the inner command is quoted here rather than interpolated raw, closing the
/// quote and reopening it around each literal `'` in the usual POSIX way.
fn single_quote(text: &str) -> String {
    format!("'{}'", text.replace('\'', "'\"'\"'"))
}

/// The shell command tmux is asked to run for an agent pane.
///
/// `keep_shell_on_exit` drops to a login shell afterwards, so a task pane
/// survives the agent quitting and can be inspected.
fn wrap_launch_command(shell_cmd: &str, keep_shell_on_exit: bool) -> String {
    let inner = single_quote(shell_cmd);
    if keep_shell_on_exit {
        format!("env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT sh -c {inner}; exec $SHELL")
    } else {
        format!("env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT sh -c {inner}")
    }
}

/// Real implementation using actual tmux commands
pub struct RealTmuxOps;

impl TmuxOperations for RealTmuxOps {
    fn create_window(
        &self,
        session: &str,
        window_name: &str,
        working_dir: &str,
        command: Option<String>,
        keep_shell_on_exit: bool,
        env: &[(String, String)],
    ) -> Result<()> {
        let mut cmd = std::process::Command::new("tmux");
        let target = format!("{}:", session);
        cmd.args(["-L", super::AGENT_SERVER])
            .args(["new-window", "-d", "-t", &target, "-n", window_name])
            .args(["-c", working_dir]);

        // tmux 3.0+; sets the variable on the window so every process started in
        // it inherits it, including agents launched later by resume or switch.
        for (key, value) in env {
            cmd.args(["-e", &format!("{}={}", key, value)]);
        }

        if let Some(ref shell_cmd) = command {
            // Unset Claude Code's nesting-detection env vars so that agents
            // launched in task panes are not blocked by the "launched inside
            // another Claude Code session" check.
            let wrapped = wrap_launch_command(shell_cmd, keep_shell_on_exit);
            cmd.args(["sh", "-c", &wrapped]);
        }

        let output = cmd.output()?;

        if !output.status.success() {
            let stderr = String::from_utf8_lossy(&output.stderr);
            let stdout = String::from_utf8_lossy(&output.stdout);
            let mut details = String::new();
            if !stderr.trim().is_empty() {
                details.push_str(stderr.trim());
            }
            if !stdout.trim().is_empty() {
                if !details.is_empty() {
                    details.push_str(" | ");
                }
                details.push_str(stdout.trim());
            }
            if details.is_empty() {
                anyhow::bail!("Failed to create tmux window");
            } else {
                anyhow::bail!("Failed to create tmux window: {}", details);
            }
        }
        Ok(())
    }

    fn kill_window(&self, target: &str) -> Result<()> {
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["kill-window", "-t", target])
            .output()?;
        Ok(())
    }

    fn pane_id(&self, target: &str) -> Option<String> {
        let out = std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["display", "-p", "-t", target, "#{pane_id}"])
            .output()
            .ok()?;
        if !out.status.success() {
            return None;
        }
        let id = String::from_utf8_lossy(&out.stdout).trim().to_string();
        (!id.is_empty()).then_some(id)
    }

    fn pane_pid(&self, target: &str) -> Option<u32> {
        let out = std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["display", "-p", "-t", target, "#{pane_pid}"])
            .output()
            .ok()?;
        if !out.status.success() {
            return None;
        }
        String::from_utf8_lossy(&out.stdout).trim().parse().ok()
    }

    fn list_window_targets(&self) -> Result<Vec<String>> {
        let output = std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["list-windows", "-a", "-F", "#{session_name}:#{window_name}"])
            .output()?;
        if !output.status.success() {
            // No server at all is "no windows", not an error: it is the normal
            // state before the first task is started.
            return Ok(Vec::new());
        }
        Ok(String::from_utf8_lossy(&output.stdout)
            .lines()
            .map(str::to_string)
            .collect())
    }

    fn window_exists(&self, target: &str) -> Result<bool> {
        let output = std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["list-windows", "-t", target])
            .output()?;
        Ok(output.status.success())
    }

    fn send_keys(&self, target: &str, keys: &str) -> Result<()> {
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["send-keys", "-t", target, keys])
            .output()?;
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["send-keys", "-t", target, "Enter"])
            .output()?;
        Ok(())
    }

    fn send_key(&self, target: &str, keys: &str) -> Result<()> {
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["send-keys", "-t", target, keys])
            .output()?;
        Ok(())
    }

    fn send_text(&self, target: &str, text: &str) -> Result<()> {
        // `-l` disables key-name lookup; `--` stops tmux parsing text that begins
        // with a dash as flags.
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["send-keys", "-t", target, "-l", "--", text])
            .output()?;
        Ok(())
    }

    fn paste_text(&self, target: &str, text: &str) -> Result<()> {
        use std::io::Write;
        let mut child = std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["load-buffer", "-"])
            .stdin(std::process::Stdio::piped())
            .spawn()?;
        if let Some(mut stdin) = child.stdin.take() {
            stdin.write_all(text.as_bytes())?;
        }
        child.wait()?;
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["paste-buffer", "-p", "-t", target])
            .output()?;
        Ok(())
    }

    fn capture_pane(&self, target: &str) -> Result<String> {
        let output = std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["capture-pane", "-t", target, "-p"])
            .output()?;
        Ok(String::from_utf8_lossy(&output.stdout).to_string())
    }

    fn capture_pane_with_history(&self, target: &str, history_lines: i32) -> Vec<u8> {
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            // Keep wrapped rows separate: tmux reports cursor_y in physical
            // pane rows, so joining wrapped rows would misalign the cursor.
            .args(["capture-pane", "-t", target, "-p", "-e"])
            .args(["-S", &format!("-{}", history_lines)])
            .output()
            .map(|o| o.stdout)
            .unwrap_or_default()
    }

    fn pane_metrics(&self, target: &str) -> Option<PaneMetrics> {
        let output = std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["display", "-p", "-t", target, PANE_METRICS_FORMAT])
            .output()
            .ok()?;

        if !output.status.success() {
            return None;
        }
        parse_pane_metrics(&String::from_utf8_lossy(&output.stdout))
    }

    fn resize_window(&self, target: &str, width: u16, height: u16) -> Result<()> {
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["resize-window", "-t", target])
            .args(["-x", &width.to_string()])
            .args(["-y", &height.to_string()])
            .output()?;
        Ok(())
    }

    fn pane_current_command(&self, target: &str) -> Option<String> {
        let output = std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["display", "-p", "-t", target, "#{pane_current_command}"])
            .output()
            .ok()?;
        if output.status.success() {
            let cmd = String::from_utf8_lossy(&output.stdout).trim().to_string();
            if !cmd.is_empty() {
                Some(cmd)
            } else {
                None
            }
        } else {
            None
        }
    }

    fn has_session(&self, session: &str) -> bool {
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["has-session", "-t", session])
            .output()
            .map(|o| o.status.success())
            .unwrap_or(false)
    }

    fn create_session(&self, session: &str, working_dir: &str) -> Result<()> {
        std::process::Command::new("tmux")
            .args(["-L", super::AGENT_SERVER])
            .args(["new-session", "-d", "-s", session])
            .args(["-c", working_dir])
            .output()?;
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Run the wrapper through a real `sh`, exactly as tmux does, and report the
    /// argv the launched process actually received.
    fn argv_delivered_by(shell_cmd: &str) -> Vec<String> {
        let wrapped = wrap_launch_command(shell_cmd, false);
        let out = std::process::Command::new("sh")
            .arg("-c")
            .arg(&wrapped)
            .output()
            .expect("sh should run");
        String::from_utf8_lossy(&out.stdout)
            .split('\u{1}')
            .filter(|s| !s.is_empty())
            .map(|s| s.to_string())
            .collect()
    }

    /// `printf` with a NUL-free separator, so an argument containing newlines
    /// stays one argument in the parsed output.
    fn dump_argv_command(args: &[&str]) -> String {
        let quoted: Vec<String> = args.iter().map(|a| single_quote(a)).collect();
        format!("printf '%s\u{1}' {}", quoted.join(" "))
    }

    #[test]
    fn a_launch_prompt_reaches_the_process_intact() {
        // The shape `compose_command` produces for the launch lane: flags, then
        // the whole opening message as one single-quoted word.
        let prompt = "/agtx:plan 57d57fe8-5990\n\nSMOKE TEST line two";
        let cmd = dump_argv_command(&["--dangerously-skip-permissions", prompt]);
        assert_eq!(
            argv_delivered_by(&cmd),
            vec![
                "--dangerously-skip-permissions".to_string(),
                prompt.to_string()
            ],
        );
    }

    #[test]
    fn a_dollar_command_is_not_expanded_away() {
        // Codex's skill syntax is `$agtx-plan`. Interpolated into the wrapper
        // unquoted, the shell expanded `$agtx` to nothing and only `-plan`
        // survived β€” the whole task text with it.
        let prompt = "$agtx-plan 468b79fa\n\nSMOKE TEST";
        let cmd = dump_argv_command(&["--sandbox", "workspace-write", prompt]);
        assert_eq!(
            argv_delivered_by(&cmd),
            vec![
                "--sandbox".to_string(),
                "workspace-write".to_string(),
                prompt.to_string(),
            ],
        );
    }

    #[test]
    fn a_quote_in_the_task_survives_both_quoting_layers() {
        let prompt = "fix the parser so it's correct";
        let cmd = dump_argv_command(&[prompt]);
        assert_eq!(argv_delivered_by(&cmd), vec![prompt.to_string()]);
    }

    /// Run the wrapped command with a fake `claude` on `PATH` that echoes its
    /// argv, and return what that binary actually received.
    ///
    /// `sh -n` is not enough here: it parses only the *outer* layer, and the
    /// wrapper is always outer-valid. A mis-quoted inner command parses fine and
    /// then dies at run time with "unexpected EOF while looking for matching `''"
    /// β€” verified, and the reason the first version of this test had no teeth.
    #[cfg(unix)]
    fn argv_seen_by_fake_claude(shell_cmd: &str) -> (bool, String) {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().expect("tempdir");
        let fake = dir.path().join("claude");
        std::fs::write(&fake, "#!/bin/sh\nprintf '%s\\n' \"$@\"\n").expect("write fake");
        std::fs::set_permissions(&fake, std::fs::Permissions::from_mode(0o755)).expect("chmod");
        let path = format!(
            "{}:{}",
            dir.path().display(),
            std::env::var("PATH").unwrap_or_default()
        );
        let out = std::process::Command::new("sh")
            .arg("-c")
            .arg(wrap_launch_command(shell_cmd, false))
            .env("PATH", path)
            .output()
            .expect("sh should run");
        (
            out.status.success(),
            String::from_utf8_lossy(&out.stdout).to_string(),
        )
    }

    /// The orchestrator command is the other thing `create_window` wraps, and it
    /// carries a single-quoted JSON blob for `claude mcp add-json`.
    ///
    /// It must not pre-escape its own wrapping quotes: `single_quote` already
    /// quotes the whole command, so a pre-escape double-escapes and the pane
    /// dies on an unterminated quote before `add-json` runs β€” silently, because
    /// the window is created either way. Nothing else covers this path; the TUI
    /// tests mock the command builder.
    #[cfg(unix)]
    #[test]
    fn the_orchestrator_command_reaches_claude_with_its_json_intact() {
        let agent = crate::agent::Agent::new("claude", "claude", "", "");
        let ops = crate::agent::CodingAgent::new(agent);
        let json = r#"{"type":"stdio","command":"/bin/agtx","args":["mcp-serve","/tmp/repo"]}"#;
        let cmd =
            crate::agent::AgentOperations::build_orchestrator_command(&ops, json, "/bin/agtx");
        let (ok, seen) = argv_seen_by_fake_claude(&cmd);
        assert!(ok, "the wrapped orchestrator command must run: {seen}");
        assert!(
            seen.lines().any(|l| l == json),
            "claude must receive the JSON as one intact argument; got:\n{seen}"
        );
    }

    /// ...and a project path containing an apostrophe still arrives intact,
    /// because the caller escapes it for the single-quoted word it lands in.
    #[cfg(unix)]
    #[test]
    fn an_apostrophe_in_the_mcp_json_survives_both_layers() {
        let agent = crate::agent::Agent::new("claude", "claude", "", "");
        let ops = crate::agent::CodingAgent::new(agent);
        let raw = r#"{"args":["mcp-serve","/tmp/it's a repo"]}"#;
        let escaped = raw.replace('\'', "'\"'\"'");
        let cmd =
            crate::agent::AgentOperations::build_orchestrator_command(&ops, &escaped, "/bin/agtx");
        let (ok, seen) = argv_seen_by_fake_claude(&cmd);
        assert!(ok, "the wrapped orchestrator command must run: {seen}");
        assert!(
            seen.lines().any(|l| l == raw),
            "claude must receive the unescaped JSON; got:\n{seen}"
        );
    }

    #[test]
    fn the_pane_drops_to_a_shell_only_when_asked() {
        assert!(wrap_launch_command("claude", true).ends_with("; exec $SHELL"));
        assert!(!wrap_launch_command("claude", false).contains("exec $SHELL"));
    }
}