enya-agent 0.1.0

package/crates/enact-tools/src/security.rs

@@ -0,0 +1,227 @@
+//! Security policy for tool execution
+//!
+//! Provides autonomy levels, rate limiting, and path sandboxing.
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU32, Ordering};
+
+/// Autonomy level for agent actions
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum AutonomyLevel {
+    /// Read-only access, no modifications allowed
+    ReadOnly,
+    /// Supervised mode (default) - some actions require approval
+    #[default]
+    Supervised,
+    /// Full autonomy - all actions allowed
+    Full,
+}
+
+/// Security policy configuration for tools
+pub struct SecurityPolicy {
+    /// Autonomy level
+    pub autonomy: AutonomyLevel,
+    /// Workspace directory (tools are sandboxed to this)
+    pub workspace_dir: PathBuf,
+    /// Allowed shell commands (empty = allow all safe commands)
+    pub allowed_commands: Vec<String>,
+    /// Blocked shell commands
+    pub blocked_commands: Vec<String>,
+    /// Maximum actions per hour (0 = unlimited)
+    pub max_actions_per_hour: u32,
+    /// Action counter for rate limiting
+    action_count: AtomicU32,
+}
+
+impl Default for SecurityPolicy {
+    fn default() -> Self {
+        Self {
+            autonomy: AutonomyLevel::Supervised,
+            workspace_dir: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
+            allowed_commands: Vec::new(),
+            blocked_commands: vec![
+                "rm -rf /".into(),
+                "sudo".into(),
+                "chmod 777".into(),
+                "dd if=".into(),
+                "> /dev/".into(),
+            ],
+            max_actions_per_hour: 1000,
+            action_count: AtomicU32::new(0),
+        }
+    }
+}
+
+impl SecurityPolicy {
+    /// Create a new security policy
+    pub fn new(workspace_dir: PathBuf) -> Self {
+        Self {
+            workspace_dir,
+            ..Self::default()
+        }
+    }
+
+    /// Check if the agent can perform write actions
+    pub fn can_act(&self) -> bool {
+        !matches!(self.autonomy, AutonomyLevel::ReadOnly)
+    }
+
+    /// Check if rate limited
+    pub fn is_rate_limited(&self) -> bool {
+        if self.max_actions_per_hour == 0 {
+            return false;
+        }
+        self.action_count.load(Ordering::Relaxed) >= self.max_actions_per_hour
+    }
+
+    /// Record an action and return true if allowed
+    pub fn record_action(&self) -> bool {
+        if self.max_actions_per_hour == 0 {
+            return true;
+        }
+        let current = self.action_count.fetch_add(1, Ordering::Relaxed);
+        current < self.max_actions_per_hour
+    }
+
+    /// Check if a relative path is allowed (no path traversal)
+    pub fn is_path_allowed(&self, path: &str) -> bool {
+        // Block absolute paths
+        if path.starts_with('/') || path.starts_with('\\') {
+            return false;
+        }
+        // Block path traversal
+        if path.contains("..") {
+            return false;
+        }
+        // Block null bytes
+        if path.contains('\0') {
+            return false;
+        }
+        true
+    }
+
+    /// Check if a resolved (canonicalized) path is within workspace
+    pub fn is_resolved_path_allowed(&self, resolved: &Path) -> bool {
+        resolved.starts_with(&self.workspace_dir)
+    }
+
+    /// Validate a shell command for execution
+    pub fn validate_command_execution(&self, command: &str, approved: bool) -> Result<(), String> {
+        if !self.can_act() {
+            return Err("Shell command not allowed: autonomy is read-only".into());
+        }
+
+        // Check blocked commands
+        for blocked in &self.blocked_commands {
+            if command.contains(blocked) {
+                return Err(format!("Command blocked by security policy: {blocked}"));
+            }
+        }
+
+        // High-risk command patterns
+        let high_risk = [
+            "rm -rf",
+            "mkfs",
+            "dd if=",
+            "> /dev/",
+            "sudo",
+            "chmod 777",
+            "curl | sh",
+            "wget | sh",
+        ];
+
+        for pattern in high_risk {
+            if command.contains(pattern) {
+                return Err(format!(
+                    "high-risk command not allowed without explicit override: {pattern}"
+                ));
+            }
+        }
+
+        // Medium-risk commands need approval in supervised mode
+        if self.autonomy == AutonomyLevel::Supervised && !approved {
+            let medium_risk = ["rm", "mv", "cp", "touch", "mkdir", "chmod", "chown"];
+            for pattern in medium_risk {
+                if command.split_whitespace().next() == Some(pattern) {
+                    return Err(format!(
+                        "Command '{pattern}' requires explicit approval in supervised mode. Set approved=true."
+                    ));
+                }
+            }
+        }
+
+        // If allowed_commands is set, check against it
+        if !self.allowed_commands.is_empty() {
+            let cmd_name = command.split_whitespace().next().unwrap_or("");
+            if !self.allowed_commands.iter().any(|c| c == cmd_name) {
+                return Err(format!("Command '{cmd_name}' not in allowed commands list"));
+            }
+        }
+
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_is_supervised() {
+        let policy = SecurityPolicy::default();
+        assert_eq!(policy.autonomy, AutonomyLevel::Supervised);
+    }
+
+    #[test]
+    fn can_act_respects_autonomy() {
+        let mut policy = SecurityPolicy::default();
+        assert!(policy.can_act());
+
+        policy.autonomy = AutonomyLevel::ReadOnly;
+        assert!(!policy.can_act());
+
+        policy.autonomy = AutonomyLevel::Full;
+        assert!(policy.can_act());
+    }
+
+    #[test]
+    fn path_blocks_traversal() {
+        let policy = SecurityPolicy::default();
+        assert!(!policy.is_path_allowed("../etc/passwd"));
+        assert!(!policy.is_path_allowed("/etc/passwd"));
+        assert!(policy.is_path_allowed("src/main.rs"));
+        assert!(policy.is_path_allowed("file.txt"));
+    }
+
+    #[test]
+    fn blocks_high_risk_commands() {
+        let policy = SecurityPolicy::default();
+        assert!(policy.validate_command_execution("rm -rf /", false).is_err());
+        assert!(policy.validate_command_execution("sudo apt install", false).is_err());
+    }
+
+    #[test]
+    fn medium_risk_needs_approval() {
+        let policy = SecurityPolicy::default();
+        let result = policy.validate_command_execution("rm file.txt", false);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("approval"));
+
+        let result = policy.validate_command_execution("rm file.txt", true);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn rate_limiting_works() {
+        let policy = SecurityPolicy {
+            max_actions_per_hour: 2,
+            ..SecurityPolicy::default()
+        };
+
+        assert!(!policy.is_rate_limited());
+        assert!(policy.record_action());
+        assert!(policy.record_action());
+        assert!(!policy.record_action());
+        assert!(policy.is_rate_limited());
+    }
+}

package/crates/enact-tools/src/shell.rs

@@ -0,0 +1,191 @@
+//! Shell command execution tool with sandboxing
+
+use crate::security::SecurityPolicy;
+use crate::traits::{Tool, ToolResult};
+use async_trait::async_trait;
+use serde_json::json;
+use std::sync::Arc;
+use std::time::Duration;
+
+/// Maximum shell command execution time before kill.
+const SHELL_TIMEOUT_SECS: u64 = 60;
+/// Maximum output size in bytes (1MB).
+const MAX_OUTPUT_BYTES: usize = 1_048_576;
+/// Environment variables safe to pass to shell commands.
+const SAFE_ENV_VARS: &[&str] = &[
+    "PATH", "HOME", "TERM", "LANG", "LC_ALL", "LC_CTYPE", "USER", "SHELL", "TMPDIR",
+];
+
+/// Shell command execution tool with sandboxing
+pub struct ShellTool {
+    security: Arc<SecurityPolicy>,
+}
+
+impl ShellTool {
+    pub fn new(security: Arc<SecurityPolicy>) -> Self {
+        Self { security }
+    }
+}
+
+#[async_trait]
+impl Tool for ShellTool {
+    fn name(&self) -> &str {
+        "shell"
+    }
+
+    fn description(&self) -> &str {
+        "Execute a shell command in the workspace directory"
+    }
+
+    fn parameters_schema(&self) -> serde_json::Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The shell command to execute"
+                },
+                "approved": {
+                    "type": "boolean",
+                    "description": "Set true to explicitly approve medium/high-risk commands in supervised mode",
+                    "default": false
+                }
+            },
+            "required": ["command"]
+        })
+    }
+
+    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
+        let command = args
+            .get("command")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing 'command' parameter"))?;
+        let approved = args
+            .get("approved")
+            .and_then(|v| v.as_bool())
+            .unwrap_or(false);
+
+        if self.security.is_rate_limited() {
+            return Ok(ToolResult::failure(
+                "Rate limit exceeded: too many actions in the last hour",
+            ));
+        }
+
+        if let Err(reason) = self.security.validate_command_execution(command, approved) {
+            return Ok(ToolResult::failure(reason));
+        }
+
+        if !self.security.record_action() {
+            return Ok(ToolResult::failure(
+                "Rate limit exceeded: action budget exhausted",
+            ));
+        }
+
+        // Build command with cleaned environment
+        let mut cmd = tokio::process::Command::new("sh");
+        cmd.arg("-c")
+            .arg(command)
+            .current_dir(&self.security.workspace_dir)
+            .env_clear();
+
+        for var in SAFE_ENV_VARS {
+            if let Ok(val) = std::env::var(var) {
+                cmd.env(var, val);
+            }
+        }
+
+        let result =
+            tokio::time::timeout(Duration::from_secs(SHELL_TIMEOUT_SECS), cmd.output()).await;
+
+        match result {
+            Ok(Ok(output)) => {
+                let mut stdout = String::from_utf8_lossy(&output.stdout).to_string();
+                let mut stderr = String::from_utf8_lossy(&output.stderr).to_string();
+
+                // Truncate output to prevent OOM
+                if stdout.len() > MAX_OUTPUT_BYTES {
+                    stdout.truncate(stdout.floor_char_boundary(MAX_OUTPUT_BYTES));
+                    stdout.push_str("\n... [output truncated at 1MB]");
+                }
+                if stderr.len() > MAX_OUTPUT_BYTES {
+                    stderr.truncate(stderr.floor_char_boundary(MAX_OUTPUT_BYTES));
+                    stderr.push_str("\n... [stderr truncated at 1MB]");
+                }
+
+                Ok(ToolResult {
+                    success: output.status.success(),
+                    output: stdout,
+                    error: if stderr.is_empty() {
+                        None
+                    } else {
+                        Some(stderr)
+                    },
+                })
+            }
+            Ok(Err(e)) => Ok(ToolResult::failure(format!(
+                "Failed to execute command: {e}"
+            ))),
+            Err(_) => Ok(ToolResult::failure(format!(
+                "Command timed out after {SHELL_TIMEOUT_SECS}s and was killed"
+            ))),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::security::AutonomyLevel;
+
+    fn test_security(autonomy: AutonomyLevel) -> Arc<SecurityPolicy> {
+        Arc::new(SecurityPolicy {
+            autonomy,
+            workspace_dir: std::env::temp_dir(),
+            ..SecurityPolicy::default()
+        })
+    }
+
+    #[test]
+    fn shell_tool_name() {
+        let tool = ShellTool::new(test_security(AutonomyLevel::Supervised));
+        assert_eq!(tool.name(), "shell");
+    }
+
+    #[test]
+    fn shell_tool_schema_has_command() {
+        let tool = ShellTool::new(test_security(AutonomyLevel::Supervised));
+        let schema = tool.parameters_schema();
+        assert!(schema["properties"]["command"].is_object());
+        assert!(schema["required"]
+            .as_array()
+            .unwrap()
+            .contains(&json!("command")));
+    }
+
+    #[tokio::test]
+    async fn shell_executes_allowed_command() {
+        let tool = ShellTool::new(test_security(AutonomyLevel::Supervised));
+        let result = tool
+            .execute(json!({"command": "echo hello"}))
+            .await
+            .unwrap();
+        assert!(result.success);
+        assert!(result.output.trim().contains("hello"));
+    }
+
+    #[tokio::test]
+    async fn shell_blocks_disallowed_command() {
+        let tool = ShellTool::new(test_security(AutonomyLevel::Supervised));
+        let result = tool.execute(json!({"command": "rm -rf /"})).await.unwrap();
+        assert!(!result.success);
+        assert!(result.error.is_some());
+    }
+
+    #[tokio::test]
+    async fn shell_blocks_readonly() {
+        let tool = ShellTool::new(test_security(AutonomyLevel::ReadOnly));
+        let result = tool.execute(json!({"command": "ls"})).await.unwrap();
+        assert!(!result.success);
+        assert!(result.error.as_ref().unwrap().contains("read-only"));
+    }
+}

