enya-agent 0.1.0

package/crates/enact-core/src/telemetry/spans.rs

@@ -0,0 +1,245 @@
+//! Telemetry Spans - OpenTelemetry span helpers for execution tracing
+//!
+//! This module provides utilities for creating and managing OpenTelemetry spans
+//! that correlate with ExecutionId and StepId for distributed tracing.
+//!
+//! ## Span Hierarchy
+//! ```text
+//! Execution Span (trace_id = TraceContext.trace_id)
+//!   ├── Step Span (span_id = unique per step)
+//!   │     └── Tool Span
+//!   ├── Step Span
+//!   │     └── LLM Span
+//!   └── Child Execution Span (sub-agent)
+//!         └── Step Span...
+//! ```
+//!
+//! @see docs/TECHNICAL/01-EXECUTION-TELEMETRY.md
+
+use crate::kernel::{ExecutionId, StepId, StepType};
+use crate::runner::TraceContext;
+
+/// Span attributes for execution-level spans
+pub struct ExecutionSpanAttributes {
+    /// Execution ID
+    pub execution_id: String,
+    /// Parent ID (if nested execution)
+    pub parent_id: Option<String>,
+    /// Parent type
+    pub parent_type: Option<String>,
+    /// Tenant ID
+    pub tenant_id: Option<String>,
+    /// User ID
+    pub user_id: Option<String>,
+}
+
+impl ExecutionSpanAttributes {
+    /// Create from an ExecutionId
+    pub fn new(execution_id: &ExecutionId) -> Self {
+        Self {
+            execution_id: execution_id.as_str().to_string(),
+            parent_id: None,
+            parent_type: None,
+            tenant_id: None,
+            user_id: None,
+        }
+    }
+
+    /// Add parent context
+    pub fn with_parent(mut self, parent_id: impl Into<String>, parent_type: impl Into<String>) -> Self {
+        self.parent_id = Some(parent_id.into());
+        self.parent_type = Some(parent_type.into());
+        self
+    }
+
+    /// Add tenant context
+    pub fn with_tenant(mut self, tenant_id: impl Into<String>) -> Self {
+        self.tenant_id = Some(tenant_id.into());
+        self
+    }
+
+    /// Add user context
+    pub fn with_user(mut self, user_id: impl Into<String>) -> Self {
+        self.user_id = Some(user_id.into());
+        self
+    }
+
+    /// Convert to a map of attributes for OpenTelemetry
+    pub fn to_attributes(&self) -> Vec<(&'static str, String)> {
+        let mut attrs = vec![("enact.execution_id", self.execution_id.clone())];
+
+        if let Some(ref parent_id) = self.parent_id {
+            attrs.push(("enact.parent_id", parent_id.clone()));
+        }
+        if let Some(ref parent_type) = self.parent_type {
+            attrs.push(("enact.parent_type", parent_type.clone()));
+        }
+        if let Some(ref tenant_id) = self.tenant_id {
+            attrs.push(("enact.tenant_id", tenant_id.clone()));
+        }
+        if let Some(ref user_id) = self.user_id {
+            attrs.push(("enact.user_id", user_id.clone()));
+        }
+
+        attrs
+    }
+}
+
+/// Span attributes for step-level spans
+pub struct StepSpanAttributes {
+    /// Execution ID
+    pub execution_id: String,
+    /// Step ID
+    pub step_id: String,
+    /// Step type
+    pub step_type: String,
+    /// Step name
+    pub name: String,
+}
+
+impl StepSpanAttributes {
+    /// Create from ExecutionId and StepId
+    pub fn new(
+        execution_id: &ExecutionId,
+        step_id: &StepId,
+        step_type: StepType,
+        name: impl Into<String>,
+    ) -> Self {
+        Self {
+            execution_id: execution_id.as_str().to_string(),
+            step_id: step_id.as_str().to_string(),
+            step_type: step_type.to_string(),
+            name: name.into(),
+        }
+    }
+
+    /// Convert to a map of attributes for OpenTelemetry
+    pub fn to_attributes(&self) -> Vec<(&'static str, String)> {
+        vec![
+            ("enact.execution_id", self.execution_id.clone()),
+            ("enact.step_id", self.step_id.clone()),
+            ("enact.step_type", self.step_type.clone()),
+            ("enact.step_name", self.name.clone()),
+        ]
+    }
+}
+
+/// Span attributes for tool calls
+pub struct ToolSpanAttributes {
+    /// Execution ID
+    pub execution_id: String,
+    /// Step ID
+    pub step_id: String,
+    /// Tool name
+    pub tool_name: String,
+}
+
+impl ToolSpanAttributes {
+    /// Create from ExecutionId, StepId, and tool name
+    pub fn new(
+        execution_id: &ExecutionId,
+        step_id: &StepId,
+        tool_name: impl Into<String>,
+    ) -> Self {
+        Self {
+            execution_id: execution_id.as_str().to_string(),
+            step_id: step_id.as_str().to_string(),
+            tool_name: tool_name.into(),
+        }
+    }
+
+    /// Convert to a map of attributes for OpenTelemetry
+    pub fn to_attributes(&self) -> Vec<(&'static str, String)> {
+        vec![
+            ("enact.execution_id", self.execution_id.clone()),
+            ("enact.step_id", self.step_id.clone()),
+            ("enact.tool_name", self.tool_name.clone()),
+        ]
+    }
+}
+
+/// Span attributes for LLM calls
+pub struct LlmSpanAttributes {
+    /// Execution ID
+    pub execution_id: String,
+    /// Step ID
+    pub step_id: String,
+    /// Model provider
+    pub provider: String,
+    /// Model name
+    pub model: String,
+    /// Input tokens (optional)
+    pub input_tokens: Option<u32>,
+    /// Output tokens (optional)
+    pub output_tokens: Option<u32>,
+}
+
+impl LlmSpanAttributes {
+    /// Create from ExecutionId, StepId, provider, and model
+    pub fn new(
+        execution_id: &ExecutionId,
+        step_id: &StepId,
+        provider: impl Into<String>,
+        model: impl Into<String>,
+    ) -> Self {
+        Self {
+            execution_id: execution_id.as_str().to_string(),
+            step_id: step_id.as_str().to_string(),
+            provider: provider.into(),
+            model: model.into(),
+            input_tokens: None,
+            output_tokens: None,
+        }
+    }
+
+    /// Add token counts
+    pub fn with_tokens(mut self, input: u32, output: u32) -> Self {
+        self.input_tokens = Some(input);
+        self.output_tokens = Some(output);
+        self
+    }
+
+    /// Convert to a map of attributes for OpenTelemetry
+    pub fn to_attributes(&self) -> Vec<(&'static str, String)> {
+        let mut attrs = vec![
+            ("enact.execution_id", self.execution_id.clone()),
+            ("enact.step_id", self.step_id.clone()),
+            ("gen_ai.system", self.provider.clone()),
+            ("gen_ai.request.model", self.model.clone()),
+        ];
+
+        if let Some(tokens) = self.input_tokens {
+            attrs.push(("gen_ai.usage.input_tokens", tokens.to_string()));
+        }
+        if let Some(tokens) = self.output_tokens {
+            attrs.push(("gen_ai.usage.output_tokens", tokens.to_string()));
+        }
+
+        attrs
+    }
+}
+
+/// Create span name for an execution
+pub fn execution_span_name(execution_id: &ExecutionId) -> String {
+    format!("execution:{}", execution_id.as_str())
+}
+
+/// Create span name for a step
+pub fn step_span_name(step_type: &StepType, name: &str) -> String {
+    format!("step:{}:{}", step_type, name)
+}
+
+/// Create span name for a tool call
+pub fn tool_span_name(tool_name: &str) -> String {
+    format!("tool:{}", tool_name)
+}
+
+/// Create span name for an LLM call
+pub fn llm_span_name(provider: &str, model: &str) -> String {
+    format!("llm:{}:{}", provider, model)
+}
+
+/// Extract trace context from a RuntimeContext trace
+pub fn extract_trace_context(trace: &TraceContext) -> (String, String) {
+    (trace.trace_id.clone(), trace.span_id.clone())
+}

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

