enya-agent 0.1.0

package/crates/enact-core/src/tool/web_search.rs

@@ -0,0 +1,277 @@
+//! Web search tool
+
+use crate::tool::Tool;
+use async_trait::async_trait;
+use serde_json::json;
+use std::time::Duration;
+
+const DEFAULT_MAX_RESULTS: usize = 5;
+const DEFAULT_TIMEOUT_SECS: u64 = 30;
+
+/// Web search tool supporting DuckDuckGo (free) and Brave (API key required)
+pub struct WebSearchTool {
+    provider: String,
+    brave_api_key: Option<String>,
+    max_results: usize,
+    timeout_secs: u64,
+}
+
+impl WebSearchTool {
+    pub fn new(provider: impl Into<String>) -> Self {
+        Self {
+            provider: provider.into().to_lowercase(),
+            brave_api_key: None,
+            max_results: DEFAULT_MAX_RESULTS,
+            timeout_secs: DEFAULT_TIMEOUT_SECS,
+        }
+    }
+
+    pub fn with_brave_key(mut self, key: impl Into<String>) -> Self {
+        self.brave_api_key = Some(key.into());
+        self
+    }
+
+    pub fn with_max_results(mut self, max: usize) -> Self {
+        self.max_results = max.clamp(1, 10);
+        self
+    }
+
+    pub fn with_timeout(mut self, secs: u64) -> Self {
+        self.timeout_secs = secs.max(1);
+        self
+    }
+
+    async fn search_duckduckgo(&self,
+        query: &str,
+    ) -> anyhow::Result<Vec<SearchResult>> {
+        let encoded_query = urlencoding::encode(query);
+        let search_url = format!(
+            "https://html.duckduckgo.com/html/?q={}",
+            encoded_query
+        );
+
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(self.timeout_secs))
+            .user_agent("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36")
+            .build()?;
+
+        let response = client.get(&search_url).send().await?;
+
+        if !response.status().is_success() {
+            anyhow::bail!(
+                "DuckDuckGo search failed: {}",
+                response.status()
+            );
+        }
+
+        let html = response.text().await?;
+        self.parse_duckduckgo_results(&html)
+    }
+
+    fn parse_duckduckgo_results(&self,
+        html: &str,
+    ) -> anyhow::Result<Vec<SearchResult>> {
+        let mut results = Vec::new();
+
+        // Simple regex-based parsing (in production, use a proper HTML parser)
+        let result_regex = regex::Regex::new(
+            r#"class="result__a"[^>]*href="([^"]+)"[^>]*>([^<]+)"#,
+        )?;
+
+        for cap in result_regex.captures_iter(html) {
+            if results.len() >= self.max_results {
+                break;
+            }
+
+            let url = cap.get(1).map(|m| m.as_str()).unwrap_or("");
+            let title = cap.get(2).map(|m| m.as_str()).unwrap_or("");
+
+            // Clean up the URL (DuckDuckGo uses redirects)
+            let url = if url.starts_with("//duckduckgo.com/l/?") {
+                // Extract actual URL from redirect
+                url.split("uddg=")
+                    .nth(1)
+                    .and_then(|u| urlencoding::decode(u).ok())
+                    .map(|s| s.to_string())
+                    .unwrap_or_else(|| url.to_string())
+            } else {
+                url.to_string()
+            };
+
+            let mut decoded_title = String::new();
+            html_escape::decode_html_entities_to_string(title, &mut decoded_title);
+            results.push(SearchResult {
+                title: decoded_title,
+                url,
+                snippet: String::new(),
+            });
+        }
+
+        Ok(results)
+    }
+
+    async fn search_brave(&self, query: &str) -> anyhow::Result<Vec<SearchResult>> {
+        let api_key = self
+            .brave_api_key
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Brave API key required"))?;
+
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(self.timeout_secs))
+            .build()?;
+
+        let response = client
+            .get("https://api.search.brave.com/res/v1/web/search")
+            .header("Accept", "application/json")
+            .header("X-Subscription-Token", api_key)
+            .query(&[("q", query), ("count", &self.max_results.to_string())])
+            .send()
+            .await?;
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            anyhow::bail!("Brave search failed ({}): {}", status, body);
+        }
+
+        let data: serde_json::Value = response.json().await?;
+        let mut results = Vec::new();
+
+        if let Some(web) = data.get("web") {
+            if let Some(pages) = web.get("results").and_then(|r| r.as_array()) {
+                for page in pages.iter().take(self.max_results) {
+                    results.push(SearchResult {
+                        title: page
+                            .get("title")
+                            .and_then(|t| t.as_str())
+                            .unwrap_or("")
+                            .to_string(),
+                        url: page
+                            .get("url")
+                            .and_then(|u| u.as_str())
+                            .unwrap_or("")
+                            .to_string(),
+                        snippet: page
+                            .get("description")
+                            .and_then(|d| d.as_str())
+                            .unwrap_or("")
+                            .to_string(),
+                    });
+                }
+            }
+        }
+
+        Ok(results)
+    }
+}
+
+#[derive(Debug, Clone)]
+struct SearchResult {
+    title: String,
+    url: String,
+    snippet: String,
+}
+
+#[async_trait]
+impl Tool for WebSearchTool {
+    fn name(&self) -> &str {
+        "web_search"
+    }
+
+    fn description(&self) -> &str {
+        "Search the web using DuckDuckGo (free) or Brave (requires API key)"
+    }
+
+    fn parameters_schema(&self) -> serde_json::Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query"
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum number of results (1-10)",
+                    "minimum": 1,
+                    "maximum": 10,
+                    "default": 5
+                }
+            },
+            "required": ["query"]
+        })
+    }
+
+    fn requires_network(&self) -> bool {
+        true
+    }
+
+    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<serde_json::Value> {
+        let query = args
+            .get("query")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing 'query' parameter"))?;
+
+        let max_results = args
+            .get("max_results")
+            .and_then(|v| v.as_u64())
+            .map(|n| n as usize)
+            .unwrap_or(DEFAULT_MAX_RESULTS)
+            .clamp(1, 10);
+
+        let results = match self.provider.as_str() {
+            "brave" => self.search_brave(query).await?,
+            "duckduckgo" | _ => self.search_duckduckgo(query).await?,
+        };
+
+        let results_json: Vec<serde_json::Value> = results
+            .into_iter()
+            .take(max_results)
+            .map(|r| {
+                json!({
+                    "title": r.title,
+                    "url": r.url,
+                    "snippet": r.snippet
+                })
+            })
+            .collect();
+
+        Ok(json!({
+            "success": true,
+            "query": query,
+            "provider": self.provider,
+            "results": results_json,
+            "count": results_json.len()
+        }))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_web_search_duckduckgo() {
+        let tool = WebSearchTool::new("duckduckgo");
+        let result = tool
+            .execute(json!({
+                "query": "Rust programming language",
+                "max_results": 3
+            }))
+            .await;
+
+        // May fail if no network, but should parse correctly
+        if let Ok(response) = result {
+            assert_eq!(response["success"], true);
+            assert!(response["count"].as_u64().unwrap_or(0) > 0);
+        }
+    }
+
+    #[test]
+    fn test_web_search_schema() {
+        let tool = WebSearchTool::new("duckduckgo");
+        let schema = tool.parameters_schema();
+        assert!(schema["properties"]["query"].is_object());
+        assert!(schema["properties"]["max_results"].is_object());
+    }
+}