package/crates/enact-tools/src/traits.rs

@@ -0,0 +1,159 @@
+//! Core tool traits and types
+
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+
+/// Result of a tool execution
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ToolResult {
+    pub success: bool,
+    pub output: String,
+    pub error: Option<String>,
+}
+
+impl ToolResult {
+    /// Create a successful result
+    pub fn success(output: impl Into<String>) -> Self {
+        Self {
+            success: true,
+            output: output.into(),
+            error: None,
+        }
+    }
+
+    /// Create a failure result
+    pub fn failure(error: impl Into<String>) -> Self {
+        Self {
+            success: false,
+            output: String::new(),
+            error: Some(error.into()),
+        }
+    }
+}
+
+/// Description of a tool for the LLM
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ToolSpec {
+    pub name: String,
+    pub description: String,
+    pub parameters: serde_json::Value,
+}
+
+/// Core tool trait — implement for any capability
+#[async_trait]
+pub trait Tool: Send + Sync {
+    /// Tool name (used in LLM function calling)
+    fn name(&self) -> &str;
+
+    /// Human-readable description
+    fn description(&self) -> &str;
+
+    /// JSON schema for parameters
+    fn parameters_schema(&self) -> serde_json::Value;
+
+    /// Execute the tool with given arguments
+    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;
+
+    /// Get the full spec for LLM registration
+    fn spec(&self) -> ToolSpec {
+        ToolSpec {
+            name: self.name().to_string(),
+            description: self.description().to_string(),
+            parameters: self.parameters_schema(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    struct DummyTool;
+
+    #[async_trait]
+    impl Tool for DummyTool {
+        fn name(&self) -> &str {
+            "dummy_tool"
+        }
+
+        fn description(&self) -> &str {
+            "A deterministic test tool"
+        }
+
+        fn parameters_schema(&self) -> serde_json::Value {
+            serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "value": { "type": "string" }
+                }
+            })
+        }
+
+        async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
+            Ok(ToolResult {
+                success: true,
+                output: args
+                    .get("value")
+                    .and_then(serde_json::Value::as_str)
+                    .unwrap_or_default()
+                    .to_string(),
+                error: None,
+            })
+        }
+    }
+
+    #[test]
+    fn spec_uses_tool_metadata_and_schema() {
+        let tool = DummyTool;
+        let spec = tool.spec();
+
+        assert_eq!(spec.name, "dummy_tool");
+        assert_eq!(spec.description, "A deterministic test tool");
+        assert_eq!(spec.parameters["type"], "object");
+        assert_eq!(spec.parameters["properties"]["value"]["type"], "string");
+    }
+
+    #[tokio::test]
+    async fn execute_returns_expected_output() {
+        let tool = DummyTool;
+        let result = tool
+            .execute(serde_json::json!({ "value": "hello-tool" }))
+            .await
+            .unwrap();
+
+        assert!(result.success);
+        assert_eq!(result.output, "hello-tool");
+        assert!(result.error.is_none());
+    }
+
+    #[test]
+    fn tool_result_success_helper() {
+        let result = ToolResult::success("done");
+        assert!(result.success);
+        assert_eq!(result.output, "done");
+        assert!(result.error.is_none());
+    }
+
+    #[test]
+    fn tool_result_failure_helper() {
+        let result = ToolResult::failure("boom");
+        assert!(!result.success);
+        assert_eq!(result.output, "");
+        assert_eq!(result.error.as_deref(), Some("boom"));
+    }
+
+    #[test]
+    fn tool_result_serialization_roundtrip() {
+        let result = ToolResult {
+            success: false,
+            output: String::new(),
+            error: Some("boom".into()),
+        };
+
+        let json = serde_json::to_string(&result).unwrap();
+        let parsed: ToolResult = serde_json::from_str(&json).unwrap();
+
+        assert!(!parsed.success);
+        assert_eq!(parsed.error.as_deref(), Some("boom"));
+    }
+}

