enya-agent 0.1.0

package/crates/enact-core/src/runner/execution_runner.rs

@@ -0,0 +1,476 @@
+//! Runner - executes callables and graphs with flow features
+
+use crate::callable::Callable;
+use crate::graph::{Checkpoint, CheckpointStore, CompiledGraph, NodeState};
+use crate::kernel::{ExecutionError, ExecutionId, StepId, StepType};
+use crate::streaming::{EventEmitter, StreamEvent};
+use std::sync::Arc;
+use std::time::Instant;
+use tokio_util::sync::CancellationToken;
+
+/// Runner - executes agents/graphs with abort, pause, and event streaming
+pub struct Runner<S: CheckpointStore> {
+    execution_id: ExecutionId,
+    cancellation_token: CancellationToken,
+    checkpoint_store: Arc<S>,
+    emitter: EventEmitter,
+    paused: std::sync::atomic::AtomicBool,
+    start_time: Option<Instant>,
+}
+
+impl<S: CheckpointStore> Runner<S> {
+    /// Create a new runner
+    pub fn new(checkpoint_store: Arc<S>) -> Self {
+        Self {
+            execution_id: ExecutionId::new(),
+            cancellation_token: CancellationToken::new(),
+            checkpoint_store,
+            emitter: EventEmitter::new(),
+            paused: std::sync::atomic::AtomicBool::new(false),
+            start_time: None,
+        }
+    }
+
+    /// Get the execution ID
+    pub fn execution_id(&self) -> &ExecutionId {
+        &self.execution_id
+    }
+
+    /// Backward compatibility alias
+    #[deprecated(note = "Use execution_id() instead")]
+    pub fn run_id(&self) -> &ExecutionId {
+        &self.execution_id
+    }
+
+    /// Get the event emitter
+    pub fn emitter(&self) -> &EventEmitter {
+        &self.emitter
+    }
+
+    /// Cancel the run (abort signal)
+    pub fn cancel(&self) {
+        self.cancellation_token.cancel();
+        self.emitter.emit(StreamEvent::execution_cancelled(
+            &self.execution_id,
+            "Run cancelled by user",
+        ));
+    }
+
+    /// Check if cancelled
+    pub fn is_cancelled(&self) -> bool {
+        self.cancellation_token.is_cancelled()
+    }
+
+    /// Pause the run
+    pub async fn pause(&self) -> anyhow::Result<()> {
+        self.paused.store(true, std::sync::atomic::Ordering::SeqCst);
+        self.emitter.emit(StreamEvent::execution_paused(
+            &self.execution_id,
+            "Paused by user",
+        ));
+        Ok(())
+    }
+
+    /// Resume the run
+    pub fn resume(&self) {
+        self.paused.store(false, std::sync::atomic::Ordering::SeqCst);
+        self.emitter.emit(StreamEvent::execution_resumed(&self.execution_id));
+    }
+
+    /// Check if paused
+    pub fn is_paused(&self) -> bool {
+        self.paused.load(std::sync::atomic::Ordering::SeqCst)
+    }
+
+    /// Save checkpoint
+    pub async fn save_checkpoint(&self, state: NodeState, node: Option<&str>) -> anyhow::Result<Checkpoint> {
+        let mut checkpoint = Checkpoint::new(self.execution_id.clone())
+            .with_state(state.data);
+
+        if let Some(n) = node {
+            checkpoint = checkpoint.with_node(n);
+        }
+
+        self.checkpoint_store.save(checkpoint.clone()).await?;
+        Ok(checkpoint)
+    }
+
+    /// Load latest checkpoint
+    pub async fn load_checkpoint(&self) -> anyhow::Result<Option<Checkpoint>> {
+        self.checkpoint_store.load_latest(self.execution_id.as_str()).await
+    }
+
+    /// Run a callable with event streaming
+    pub async fn run_callable<A: Callable + ?Sized>(&mut self, callable: &A, input: &str) -> anyhow::Result<String> {
+        self.start_time = Some(Instant::now());
+        self.emitter.emit(StreamEvent::execution_start(&self.execution_id));
+
+        // Check for cancellation before running
+        if self.is_cancelled() {
+            anyhow::bail!("Run cancelled");
+        }
+
+        let result = callable.run(input).await;
+        let duration_ms = self.start_time.map(|t| t.elapsed().as_millis() as u64).unwrap_or(0);
+
+        match &result {
+            Ok(output) => {
+                self.emitter.emit(StreamEvent::execution_end(
+                    &self.execution_id,
+                    Some(output.clone()),
+                    duration_ms,
+                ));
+            }
+            Err(e) => {
+                let error = ExecutionError::kernel_internal(e.to_string());
+                self.emitter.emit(StreamEvent::execution_failed(
+                    &self.execution_id,
+                    error,
+                ));
+            }
+        }
+
+        result
+    }
+
+    /// Run a compiled graph with event streaming
+    pub async fn run_graph(&mut self, graph: &CompiledGraph, input: &str) -> anyhow::Result<NodeState> {
+        self.start_time = Some(Instant::now());
+        self.emitter.emit(StreamEvent::execution_start(&self.execution_id));
+
+        let mut state = NodeState::from_str(input);
+        let mut current_node = graph.entry_point().to_string();
+
+        loop {
+            // Check for cancellation
+            if self.is_cancelled() {
+                anyhow::bail!("Run cancelled");
+            }
+
+            // Check for pause - wait until resumed
+            while self.is_paused() {
+                tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
+                if self.is_cancelled() {
+                    anyhow::bail!("Run cancelled while paused");
+                }
+            }
+
+            // Get the node
+            let node = graph
+                .get_node(&current_node)
+                .ok_or_else(|| anyhow::anyhow!("Node '{}' not found", current_node))?;
+
+            // Create step ID for this node execution
+            let step_id = StepId::new();
+            let step_start = Instant::now();
+
+            // Emit step started
+            self.emitter.emit(StreamEvent::step_start(
+                &self.execution_id,
+                &step_id,
+                StepType::FunctionNode, // Graph nodes are function nodes by default
+                current_node.clone(),
+            ));
+
+            // Execute node
+            state = node.execute(state).await?;
+
+            // Emit step completed
+            let step_duration = step_start.elapsed().as_millis() as u64;
+            self.emitter.emit(StreamEvent::step_end(
+                &self.execution_id,
+                &step_id,
+                Some(state.as_str().unwrap_or_default().to_string()),
+                step_duration,
+            ));
+
+            // Get next nodes
+            let output = state.as_str().unwrap_or_default();
+            let next = graph.get_next(&current_node, output);
+
+            if next.is_empty() {
+                break;
+            }
+
+            match &next[0] {
+                crate::graph::EdgeTarget::End => break,
+                crate::graph::EdgeTarget::Node(n) => {
+                    current_node = n.clone();
+                }
+            }
+        }
+
+        let duration_ms = self.start_time.map(|t| t.elapsed().as_millis() as u64).unwrap_or(0);
+        self.emitter.emit(StreamEvent::execution_end(
+            &self.execution_id,
+            Some(state.as_str().unwrap_or_default().to_string()),
+            duration_ms,
+        ));
+
+        Ok(state)
+    }
+}
+
+/// Runner with in-memory checkpoint store (default)
+pub type DefaultRunner = Runner<crate::graph::InMemoryCheckpointStore>;
+
+impl DefaultRunner {
+    /// Create a new runner with in-memory checkpoint store
+    pub fn default_new() -> Self {
+        Self::new(Arc::new(crate::graph::InMemoryCheckpointStore::new()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use async_trait::async_trait;
+    use crate::graph::InMemoryCheckpointStore;
+
+    /// Mock callable for testing
+    struct MockCallable {
+        name: String,
+        response: Result<String, String>,
+        delay_ms: Option<u64>,
+    }
+
+    impl MockCallable {
+        fn success(name: &str, response: &str) -> Self {
+            Self {
+                name: name.to_string(),
+                response: Ok(response.to_string()),
+                delay_ms: None,
+            }
+        }
+
+        fn failing(name: &str, error: &str) -> Self {
+            Self {
+                name: name.to_string(),
+                response: Err(error.to_string()),
+                delay_ms: None,
+            }
+        }
+    }
+
+    #[async_trait]
+    impl Callable for MockCallable {
+        fn name(&self) -> &str {
+            &self.name
+        }
+
+        async fn run(&self, input: &str) -> anyhow::Result<String> {
+            if let Some(delay) = self.delay_ms {
+                tokio::time::sleep(tokio::time::Duration::from_millis(delay)).await;
+            }
+            match &self.response {
+                Ok(r) => Ok(format!("{}:{}", r, input)),
+                Err(e) => anyhow::bail!("{}", e),
+            }
+        }
+    }
+
+    // ============ Construction Tests ============
+
+    #[test]
+    fn test_runner_new() {
+        let store = Arc::new(InMemoryCheckpointStore::new());
+        let runner = Runner::new(store);
+
+        // Should have a valid execution ID
+        assert!(!runner.execution_id().as_str().is_empty());
+        // Should not be cancelled initially
+        assert!(!runner.is_cancelled());
+        // Should not be paused initially
+        assert!(!runner.is_paused());
+    }
+
+    #[test]
+    fn test_default_runner_new() {
+        let runner = DefaultRunner::default_new();
+        assert!(!runner.execution_id().as_str().is_empty());
+    }
+
+    #[test]
+    fn test_runner_execution_id_unique() {
+        let store = Arc::new(InMemoryCheckpointStore::new());
+        let runner1 = Runner::new(store.clone());
+        let runner2 = Runner::new(store);
+
+        // Each runner should have unique execution ID
+        assert_ne!(runner1.execution_id().as_str(), runner2.execution_id().as_str());
+    }
+
+    // ============ Cancellation Tests ============
+
+    #[test]
+    fn test_runner_cancel() {
+        let runner = DefaultRunner::default_new();
+
+        assert!(!runner.is_cancelled());
+        runner.cancel();
+        assert!(runner.is_cancelled());
+    }
+
+    #[tokio::test]
+    async fn test_runner_callable_checks_cancellation_before_run() {
+        let mut runner = DefaultRunner::default_new();
+        let callable = MockCallable::success("test", "response");
+
+        // Cancel before running
+        runner.cancel();
+
+        let result = runner.run_callable(&callable, "input").await;
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("cancelled"));
+    }
+
+    // ============ Pause/Resume Tests ============
+
+    #[tokio::test]
+    async fn test_runner_pause_resume() {
+        let runner = DefaultRunner::default_new();
+
+        assert!(!runner.is_paused());
+
+        runner.pause().await.unwrap();
+        assert!(runner.is_paused());
+
+        runner.resume();
+        assert!(!runner.is_paused());
+    }
+
+    // ============ Run Callable Tests ============
+
+    #[tokio::test]
+    async fn test_run_callable_success() {
+        let mut runner = DefaultRunner::default_new();
+        let callable = MockCallable::success("test", "hello");
+
+        let result = runner.run_callable(&callable, "world").await;
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap(), "hello:world");
+    }
+
+    #[tokio::test]
+    async fn test_run_callable_failure() {
+        let mut runner = DefaultRunner::default_new();
+        let callable = MockCallable::failing("test", "Something went wrong");
+
+        let result = runner.run_callable(&callable, "input").await;
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("Something went wrong"));
+    }
+
+    #[tokio::test]
+    async fn test_run_callable_emits_events() {
+        let mut runner = DefaultRunner::default_new();
+        let callable = MockCallable::success("test", "response");
+
+        runner.run_callable(&callable, "input").await.unwrap();
+
+        // Drain and check collected events
+        let events = runner.emitter().drain();
+
+        // Should have execution start and end events
+        assert!(events.len() >= 2);
+
+        // First event should be execution start
+        let first = &events[0];
+        assert!(matches!(first, StreamEvent::ExecutionStart { .. }));
+
+        // Last event should be execution end
+        let last = &events[events.len() - 1];
+        assert!(matches!(last, StreamEvent::ExecutionEnd { .. }));
+    }
+
+    #[tokio::test]
+    async fn test_run_callable_failure_emits_failed_event() {
+        let mut runner = DefaultRunner::default_new();
+        let callable = MockCallable::failing("test", "error message");
+
+        let _ = runner.run_callable(&callable, "input").await;
+
+        // Drain and check collected events
+        let events = runner.emitter().drain();
+
+        // Should have execution start and failed events
+        assert!(events.len() >= 2);
+
+        // Last event should be execution failed
+        let last = &events[events.len() - 1];
+        assert!(matches!(last, StreamEvent::ExecutionFailed { .. }));
+    }
+
+    // ============ Checkpoint Tests ============
+
+    #[tokio::test]
+    async fn test_runner_save_and_load_checkpoint() {
+        let runner = DefaultRunner::default_new();
+
+        // Save a checkpoint
+        let state = NodeState::from_str("test state data");
+        let checkpoint = runner.save_checkpoint(state, Some("node1")).await.unwrap();
+
+        assert_eq!(checkpoint.current_node.as_ref().unwrap(), "node1");
+
+        // Load the checkpoint
+        let loaded = runner.load_checkpoint().await.unwrap();
+        assert!(loaded.is_some());
+
+        let loaded = loaded.unwrap();
+        assert_eq!(loaded.state, serde_json::Value::String("test state data".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_runner_checkpoint_without_node() {
+        let runner = DefaultRunner::default_new();
+
+        let state = NodeState::from_str("some data");
+        let checkpoint = runner.save_checkpoint(state, None).await.unwrap();
+
+        assert!(checkpoint.current_node.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_runner_load_checkpoint_no_data() {
+        let runner = DefaultRunner::default_new();
+
+        // Without saving, load should return None
+        let loaded = runner.load_checkpoint().await.unwrap();
+        assert!(loaded.is_none());
+    }
+
+    // ============ Emitter Tests ============
+
+    #[test]
+    fn test_runner_emitter_access() {
+        let runner = DefaultRunner::default_new();
+        let emitter = runner.emitter();
+
+        // Should be able to emit and drain events
+        emitter.emit(StreamEvent::execution_start(runner.execution_id()));
+        let events = emitter.drain();
+        assert_eq!(events.len(), 1);
+    }
+
+    #[test]
+    fn test_emitter_mode() {
+        use crate::streaming::StreamMode;
+
+        let runner = DefaultRunner::default_new();
+        let emitter = runner.emitter();
+
+        // Default mode should be Full
+        assert_eq!(emitter.mode(), StreamMode::Full);
+    }
+
+    // ============ Deprecated API Tests ============
+
+    #[test]
+    #[allow(deprecated)]
+    fn test_runner_run_id_deprecated() {
+        let runner = DefaultRunner::default_new();
+        // run_id should return same as execution_id
+        assert_eq!(runner.run_id().as_str(), runner.execution_id().as_str());
+    }
+}

package/crates/enact-core/src/runner/loop.rs

@@ -0,0 +1,117 @@
+//! Agentic Loop implementation
+//!
+//! The core loop that drives long-running executions.
+//! It handles the "Discovery -> Execute -> Repeat" cycle.
+
+use crate::callable::{Callable, DynCallable};
+use crate::graph::CheckpointStore;
+use crate::policy::LongRunningExecutionPolicy;
+use crate::runner::Runner;
+use crate::streaming::StreamEvent;
+use std::time::{Duration, Instant};
+
+/// The agentic loop driver
+#[allow(dead_code)]
+pub struct AgenticLoop;
+
+#[allow(dead_code)]
+impl AgenticLoop {
+    /// Run the agentic loop for a callable
+    pub async fn run<S: CheckpointStore>(
+        runner: &mut Runner<S>,
+        callable: DynCallable,
+        input: String,
+        policy: LongRunningExecutionPolicy,
+    ) -> anyhow::Result<String> {
+        // Initial setup
+        let start_time = Instant::now();
+        let mut steps_executed = 0;
+        let mut _tokens_used = 0;
+        let mut history: Vec<String> = Vec::new();
+
+        // Push initial input
+        history.push(format!("User: {}", input));
+
+        // Initial execution
+        let current_input = input.clone();
+        let current_callable = callable;
+
+        // Main Loop
+        loop {
+            // 1. Check Limits (simplified for now, full enforcement in kernel/enforcement.rs)
+            if let Some(max_steps) = policy.max_discovered_steps {
+                if steps_executed > max_steps {
+                    runner.emitter().emit(StreamEvent::execution_failed(
+                        runner.execution_id(),
+                        crate::kernel::ExecutionError::quota_exceeded("Max steps exceeded"),
+                    ));
+                    anyhow::bail!("Max steps exceeded");
+                }
+            }
+
+            if let Some(timeout) = policy.idle_timeout_seconds {
+                if start_time.elapsed() > Duration::from_secs(timeout) {
+                    runner.emitter().emit(StreamEvent::execution_failed(
+                        runner.execution_id(),
+                        crate::kernel::ExecutionError::timeout(format!(
+                            "Idle timeout after {}s",
+                            timeout
+                        )),
+                    ));
+                    anyhow::bail!("Idle timeout");
+                }
+            }
+
+            // 2. Execute Step
+            let result = runner
+                .run_callable(current_callable.as_ref() as &dyn Callable, &current_input)
+                .await;
+
+            match result {
+                Ok(output) => {
+                    history.push(format!("Assistant: {}", output));
+                    steps_executed += 1;
+
+                    // 3. Check for Checkpoint
+                    if policy.checkpointing.on_discovery
+                        || policy
+                            .checkpointing
+                            .interval_steps
+                            .map_or(false, |i| steps_executed % i == 0)
+                    {
+                        // Create a checkpoint state (simplified)
+                        let state = crate::graph::NodeState::from_str(&output);
+                        if let Err(e) = runner
+                            .save_checkpoint(state, Some(current_callable.name()))
+                            .await
+                        {
+                            // Log warning but continue?
+                            eprintln!("Failed to save checkpoint: {}", e);
+                        }
+                    }
+
+                    // 4. Determine Next Step (Discovery)
+                    // In a real agentic DAG, the output might contain instructions to run more tools
+                    // or discover new steps. For this v0 implementation, we check if the callable
+                    // returned a "DONE" signal or if it's a single-shot callable.
+
+                    // TODO: Parse output for discovered steps if this is a DiscoveryAgent
+                    // For now, we assume simple single-turn or limited loop
+
+                    // IF output suggests more work, continue.
+                    // IF output suggests completion, break.
+
+                    // Simple heuristic for now: if it's just a generic callable, run once.
+                    // If we want a loop, we'd need a "LoopCallable" wrapper or parsing logic.
+                    // Given the prompt asks for "loop for long running executions", we implement
+                    // the framework here but defaults to single pass unless discovered steps are found.
+
+                    // (Placeholder for proper Discovery logic which would be in the Callable result)
+
+                    return Ok(output);
+                }
+                Err(e) => return Err(e),
+            }
+        }
+    }
+}

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

@@ -0,0 +1,58 @@
+//! Runner module - thin execution shell
+//!
+//! The runner is a thin orchestration layer that:
+//! - Accepts invocations
+//! - Passes to Kernel
+//! - Wires callbacks
+//! - Returns streams
+//!
+//! Core execution logic lives in the kernel module.
+//! Context types are in the context module.
+//!
+//! ## CRITICAL INVARIANT: Runner Never Mutates State
+//!
+//! Runner is a thin orchestration shell. All execution semantics live in kernel/.
+//!
+//! Runner MUST NOT:
+//! - Mutate execution state directly
+//! - Retry steps (kernel handles retries)
+//! - Handle backoff (kernel handles backoff)
+//! - Skip nodes (kernel handles node execution)
+//!
+//! If Runner starts doing these things → duplicated kernel logic (architectural leak).
+//!
+//! **What Runner Does:**
+//! - Wires services (session, memory, artifacts)
+//! - Handles callbacks (before/after hooks)
+//! - Delegates execution to ExecutionKernel
+//! - Streams events to clients
+//!
+//! **What Runner Does NOT Do:**
+//! - Mutate execution state directly
+//! - Implement execution semantics
+//! - Make policy decisions
+//!
+//! @see docs/TECHNICAL/01-EXECUTION-TELEMETRY.md
+//! @see docs/TECHNICAL/25-STREAM-PROCESSORS.md
+
+mod callbacks;
+mod execution_runner;
+mod r#loop;
+mod protected_runner;
+
+// Runner types
+pub use execution_runner::{DefaultRunner, Runner};
+
+// Protected runner (feat-09: Guardrails)
+pub use protected_runner::{DefaultProtectedRunner, InputBlockedError, ProtectedRunner};
+
+// Re-export from kernel (kernel owns parallel/interrupt logic)
+pub use crate::kernel::{
+    run_parallel, InterruptDecision, InterruptReason, InterruptableRunner, ParallelResult,
+};
+
+// Re-export from context
+pub use crate::context::{
+    InvocationContext, InvocationServices, ResourceLimits, RuntimeContext, RuntimeContextBuilder,
+    SessionContext, TraceContext,
+};