package/crates/enact-core/src/util/mod.rs

@@ -0,0 +1,6 @@
+//! Shared utility types and helpers.
+//!
+//! This module will host common utilities such as
+//! error types, and configuration structures.
+
+

package/crates/enact-core/tests/airgapped_e2e_test.rs

@@ -0,0 +1,291 @@
+//! Air-Gapped E2E Tests - Verify zero network egress
+//!
+//! These tests verify that air-gapped mode:
+//! 1. Blocks network-requiring providers
+//! 2. Blocks network-requiring tools
+//! 3. Produces NetworkViolation errors
+//! 4. Allows local-only operations to proceed
+//!
+//! @see docs/feat-07-air-gapped-hardening.md
+
+use enact_core::kernel::{
+    ExecutionKernel, ExecutionState, StepType, ViolationType,
+    ExecutionErrorCategory, TenantId,
+};
+use enact_core::context::TenantContext;
+use enact_core::providers::{ModelProvider, ChatRequest, ChatResponse, ChatMessage, ModelCapabilities};
+use enact_core::tool::Tool;
+use async_trait::async_trait;
+use serde_json::Value;
+use std::sync::Arc;
+
+/// Helper to create a test TenantContext
+fn test_tenant() -> TenantContext {
+    TenantContext::new(TenantId::from("tenant_test"))
+}
+
+// =============================================================================
+// Mock Network-Requiring Provider
+// =============================================================================
+
+struct MockNetworkProvider;
+
+#[async_trait]
+impl ModelProvider for MockNetworkProvider {
+    fn name(&self) -> &str {
+        "mock-network-provider"
+    }
+
+    fn requires_network(&self) -> bool {
+        true // This provider requires network
+    }
+
+    fn capabilities(&self) -> ModelCapabilities {
+        ModelCapabilities::default()
+    }
+
+    async fn chat(&self, _request: ChatRequest) -> anyhow::Result<ChatResponse> {
+        // This would normally make a network call
+        // In air-gapped mode, this should be blocked before reaching here
+        anyhow::bail!("Network call attempted (should be blocked in air-gapped mode)")
+    }
+}
+
+// =============================================================================
+// Mock Local Provider
+// =============================================================================
+
+struct MockLocalProvider;
+
+#[async_trait]
+impl ModelProvider for MockLocalProvider {
+    fn name(&self) -> &str {
+        "mock-local-provider"
+    }
+
+    fn requires_network(&self) -> bool {
+        false // This provider does not require network
+    }
+
+    fn capabilities(&self) -> ModelCapabilities {
+        ModelCapabilities::default()
+    }
+
+    async fn chat(&self, _request: ChatRequest) -> anyhow::Result<ChatResponse> {
+        // Local provider - no network needed
+        Ok(ChatResponse {
+            id: "local-response-id".to_string(),
+            choices: vec![enact_core::providers::ChatChoice {
+                index: 0,
+                message: ChatMessage::assistant("Local response"),
+                finish_reason: Some("stop".to_string()),
+            }],
+            usage: Some(enact_core::providers::ChatUsage {
+                prompt_tokens: 10,
+                completion_tokens: 5,
+                total_tokens: 15,
+            }),
+        })
+    }
+}
+
+// =============================================================================
+// Mock Network-Requiring Tool
+// =============================================================================
+
+struct MockNetworkTool;
+
+#[async_trait]
+impl Tool for MockNetworkTool {
+    fn name(&self) -> &str {
+        "mock_network_tool"
+    }
+
+    fn description(&self) -> &str {
+        "A tool that requires network access"
+    }
+
+    fn requires_network(&self) -> bool {
+        true // This tool requires network
+    }
+
+    async fn execute(&self, _args: Value) -> anyhow::Result<Value> {
+        // This would normally make a network call
+        anyhow::bail!("Network call attempted (should be blocked in air-gapped mode)")
+    }
+}
+
+// =============================================================================
+// Mock Local Tool
+// =============================================================================
+
+struct MockLocalTool;
+
+#[async_trait]
+impl Tool for MockLocalTool {
+    fn name(&self) -> &str {
+        "mock_local_tool"
+    }
+
+    fn description(&self) -> &str {
+        "A tool that does not require network access"
+    }
+
+    fn requires_network(&self) -> bool {
+        false // This tool does not require network
+    }
+
+    async fn execute(&self, _args: Value) -> anyhow::Result<Value> {
+        // Local tool - no network needed
+        Ok(serde_json::json!({"result": "local computation"}))
+    }
+}
+
+// =============================================================================
+// Test Cases
+// =============================================================================
+
+/// Test that network-requiring providers are detected and blocked
+///
+/// This test verifies that:
+/// - Providers with `requires_network() == true` are identified
+/// - Attempting to use them in air-gapped mode should raise NetworkViolation
+#[tokio::test]
+async fn test_airgapped_blocks_network_provider() {
+    let network_provider = Arc::new(MockNetworkProvider);
+    
+    // Verify the provider declares it requires network
+    assert!(network_provider.requires_network(), "Provider should declare network requirement");
+    
+    // In a real implementation, the enforcement middleware would check this
+    // and raise a NetworkViolation before the provider is called.
+    // For now, we verify the provider correctly declares its requirement.
+}
+
+/// Test that network-requiring tools are detected and blocked
+///
+/// This test verifies that:
+/// - Tools with `requires_network() == true` are identified
+/// - Attempting to use them in air-gapped mode should raise NetworkViolation
+#[tokio::test]
+async fn test_airgapped_blocks_network_tool() {
+    let network_tool = Arc::new(MockNetworkTool);
+    
+    // Verify the tool declares it requires network
+    assert!(network_tool.requires_network(), "Tool should declare network requirement");
+    
+    // In a real implementation, the enforcement middleware would check this
+    // and raise a NetworkViolation before the tool is called.
+    // For now, we verify the tool correctly declares its requirement.
+}
+
+/// Test that local providers are allowed in air-gapped mode
+///
+/// This test verifies that:
+/// - Providers with `requires_network() == false` are allowed
+/// - They can be used without raising NetworkViolation
+#[tokio::test]
+async fn test_airgapped_allows_local_provider() {
+    let local_provider = Arc::new(MockLocalProvider);
+    
+    // Verify the provider declares it does not require network
+    assert!(!local_provider.requires_network(), "Provider should declare no network requirement");
+    
+    // The provider should be usable in air-gapped mode
+    let request = ChatRequest {
+        messages: vec![ChatMessage::user("test")],
+        temperature: None,
+        max_tokens: None,
+    };
+    
+    let response = local_provider.chat(request).await;
+    assert!(response.is_ok(), "Local provider should work in air-gapped mode");
+}
+
+/// Test that local tools are allowed in air-gapped mode
+///
+/// This test verifies that:
+/// - Tools with `requires_network() == false` are allowed
+/// - They can be used without raising NetworkViolation
+#[tokio::test]
+async fn test_airgapped_allows_local_tool() {
+    let local_tool = Arc::new(MockLocalTool);
+    
+    // Verify the tool declares it does not require network
+    assert!(!local_tool.requires_network(), "Tool should declare no network requirement");
+    
+    // The tool should be usable in air-gapped mode
+    let result = local_tool.execute(serde_json::json!({})).await;
+    assert!(result.is_ok(), "Local tool should work in air-gapped mode");
+}
+
+/// Test that NetworkViolation error type is correctly formatted
+///
+/// This test verifies that:
+/// - NetworkViolation maps to PolicyViolation category
+/// - Error is non-retryable
+/// - Error code is "network_violation"
+#[tokio::test]
+async fn test_network_violation_error_format() {
+    use enact_core::kernel::EnforcementViolation;
+    
+    let violation = EnforcementViolation::new(ViolationType::NetworkViolation, 0, 0);
+    let error = violation.to_error();
+    
+    // Verify error category
+    assert_eq!(error.category, ExecutionErrorCategory::PolicyViolation);
+    
+    // Verify error code
+    assert_eq!(error.code, Some("network_violation".to_string()));
+    
+    // Verify error is non-retryable (PolicyViolation is fatal)
+    assert!(!error.retry_policy.retryable);
+    assert!(error.category.is_fatal());
+}
+
+/// Test that execution kernel can be created in air-gapped context
+///
+/// This test verifies that:
+/// - ExecutionKernel can be instantiated
+/// - Basic operations work without network
+#[tokio::test]
+async fn test_airgapped_kernel_basic_operations() {
+    let mut kernel = ExecutionKernel::new(test_tenant());
+    
+    // Start execution
+    kernel.start().unwrap();
+    assert_eq!(kernel.state(), ExecutionState::Running);
+    
+    // Begin a step (local operation, no network needed)
+    let step_id = kernel.begin_step(
+        StepType::LlmNode,
+        "test_step",
+        None,
+    ).unwrap();
+    
+    // Complete the step
+    kernel.complete_step(step_id, Some("output".to_string()), 100).unwrap();
+    
+    // Complete execution
+    kernel.complete(Some("final output".to_string())).unwrap();
+    assert_eq!(kernel.state(), ExecutionState::Completed);
+}
+
+/// Test that NetworkViolation is properly serialized
+///
+/// This test verifies that:
+/// - ViolationType::NetworkViolation serializes correctly
+/// - Error messages are formatted correctly
+#[tokio::test]
+async fn test_network_violation_serialization() {
+    use enact_core::kernel::EnforcementViolation;
+    
+    let violation = EnforcementViolation::new(ViolationType::NetworkViolation, 0, 0);
+    
+    // Verify string representation
+    assert_eq!(format!("{}", ViolationType::NetworkViolation), "network_violation");
+    
+    // Verify violation message format
+    assert!(violation.message.contains("network_violation"));
+}
+