package/docs/Makefile

@@ -0,0 +1,74 @@
+# Enact Documentation - Makefile
+# Built with Zola (https://www.getzola.org/)
+
+.PHONY: build serve clean check install-zola help
+
+# Default target
+help:
+	@echo "Enact Documentation Commands"
+	@echo "============================"
+	@echo ""
+	@echo "  make build        Build the documentation site"
+	@echo "  make serve        Start development server with hot reload"
+	@echo "  make clean        Remove build artifacts"
+	@echo "  make check        Check for broken links and errors"
+	@echo "  make install-zola Install Zola static site generator"
+	@echo ""
+	@echo "Development server runs at http://127.0.0.1:1111"
+
+# Build the documentation site
+build:
+	@echo "Building documentation..."
+	zola build
+	@echo "Build complete! Output in public/"
+
+# Start development server with hot reload
+serve:
+	@echo "Starting development server at http://127.0.0.1:1111"
+	zola serve
+
+# Serve on all interfaces (useful for testing on other devices)
+serve-public:
+	@echo "Starting public server at http://0.0.0.0:1111"
+	zola serve --interface 0.0.0.0
+
+# Remove build artifacts
+clean:
+	@echo "Cleaning build artifacts..."
+	rm -rf public/
+	@echo "Clean complete!"
+
+# Check for errors without building
+check:
+	@echo "Checking documentation..."
+	zola check
+	@echo "Check complete!"
+
+# Install Zola (macOS)
+install-zola:
+	@echo "Installing Zola..."
+	@if command -v brew >/dev/null 2>&1; then \
+		brew install zola; \
+	elif command -v cargo >/dev/null 2>&1; then \
+		cargo install zola; \
+	else \
+		echo "Please install Homebrew or Cargo first"; \
+		exit 1; \
+	fi
+	@echo "Zola installed!"
+
+# Build for production (minified)
+build-prod:
+	@echo "Building for production..."
+	zola build --force
+	@echo "Production build complete!"
+
+# Watch for changes and rebuild (alternative to serve)
+watch:
+	@echo "Watching for changes..."
+	zola build --drafts
+	@while true; do \
+		fswatch -1 content/ templates/ sass/ static/ config.toml && \
+		echo "Rebuilding..." && \
+		zola build --drafts; \
+	done