Skip to main content

ProcessExecutor

ralph_workflow::executor

Trait ProcessExecutor 

Source 
pub trait ProcessExecutor:
    Send
    + Sync
    + Debug {
    // Required method
    fn execute(
        &self,
        command: &str,
        args: &[&str],
        env: &[(String, String)],
        workdir: Option<&Path>,
    ) -> Result<ProcessOutput>;

    // Provided methods
    fn spawn(
        &self,
        command: &str,
        args: &[&str],
        env: &[(String, String)],
        workdir: Option<&Path>,
    ) -> Result<Child> { ... }
    fn spawn_agent(&self, config: &AgentSpawnConfig) -> Result<AgentChildHandle> { ... }
    fn command_exists(&self, command: &str) -> bool { ... }
    fn has_active_child_processes(&self, parent_pid: u32) -> bool { ... }
}
Expand description

Trait for executing external processes.

This trait abstracts process execution to allow dependency injection. Production code uses RealProcessExecutor which calls actual commands. Test code can use MockProcessExecutor to control process behavior.

Only external process execution is abstracted. Internal code logic is never mocked.

Required Methods§

Source

fn execute( &self, command: &str, args: &[&str], env: &[(String, String)], workdir: Option<&Path>, ) -> Result<ProcessOutput>

Execute a command with given arguments and return its output.

§Arguments
  • command - The program to execute
  • args - Command-line arguments to pass to the program
  • env - Environment variables to set for the process (optional)
  • workdir - Working directory for the process (optional)
§Returns

Returns a ProcessOutput containing exit status, stdout, and stderr.

§Errors

Returns an error if command cannot be spawned or if output capture fails.

Provided Methods§

Source

fn spawn( &self, command: &str, args: &[&str], env: &[(String, String)], workdir: Option<&Path>, ) -> Result<Child>

Spawn a process with stdin input and return the child handle.

This method is used when you need to write to the process’s stdin or stream its output in real-time. Unlike execute(), this returns a Child handle for direct interaction.

§Arguments
  • command - The program to execute
  • args - Command-line arguments to pass to the program
  • env - Environment variables to set for the process (optional)
  • workdir - Working directory for the process (optional)
§Returns

Returns a Child handle that can be used to interact with the process.

§Errors

Returns an error if command cannot be spawned.

Source

fn spawn_agent(&self, config: &AgentSpawnConfig) -> Result<AgentChildHandle>

Spawn an agent process with streaming output support.

This method is specifically designed for spawning AI agent subprocesses that need to output streaming JSON in real-time. Unlike spawn(), this returns a handle with boxed stdout for trait object compatibility.

§Arguments
  • config - Agent spawn configuration including command, args, env, prompt, etc.
§Returns

Returns an AgentChildHandle with stdout, stderr, and the child process.

§Errors

Returns an error if the agent cannot be spawned.

§Default Implementation

The default implementation uses the spawn() method with additional configuration for agent-specific needs. Mock implementations should override this to return mock results without spawning real processes.

Source

fn command_exists(&self, command: &str) -> bool

Check if a command exists and can be executed.

This is a convenience method that executes a command with a --version or similar flag to check if it’s available.

§Arguments
  • command - The program to check
§Returns

Returns true if command exists, false otherwise.

Source

fn has_active_child_processes(&self, parent_pid: u32) -> bool

Returns true if the process identified by parent_pid has at least one live child process.

Used by the idle-timeout monitor to avoid false-positive kills when the agent has spawned a subprocess (e.g. cargo test, npm install) that is still running even though the agent produces no stdout/stderr output.

Default implementation: invokes pgrep -P <pid> on Unix platforms and falls back to parsing ps output (PID/PPID pairs) if pgrep is unavailable. Returns false (conservative no-op) on non-Unix.

Any execution error is treated as “no children” to avoid blocking the timeout system. If both pgrep and the ps fallback are unavailable or fail unexpectedly, a one-time warning is emitted to stderr so operators can diagnose reduced protection against false-positive idle kills.

Implementors§