@@ -0,0 +1,177 @@
+//! AgentTool - wraps a Callable as a Tool (agent-as-tool pattern)
+//!
+//! ⚠️ **SECURITY WARNING: PRIVILEGED ADAPTER**
+//!
+//! `AgentTool` is **NOT** a general-purpose adapter. It is a **privileged** component
+//! that must only be constructed by **trusted runtime components**.
+//!
+//! ## Why This Is Dangerous
+//!
+//! `AgentTool` allows exposing a `Callable` (which may be an agent, graph, or other
+//! complex execution unit) as a `Tool`. This creates a powerful capability:
+//!
+//! - **Callable** = execution (agents, graphs, complex workflows)
+//! - **Tool** = capability (side-effect functions for LLMs to invoke)
+//!
+//! Wrapping a Callable as a Tool means an LLM can invoke agents/graphs as tools,
+//! creating recursive agent execution patterns. This is powerful but **dangerous**
+//! if exposed to untrusted contexts.
+//!
+//! ## Security Invariant
+//!
+//! **AgentTool may only be constructed by trusted runtime components.**
+//!
+//! This means:
+//! - ✅ **Allowed**: Kernel, runner, or other trusted execution components
+//! - ❌ **Forbidden**: User-provided code, untrusted plugins, dynamic tool registries
+//!
+//! ## Why This Matters
+//!
+//! If `AgentTool` is exposed to untrusted contexts:
+//! - Malicious users could expose arbitrary agents as tools
+//! - Untrusted code could create recursive agent loops
+//! - Policy boundaries could be bypassed
+//! - Quota limits could be circumvented
+//!
+//! ## Usage Pattern
+//!
+//! ```rust,ignore
+//! // ✅ CORRECT: Created by trusted runtime component
+//! // In kernel or runner, with proper policy checks
+//! let agent = Arc::new(LlmCallable::new(...));
+//! let agent_tool = AgentTool::new(agent, "agent_name", "Agent description");
+//!
+//! // ❌ WRONG: Created from user input or untrusted source
+//! // let agent_tool = AgentTool::from_user_input(...); // DON'T DO THIS!
+//! ```
+//!
+//! ## Policy Enforcement
+//!
+//! Even when created by trusted components, `AgentTool` instances must still:
+//! - Go through `ToolExecutor` for execution (policy enforcement)
+//! - Respect `ToolPolicy` trust levels
+//! - Be subject to quota limits
+//! - Follow the same security boundaries as any other tool
+//!
+//! The privilege is in **construction**, not in **execution**.
+
+use super::Tool;
+use crate::callable::DynCallable;
+use async_trait::async_trait;
+use serde_json::{json, Value};
+
+/// AgentTool - wraps a Callable as a Tool
+///
+/// ⚠️ **PRIVILEGED**: This adapter may only be constructed by trusted runtime components.
+/// See module-level documentation for security implications.
+///
+/// This allows exposing agents, graphs, or other Callables as tools that can be
+/// invoked by LLMs. The Callable's `run()` method is invoked with the tool's
+/// JSON arguments serialized as a string.
+pub struct AgentTool {
+    /// The underlying callable being wrapped
+    callable: DynCallable,
+    /// Tool name (may differ from callable name)
+    name: String,
+    /// Tool description
+    description: String,
+    /// JSON schema for tool parameters
+    parameters: Value,
+}
+
+impl AgentTool {
+    /// Create a new AgentTool
+    ///
+    /// ⚠️ **SECURITY**: This constructor is privileged. Only trusted runtime components
+    /// (kernel, runner) should create `AgentTool` instances.
+    ///
+    /// # Arguments
+    ///
+    /// * `callable` - The callable to wrap (agent, graph, etc.)
+    /// * `name` - Tool name (for LLM tool schema)
+    /// * `description` - Tool description (for LLM tool schema)
+    /// * `parameters` - JSON schema for tool parameters (defaults to empty object)
+    ///
+    /// # Example
+    ///
+    /// ```rust,ignore
+    /// // ✅ CORRECT: Created by trusted runtime
+    /// let agent = Arc::new(LlmCallable::new(...));
+    /// let tool = AgentTool::new(
+    ///     agent,
+    ///     "sub_agent",
+    ///     "A sub-agent that handles specific tasks",
+    ///     json!({
+    ///         "type": "object",
+    ///         "properties": {
+    ///             "task": {"type": "string", "description": "Task description"}
+    ///         },
+    ///         "required": ["task"]
+    ///     })
+    /// );
+    /// ```
+    pub fn new(
+        callable: DynCallable,
+        name: impl Into<String>,
+        description: impl Into<String>,
+        parameters: Value,
+    ) -> Self {
+        Self {
+            callable,
+            name: name.into(),
+            description: description.into(),
+            parameters,
+        }
+    }
+
+    /// Create a new AgentTool with default empty parameters schema
+    ///
+    /// ⚠️ **SECURITY**: Same privilege requirements as `new()`.
+    pub fn simple(
+        callable: DynCallable,
+        name: impl Into<String>,
+        description: impl Into<String>,
+    ) -> Self {
+        Self::new(
+            callable,
+            name,
+            description,
+            json!({
+                "type": "object",
+                "properties": {},
+                "required": []
+            }),
+        )
+    }
+}
+
+#[async_trait]
+impl Tool for AgentTool {
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn description(&self) -> &str {
+        &self.description
+    }
+
+    fn parameters_schema(&self) -> Value {
+        self.parameters.clone()
+    }
+
+    async fn execute(&self, args: Value) -> anyhow::Result<Value> {
+        // Serialize JSON arguments to string for Callable::run()
+        let input = serde_json::to_string(&args)?;
+        
+        // Execute the underlying callable
+        let output = self.callable.run(&input).await?;
+        
+        // Parse output as JSON (callable returns string, but we expect JSON)
+        // If parsing fails, wrap the string in a JSON object
+        match serde_json::from_str::<Value>(&output) {
+            Ok(json) => Ok(json),
+            Err(_) => Ok(json!({ "result": output })),
+        }
+    }
+}
+

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