package/crates/enact-core/tests/e2e_agentic_loop.rs

@@ -0,0 +1,119 @@
+use enact_core::kernel::{ExecutionEventType, ExecutionId, StepId};
+use enact_core::streaming::{EventEmitter, EventLog, StreamEvent};
+use enact_core::{EventStore, InMemoryEventStore};
+use std::sync::Arc;
+use tokio::time::Duration;
+
+#[tokio::test]
+async fn test_agentic_loop_event_persistence() {
+    // 1. Setup - Create an EventStore and EventEmitter
+    // InMemoryEventStore implements enact_core::EventStore (which is the streaming one)
+    let event_store = Arc::new(InMemoryEventStore::new());
+    let event_log = Arc::new(EventLog::new(event_store.clone()));
+    let execution_id = ExecutionId::new();
+
+    let mut emitter = EventEmitter::with_persistence(event_log.clone(), execution_id.clone());
+    emitter.set_event_log(event_log, execution_id.clone());
+
+    // 2. Simulate Agentic Loop - Tool Execution
+    let step_id = StepId::new();
+    let tool_call_id = "call_12345";
+    let tool_name = "weather_tool";
+
+    // 2a. Tool Input Available (Should be mapped to ExecutionEventType::ToolCallStart)
+    let input_payload = serde_json::json!({ "city": "San Francisco" });
+    emitter.emit(StreamEvent::ToolInputAvailable {
+        tool_call_id: tool_call_id.to_string(),
+        tool_name: tool_name.to_string(),
+        input: input_payload.clone(),
+    });
+
+    // 2b. Tool Output Available (Should be mapped to ExecutionEventType::ToolCallEnd)
+    let output_payload = serde_json::json!({ "temp": 72, "conditions": "Sunny" });
+    emitter.emit(StreamEvent::ToolOutputAvailable {
+        tool_call_id: tool_call_id.to_string(),
+        output: output_payload.clone(),
+    });
+
+    // 3. Simulate Agentic Loop - Checkpoint
+    let checkpoint_id = "chk_12345";
+    emitter.emit(StreamEvent::CheckpointSaved {
+        execution_id: execution_id.as_str().to_string(),
+        step_id: Some(step_id.as_str().to_string()),
+        checkpoint_id: checkpoint_id.to_string(),
+        state_hash: "hash_abc123".to_string(),
+        timestamp: 1234567890,
+    });
+
+    // 4. Simulate Agentic Loop - Goal Evaluation
+    emitter.emit(StreamEvent::GoalEvaluated {
+        execution_id: execution_id.as_str().to_string(),
+        step_id: Some(step_id.as_str().to_string()),
+        goal_id: "goal_primary".to_string(),
+        status: "met".to_string(),
+        score: Some(1.0),
+        reason: Some("Task completed successfully".to_string()),
+        timestamp: 1234567890,
+    });
+
+    // Allow async persistence to complete
+    tokio::time::sleep(Duration::from_millis(100)).await;
+
+    // 5. Verification - Check EventStore (requires EventStore trait in scope)
+    let events = event_store
+        .get_by_execution(&execution_id)
+        .await
+        .expect("Failed to load events");
+
+    // We expect 4 events
+    assert_eq!(
+        events.len(),
+        4,
+        "Expected 4 persisted events, found {}",
+        events.len()
+    );
+
+    // Verify Event 1: ToolCallStart
+    let event1 = &events[0].event;
+    assert!(
+        matches!(event1.event_type, ExecutionEventType::ToolCallStart),
+        "Event 1 should be ToolCallStart"
+    );
+    let p1 = event1.payload.as_ref().expect("Payload missing");
+    assert_eq!(p1["tool_call_id"], tool_call_id);
+    assert_eq!(p1["tool_name"], tool_name);
+    assert_eq!(p1["input"], input_payload);
+
+    // Verify Event 2: ToolCallEnd
+    let event2 = &events[1].event;
+    assert!(
+        matches!(event2.event_type, ExecutionEventType::ToolCallEnd),
+        "Event 2 should be ToolCallEnd"
+    );
+    let p2 = event2.payload.as_ref().expect("Payload missing");
+    assert_eq!(p2["tool_call_id"], tool_call_id);
+    assert_eq!(p2["output"], output_payload);
+
+    // Verify Event 3: CheckpointSaved
+    let event3 = &events[2].event;
+    assert!(
+        matches!(event3.event_type, ExecutionEventType::CheckpointSaved),
+        "Event 3 should be CheckpointSaved"
+    );
+    let p3 = event3.payload.as_ref().expect("Payload missing");
+    assert_eq!(p3["checkpoint_id"], checkpoint_id);
+    assert_eq!(p3["state_hash"], "hash_abc123");
+
+    // Verify Event 4: GoalEvaluated
+    let event4 = &events[3].event;
+    assert!(
+        matches!(event4.event_type, ExecutionEventType::GoalEvaluated),
+        "Event 4 should be GoalEvaluated"
+    );
+    let p4 = event4.payload.as_ref().expect("Payload missing");
+    assert_eq!(p4["goal_id"], "goal_primary");
+    assert_eq!(p4["status"], "met");
+    assert_eq!(p4["score"], 1.0);
+
+    println!("✅ All agentic loop events persisted correctly!");
+}