Command Execution Engine

Relevant source files

The following files were used as context for generating this wiki page:

• src/execution/executor.rs
• src/execution/shell.rs
• tests/execution_contract.rs
• specs/003-implement-core-infrastructure/tasks.md
• specs/003-implement-core-infrastructure/plan.md
• CONTRIBUTING.md
• specs/006-intelligent-prompt-generation/spec.md

The Command Execution Engine is a foundational infrastructure module in caro responsible for capturing the user's current environment and system context. Its primary purpose is to gather critical information such as the operating system, shell type, and environment variables. This captured context is essential for the Intelligent Prompt Generation system to produce accurate, platform-aware shell commands, preventing the generation of incompatible commands (e.g., GNU flags on a BSD system).

This engine does not execute commands itself but rather provides the necessary "execution context" for other parts of the system, like the Safety Module and LLM backends, to make informed decisions. It is designed to be fast, with a target capture time of less than 50ms, and operates with zero unsafe Rust code.

Sources: specs/003-implement-core-infrastructure/plan.md:38-46, 78-82, specs/006-intelligent-prompt-generation/spec.md:14-19, specs/003-implement-core-infrastructure/tasks.md:126-133, 169-171

Architecture Overview

The engine is composed of three main components: ExecutionContext, ShellDetector, and PlatformDetector. The ExecutionContext acts as the central orchestrator, using the detector components to gather information and assemble a comprehensive snapshot of the user's environment.

The following diagram illustrates the data flow during the context capture process.

This diagram shows the ExecutionContext::capture method orchestrating the detection of shell and platform, and the collection of environment variables to build the final ExecutionContext struct.

Sources: specs/003-implement-core-infrastructure/plan.md:106-108, tests/execution_contract.rs:20-23, specs/003-implement-core-infrastructure/tasks.md:126-133

Core Components

The engine is implemented across several files, primarily src/execution/mod.rs and src/execution/shell.rs.

Sources: specs/003-implement-core-infrastructure/tasks.md:126-133

ExecutionContext

The ExecutionContext struct is the primary data model that encapsulates all captured environmental information. It is designed to be created via the capture() method, which populates its fields.

Sources: specs/003-implement-core-infrastructure/tasks.md:135-139, tests/execution_contract.rs:20-23

Data Structure

The fields of the ExecutionContext struct provide a detailed snapshot of the system at the time of capture.

Field	Type	Description
current_dir	PathBuf	The current working directory.
shell_type	ShellType	The detected user shell (e.g., Bash, Zsh, PowerShell).
platform	Platform	The detected operating system (e.g., Linux, MacOS, Windows).
environment_vars	HashMap<String, String>	A map of environment variables, with sensitive ones filtered out.
username	String	The current user's name.
hostname	String	The machine's hostname.
captured_at	DateTime<Utc>	The timestamp of when the context was captured.

Sources: specs/003-implement-core-infrastructure/tasks.md:135-139, specs/003-implement-core-infrastructure/contracts/execution-api.md:13-25

Context Capture Process

The capture() method is the entry point for gathering context. It performs the following steps:

1. Detects the current platform using Platform::detect().
2. Detects the active shell using ShellDetector::detect().
3. Reads the current working directory, username, and hostname.
4. Collects all environment variables.
5. Filters out sensitive environment variables (e.g., those containing API_KEY, TOKEN, PASSWORD).
6. Constructs and returns the ExecutionContext instance.

This process is designed to be completed in under 50ms.

Sources: tests/execution_contract.rs:20-41, specs/003-implement-core-infrastructure/tasks.md:169-171, specs/003-implement-core-infrastructure/plan.md:43

ShellDetector

Located in src/execution/shell.rs, the ShellDetector is responsible for identifying the user's current shell.

The detection logic follows a specific order of strategies:

1. Environment Variable: It first checks the SHELL environment variable.
2. Path Parsing: If the SHELL variable is not definitive, it parses the path of the shell executable (e.g., /bin/zsh, /usr/bin/bash).
3. Override: The detection can be manually overridden for specific use cases.

This diagram shows the decision process for shell detection.

Sources: src/execution/shell.rs, tests/execution_contract.rs:43-74, specs/003-implement-core-infrastructure/tasks.md:130, 172-173

PlatformDetector

Also in src/execution/shell.rs, the PlatformDetector identifies the host operating system. This is achieved using compile-time cfg! macros, making it a highly efficient and reliable static check.

The supported platforms are:

• Linux
• MacOS
• Windows

Sources: src/execution/shell.rs, specs/003-implement-core-infrastructure/tasks.md:111-115, tests/execution_contract.rs:76-88

API and Contracts

The public API and behavior of the Execution Engine are defined and validated by a suite of contract tests in tests/execution_contract.rs. These tests ensure the module adheres to its design specifications.

Key tested contracts include:

• Context Capture: ExecutionContext::capture() correctly gathers all required information.
• Shell Detection: ShellDetector accurately identifies various shells (Bash, Zsh, Fish, PowerShell).
• Platform Detection: PlatformDetector correctly identifies the OS.
• Environment Variable Filtering: Sensitive variables are successfully removed from the context.
• Prompt Context Generation: to_prompt_context() serializes the context into a string suitable for an LLM prompt.
• Performance: The entire capture process must complete in under 50ms.

Sources: tests/execution_contract.rs, specs/003-implement-core-infrastructure/tasks.md:23-31

Security Considerations

The src/execution/ module is designated as a security-sensitive area. Although it does not execute commands, its role in gathering environment variables presents a risk of leaking sensitive information.

The primary mitigation is the filtering of environment variables based on common secret-related keywords like TOKEN, API_KEY, and PASSWORD. This redaction logic is critical to prevent credentials from being inadvertently included in logs or LLM prompts.

Sources: CONTRIBUTING.md:213-222, tests/execution_contract.rs:114-131, specs/003-implement-core-infrastructure/tasks.md:172

Conclusion

The Command Execution Engine is a vital, non-executable module that provides the foundational context awareness for caro. By accurately detecting the user's platform, shell, and environment, it enables the rest of the application to generate safe, relevant, and compatible shell commands. Its design is guided by strict TDD principles, performance targets, and security considerations, ensuring it is a reliable and robust component of the system's core infrastructure.

Sources: specs/003-implement-core-infrastructure/plan.md:38-46