@@ -0,0 +1,247 @@
+//! Cost tracking tool for monitoring API usage
+
+use crate::tool::Tool;
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::SystemTime;
+
+/// Cost tracking for LLM API calls
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct CostMetrics {
+    pub total_requests: u64,
+    pub total_input_tokens: u64,
+    pub total_output_tokens: u64,
+    pub total_cost_usd: f64,
+    pub requests_by_model: HashMap<String, u64>,
+    pub cost_by_model: HashMap<String, f64>,
+}
+
+/// Cost tracker with thread-safe counters
+pub struct CostTracker {
+    metrics: Arc<std::sync::Mutex<CostMetrics>>,
+    model_pricing: HashMap<String, ModelPricing>,
+}
+
+#[derive(Debug, Clone)]
+struct ModelPricing {
+    input_price_per_1k: f64,  // USD per 1K input tokens
+    output_price_per_1k: f64, // USD per 1K output tokens
+}
+
+impl CostTracker {
+    pub fn new() -> Self {
+        let mut model_pricing = HashMap::new();
+        
+        // OpenAI pricing (as of 2024)
+        model_pricing.insert(
+            "gpt-4o".to_string(),
+            ModelPricing {
+                input_price_per_1k: 0.0025,
+                output_price_per_1k: 0.01,
+            },
+        );
+        model_pricing.insert(
+            "gpt-4o-mini".to_string(),
+            ModelPricing {
+                input_price_per_1k: 0.00015,
+                output_price_per_1k: 0.0006,
+            },
+        );
+        model_pricing.insert(
+            "gpt-4-turbo".to_string(),
+            ModelPricing {
+                input_price_per_1k: 0.01,
+                output_price_per_1k: 0.03,
+            },
+        );
+        
+        // Anthropic pricing
+        model_pricing.insert(
+            "claude-3-opus".to_string(),
+            ModelPricing {
+                input_price_per_1k: 0.015,
+                output_price_per_1k: 0.075,
+            },
+        );
+        model_pricing.insert(
+            "claude-3-sonnet".to_string(),
+            ModelPricing {
+                input_price_per_1k: 0.003,
+                output_price_per_1k: 0.015,
+            },
+        );
+        
+        // Gemini pricing
+        model_pricing.insert(
+            "gemini-pro".to_string(),
+            ModelPricing {
+                input_price_per_1k: 0.0005,
+                output_price_per_1k: 0.0015,
+            },
+        );
+
+        Self {
+            metrics: Arc::new(std::sync::Mutex::new(CostMetrics::default())),
+            model_pricing,
+        }
+    }
+
+    pub fn track_request(
+        &self,
+        model: &str,
+        input_tokens: u64,
+        output_tokens: u64,
+    ) {
+        let mut metrics = self.metrics.lock().unwrap();
+        
+        metrics.total_requests += 1;
+        metrics.total_input_tokens += input_tokens;
+        metrics.total_output_tokens += output_tokens;
+        
+        // Track by model
+        *metrics.requests_by_model.entry(model.to_string()).or_insert(0) += 1;
+        
+        // Calculate cost
+        let cost = if let Some(pricing) = self.model_pricing.get(model) {
+            let input_cost = (input_tokens as f64 / 1000.0) * pricing.input_price_per_1k;
+            let output_cost = (output_tokens as f64 / 1000.0) * pricing.output_price_per_1k;
+            input_cost + output_cost
+        } else {
+            // Default pricing if model unknown
+            let input_cost = (input_tokens as f64 / 1000.0) * 0.001;
+            let output_cost = (output_tokens as f64 / 1000.0) * 0.002;
+            input_cost + output_cost
+        };
+        
+        metrics.total_cost_usd += cost;
+        *metrics.cost_by_model.entry(model.to_string()).or_insert(0.0) += cost;
+    }
+
+    pub fn get_metrics(&self) -> CostMetrics {
+        self.metrics.lock().unwrap().clone()
+    }
+
+    pub fn reset(&self) {
+        let mut metrics = self.metrics.lock().unwrap();
+        *metrics = CostMetrics::default();
+    }
+}
+
+impl Default for CostTracker {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Cost tool for querying cost metrics
+pub struct CostTool {
+    tracker: Arc<CostTracker>,
+}
+
+impl CostTool {
+    pub fn new(tracker: Arc<CostTracker>) -> Self {
+        Self { tracker }
+    }
+}
+
+#[async_trait]
+impl Tool for CostTool {
+    fn name(&self) -> &str {
+        "cost"
+    }
+
+    fn description(&self) -> &str {
+        "Get cost metrics and usage statistics for LLM API calls"
+    }
+
+    fn parameters_schema(&self) -> serde_json::Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["get", "reset"],
+                    "description": "Action to perform",
+                    "default": "get"
+                }
+            }
+        })
+    }
+
+    fn requires_network(&self) -> bool {
+        false
+    }
+
+    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<serde_json::Value> {
+        let action = args
+            .get("action")
+            .and_then(|v| v.as_str())
+            .unwrap_or("get");
+
+        match action {
+            "reset" => {
+                self.tracker.reset();
+                Ok(json!({
+                    "success": true,
+                    "message": "Cost metrics reset"
+                }))
+            }
+            _ => {
+                let metrics = self.tracker.get_metrics();
+                Ok(json!({
+                    "success": true,
+                    "metrics": metrics
+                }))
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_cost_tracker() {
+        let tracker = CostTracker::new();
+        
+        tracker.track_request("gpt-4o-mini", 1000, 500);
+        tracker.track_request("gpt-4o-mini", 2000, 1000);
+        
+        let metrics = tracker.get_metrics();
+        assert_eq!(metrics.total_requests, 2);
+        assert_eq!(metrics.total_input_tokens, 3000);
+        assert_eq!(metrics.total_output_tokens, 1500);
+        assert!(metrics.total_cost_usd > 0.0);
+        
+        // Check model breakdown
+        assert_eq!(metrics.requests_by_model.get("gpt-4o-mini"), Some(&2));
+    }
+
+    #[test]
+    fn test_cost_tracker_reset() {
+        let tracker = CostTracker::new();
+        tracker.track_request("gpt-4o-mini", 1000, 500);
+        
+        tracker.reset();
+        let metrics = tracker.get_metrics();
+        assert_eq!(metrics.total_requests, 0);
+        assert_eq!(metrics.total_cost_usd, 0.0);
+    }
+
+    #[tokio::test]
+    async fn test_cost_tool_get() {
+        let tracker = Arc::new(CostTracker::new());
+        tracker.track_request("gpt-4o-mini", 1000, 500);
+        
+        let tool = CostTool::new(tracker);
+        let result = tool.execute(json!({"action": "get"})).await.unwrap();
+        
+        assert_eq!(result["success"], true);
+        assert!(result["metrics"]["total_requests"].as_u64().unwrap() > 0);
+    }
+}