enya-agent 0.1.0

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

@@ -0,0 +1,280 @@
+//! Protected Runner
+//!
+//! Wraps Runner with input processor pipeline to validate/transform input
+//! before execution begins.
+//!
+//! @see docs/TECHNICAL/17-GUARDRAILS-PROTECTION.md
+//! @see docs/TECHNICAL/25-STREAM-PROCESSORS.md
+
+use super::execution_runner::Runner;
+use crate::callable::Callable;
+use crate::graph::{CheckpointStore, CompiledGraph, NodeState};
+use crate::kernel::ExecutionId;
+use crate::policy::{
+    InputProcessor, InputProcessorPipeline, InputProcessorResult, PolicyAction, PolicyContext,
+};
+use crate::streaming::{EventEmitter, ProtectedEventEmitter};
+use std::sync::Arc;
+
+/// Error returned when input is blocked by processors
+#[derive(Debug, Clone)]
+pub struct InputBlockedError {
+    pub reason: String,
+    pub processor: String,
+}
+
+impl std::fmt::Display for InputBlockedError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "Input blocked by {}: {}", self.processor, self.reason)
+    }
+}
+
+impl std::error::Error for InputBlockedError {}
+
+/// Protected Runner
+///
+/// Wraps a Runner with input processor pipeline and optional protected emitter.
+/// Input is validated/transformed BEFORE execution begins.
+///
+/// ## Usage
+///
+/// ```ignore
+/// use enact_core::runner::{ProtectedRunner, DefaultRunner};
+/// use enact_core::policy::{PiiInputProcessor, PiiInputMode};
+///
+/// let runner = DefaultRunner::default_new();
+/// let protected = ProtectedRunner::new(runner)
+///     .with_input_processor(Arc::new(
+///         PiiInputProcessor::new().with_mode(PiiInputMode::BlockDirect)
+///     ));
+///
+/// // Input will be validated before callable runs
+/// let result = protected.run_callable(&my_callable, "user input").await;
+/// ```
+pub struct ProtectedRunner<S: CheckpointStore> {
+    inner: Runner<S>,
+    input_pipeline: InputProcessorPipeline,
+    protected_emitter: Option<ProtectedEventEmitter>,
+}
+
+impl<S: CheckpointStore> ProtectedRunner<S> {
+    /// Create a new protected runner wrapping an existing runner
+    pub fn new(runner: Runner<S>) -> Self {
+        Self {
+            inner: runner,
+            input_pipeline: InputProcessorPipeline::new(),
+            protected_emitter: None,
+        }
+    }
+
+    /// Add an input processor to the pipeline
+    pub fn with_input_processor(mut self, processor: Arc<dyn InputProcessor>) -> Self {
+        self.input_pipeline = self.input_pipeline.add(processor);
+        self
+    }
+
+    /// Set a protected emitter for output processing
+    pub fn with_protected_emitter(mut self, emitter: ProtectedEventEmitter) -> Self {
+        self.protected_emitter = Some(emitter);
+        self
+    }
+
+    /// Get the execution ID
+    pub fn execution_id(&self) -> &ExecutionId {
+        self.inner.execution_id()
+    }
+
+    /// Get the event emitter (from inner runner)
+    pub fn emitter(&self) -> &EventEmitter {
+        self.inner.emitter()
+    }
+
+    /// Cancel the run
+    pub fn cancel(&self) {
+        self.inner.cancel();
+    }
+
+    /// Check if cancelled
+    pub fn is_cancelled(&self) -> bool {
+        self.inner.is_cancelled()
+    }
+
+    /// Pause the run
+    pub async fn pause(&self) -> anyhow::Result<()> {
+        self.inner.pause().await
+    }
+
+    /// Resume the run
+    pub fn resume(&self) {
+        self.inner.resume();
+    }
+
+    /// Check if paused
+    pub fn is_paused(&self) -> bool {
+        self.inner.is_paused()
+    }
+
+    /// Create policy context for input processing
+    fn create_policy_context(&self) -> PolicyContext {
+        PolicyContext {
+            tenant_id: None, // Could be set from runner context
+            user_id: None,   // Could be set from runner context
+            action: PolicyAction::StartExecution { graph_id: None },
+            metadata: std::collections::HashMap::new(),
+        }
+    }
+
+    /// Process input through the pipeline
+    async fn process_input(&self, input: &str) -> anyhow::Result<String> {
+        if self.input_pipeline.is_empty() {
+            return Ok(input.to_string());
+        }
+
+        let ctx = self.create_policy_context();
+        let result = self.input_pipeline.process(input, &ctx).await?;
+
+        match result {
+            InputProcessorResult::Pass => Ok(input.to_string()),
+            InputProcessorResult::Block { reason, processor } => {
+                Err(InputBlockedError { reason, processor }.into())
+            }
+            InputProcessorResult::Modify { modified, .. } => Ok(modified),
+        }
+    }
+
+    /// Run a callable with input validation
+    pub async fn run_callable<A: Callable>(
+        &mut self,
+        callable: &A,
+        input: &str,
+    ) -> anyhow::Result<String> {
+        // Process input through pipeline
+        let processed_input = self.process_input(input).await?;
+
+        // Run with processed input
+        self.inner.run_callable(callable, &processed_input).await
+    }
+
+    /// Run a graph with input validation
+    pub async fn run_graph(
+        &mut self,
+        graph: &CompiledGraph,
+        input: &str,
+    ) -> anyhow::Result<NodeState> {
+        // Process input through pipeline
+        let processed_input = self.process_input(input).await?;
+
+        // Run with processed input
+        self.inner.run_graph(graph, &processed_input).await
+    }
+}
+
+/// Protected Runner with in-memory checkpoint store (default)
+pub type DefaultProtectedRunner = ProtectedRunner<crate::graph::InMemoryCheckpointStore>;
+
+impl DefaultProtectedRunner {
+    /// Create a new protected runner with in-memory checkpoint store
+    pub fn default_new() -> Self {
+        Self::new(crate::runner::DefaultRunner::default_new())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::runner::DefaultRunner;
+    use async_trait::async_trait;
+
+    struct MockCallable {
+        response: String,
+    }
+
+    impl MockCallable {
+        fn new(response: &str) -> Self {
+            Self {
+                response: response.to_string(),
+            }
+        }
+    }
+
+    #[async_trait]
+    impl Callable for MockCallable {
+        fn name(&self) -> &str {
+            "mock"
+        }
+        async fn run(&self, _input: &str) -> anyhow::Result<String> {
+            Ok(self.response.clone())
+        }
+    }
+
+    struct BlockingProcessor;
+
+    #[async_trait]
+    impl InputProcessor for BlockingProcessor {
+        fn name(&self) -> &str {
+            "blocker"
+        }
+
+        async fn process(
+            &self,
+            _input: &str,
+            _ctx: &PolicyContext,
+        ) -> anyhow::Result<InputProcessorResult> {
+            Ok(InputProcessorResult::Block {
+                reason: "Always blocks".to_string(),
+                processor: "blocker".to_string(),
+            })
+        }
+    }
+
+    #[tokio::test]
+    async fn test_protected_runner_no_processors() {
+        let runner = DefaultRunner::default_new();
+        let mut protected = ProtectedRunner::new(runner);
+        let callable = MockCallable::new("response");
+
+        let result = protected.run_callable(&callable, "input").await;
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap(), "response");
+    }
+
+    #[tokio::test]
+    async fn test_protected_runner_blocked_input() {
+        let runner = DefaultRunner::default_new();
+        let mut protected =
+            ProtectedRunner::new(runner).with_input_processor(Arc::new(BlockingProcessor));
+        let callable = MockCallable::new("response");
+
+        let result = protected.run_callable(&callable, "input").await;
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("blocked"));
+    }
+
+    #[tokio::test]
+    async fn test_protected_runner_execution_id() {
+        let runner = DefaultRunner::default_new();
+        let protected = ProtectedRunner::new(runner);
+
+        // Should have a valid execution ID
+        assert!(!protected.execution_id().as_str().is_empty());
+    }
+
+    #[tokio::test]
+    async fn test_protected_runner_cancel() {
+        let runner = DefaultRunner::default_new();
+        let protected = ProtectedRunner::new(runner);
+
+        assert!(!protected.is_cancelled());
+        protected.cancel();
+        assert!(protected.is_cancelled());
+    }
+
+    #[tokio::test]
+    async fn test_default_protected_runner() {
+        let mut protected = DefaultProtectedRunner::default_new();
+        let callable = MockCallable::new("hello");
+
+        let result = protected.run_callable(&callable, "test").await;
+        assert!(result.is_ok());
+    }
+}

package/crates/enact-core/src/signal/inmemory.rs

@@ -0,0 +1,231 @@
+//! In-memory SignalBus implementation for local/desktop/testing
+//!
+//! This is the default, in-memory-only implementation suitable for:
+//! - Local development
+//! - Desktop applications
+//! - Testing environments
+//! - Single-process deployments
+//!
+//! ## Important
+//!
+//! This implementation is **not distributed** and does **not** provide
+//! cross-process signaling. For distributed signaling, use the control plane
+//! which implements authoritative messaging (Redis, Kafka, etc.).
+
+use super::{SignalBus, SignalReceiver};
+use async_trait::async_trait;
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::sync::{broadcast, RwLock};
+
+/// In-memory signal bus using tokio broadcast channels
+///
+/// Suitable for desktop apps and testing (no external dependencies).
+/// Signals are best-effort and may be lost if no receivers are subscribed.
+pub struct InMemorySignalBus {
+    channels: Arc<RwLock<HashMap<String, broadcast::Sender<Vec<u8>>>>>,
+    capacity: usize,
+}
+
+impl InMemorySignalBus {
+    /// Create a new in-memory signal bus with the specified channel capacity
+    pub fn new(capacity: usize) -> Self {
+        Self {
+            channels: Arc::new(RwLock::new(HashMap::new())),
+            capacity,
+        }
+    }
+
+    /// Create a new in-memory signal bus with default capacity (1024)
+    pub fn default() -> Self {
+        Self::new(1024)
+    }
+}
+
+#[async_trait]
+impl SignalBus for InMemorySignalBus {
+    async fn emit(&self, channel: &str, signal: &[u8]) -> anyhow::Result<()> {
+        let channels = self.channels.read().await;
+        if let Some(sender) = channels.get(channel) {
+            // Ignore send errors (no receivers) - this is best-effort
+            let _ = sender.send(signal.to_vec());
+        }
+        Ok(())
+    }
+
+    async fn subscribe(&self, channel: &str) -> anyhow::Result<SignalReceiver<Vec<u8>>> {
+        let mut channels = self.channels.write().await;
+        let sender = channels
+            .entry(channel.to_string())
+            .or_insert_with(|| broadcast::channel(self.capacity).0);
+        Ok(sender.subscribe())
+    }
+
+    async fn unsubscribe(&self, _channel: &str) -> anyhow::Result<()> {
+        // Broadcast receivers auto-cleanup when dropped
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_inmemory_signal_bus_new() {
+        let bus = InMemorySignalBus::new(100);
+        assert_eq!(bus.capacity, 100);
+    }
+
+    #[tokio::test]
+    async fn test_inmemory_signal_bus_default() {
+        let bus = InMemorySignalBus::default();
+        assert_eq!(bus.capacity, 1024);
+    }
+
+    #[tokio::test]
+    async fn test_subscribe_and_receive() {
+        let bus = InMemorySignalBus::default();
+
+        // Subscribe to a channel
+        let mut rx = bus.subscribe("test-channel").await.unwrap();
+
+        // Emit a signal
+        bus.emit("test-channel", b"hello world").await.unwrap();
+
+        // Receive the signal
+        let received = rx.recv().await.unwrap();
+        assert_eq!(received, b"hello world".to_vec());
+    }
+
+    #[tokio::test]
+    async fn test_multiple_subscribers() {
+        let bus = InMemorySignalBus::default();
+
+        // Subscribe two receivers to the same channel
+        let mut rx1 = bus.subscribe("multi-channel").await.unwrap();
+        let mut rx2 = bus.subscribe("multi-channel").await.unwrap();
+
+        // Emit a signal
+        bus.emit("multi-channel", b"broadcast").await.unwrap();
+
+        // Both receivers should get the signal
+        let received1 = rx1.recv().await.unwrap();
+        let received2 = rx2.recv().await.unwrap();
+
+        assert_eq!(received1, b"broadcast".to_vec());
+        assert_eq!(received2, b"broadcast".to_vec());
+    }
+
+    #[tokio::test]
+    async fn test_emit_without_subscribers() {
+        let bus = InMemorySignalBus::default();
+
+        // Emit to a channel with no subscribers - should not fail
+        let result = bus.emit("no-subscribers", b"data").await;
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn test_emit_to_different_channels() {
+        let bus = InMemorySignalBus::default();
+
+        let mut rx1 = bus.subscribe("channel-a").await.unwrap();
+        let mut rx2 = bus.subscribe("channel-b").await.unwrap();
+
+        bus.emit("channel-a", b"msg-a").await.unwrap();
+        bus.emit("channel-b", b"msg-b").await.unwrap();
+
+        // Each receiver should only get their channel's messages
+        let received1 = rx1.recv().await.unwrap();
+        let received2 = rx2.recv().await.unwrap();
+
+        assert_eq!(received1, b"msg-a".to_vec());
+        assert_eq!(received2, b"msg-b".to_vec());
+    }
+
+    #[tokio::test]
+    async fn test_unsubscribe() {
+        let bus = InMemorySignalBus::default();
+
+        let _rx = bus.subscribe("unsub-channel").await.unwrap();
+
+        // Unsubscribe should succeed (no-op for broadcast)
+        let result = bus.unsubscribe("unsub-channel").await;
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn test_multiple_messages() {
+        let bus = InMemorySignalBus::default();
+
+        let mut rx = bus.subscribe("multi-msg").await.unwrap();
+
+        bus.emit("multi-msg", b"first").await.unwrap();
+        bus.emit("multi-msg", b"second").await.unwrap();
+        bus.emit("multi-msg", b"third").await.unwrap();
+
+        assert_eq!(rx.recv().await.unwrap(), b"first".to_vec());
+        assert_eq!(rx.recv().await.unwrap(), b"second".to_vec());
+        assert_eq!(rx.recv().await.unwrap(), b"third".to_vec());
+    }
+
+    #[tokio::test]
+    async fn test_late_subscriber_misses_messages() {
+        let bus = InMemorySignalBus::default();
+
+        // Subscribe first receiver
+        let mut rx1 = bus.subscribe("late-sub").await.unwrap();
+
+        // Emit first message
+        bus.emit("late-sub", b"early").await.unwrap();
+
+        // Subscribe second receiver (late)
+        let mut rx2 = bus.subscribe("late-sub").await.unwrap();
+
+        // Emit second message
+        bus.emit("late-sub", b"late").await.unwrap();
+
+        // First receiver gets both
+        assert_eq!(rx1.recv().await.unwrap(), b"early".to_vec());
+        assert_eq!(rx1.recv().await.unwrap(), b"late".to_vec());
+
+        // Second receiver only gets the late message
+        assert_eq!(rx2.recv().await.unwrap(), b"late".to_vec());
+    }
+
+    #[tokio::test]
+    async fn test_concurrent_emit() {
+        let bus = Arc::new(InMemorySignalBus::default());
+
+        let mut rx = bus.subscribe("concurrent").await.unwrap();
+
+        let bus1 = bus.clone();
+        let bus2 = bus.clone();
+
+        // Spawn two tasks emitting concurrently
+        let h1 = tokio::spawn(async move {
+            for i in 0..5 {
+                bus1.emit("concurrent", format!("msg-a-{}", i).as_bytes()).await.unwrap();
+            }
+        });
+
+        let h2 = tokio::spawn(async move {
+            for i in 0..5 {
+                bus2.emit("concurrent", format!("msg-b-{}", i).as_bytes()).await.unwrap();
+            }
+        });
+
+        h1.await.unwrap();
+        h2.await.unwrap();
+
+        // Collect all received messages
+        let mut received = Vec::new();
+        while let Ok(msg) = rx.try_recv() {
+            received.push(msg);
+        }
+
+        // Should have received 10 messages total
+        assert_eq!(received.len(), 10);
+    }
+}

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

@@ -0,0 +1,108 @@
+//! Signal module - Optional, best-effort signaling for hints and notifications
+//!
+//! ## Important: Non-Authoritative
+//!
+//! This module provides **optional, best-effort signaling** for hints and
+//! notifications. Signals are **not authoritative** and the kernel must work
+//! correctly even if all signaling infrastructure is disabled.
+//!
+//! ## Three Kinds of "Messages"
+//!
+//! There are three distinct kinds of communication in the system:
+//!
+//! | Kind                       | Example                         | Where it belongs        |
+//! | -------------------------- | ------------------------------- | ----------------------- |
+//! | **Execution events**       | step started, decision made     | **Kernel only** (`kernel/event.rs`) |
+//! | **Control signals**        | cancel execution, scale workers | **Control plane** (cloud) |
+//! | **Infrastructure signals** | notify UI, wake worker          | **This module** (optional) |
+//!
+//! ## Signal Semantics
+//!
+//! Signals are:
+//! - ✅ Non-authoritative (may be ignored)
+//! - ✅ Best-effort (delivery not guaranteed)
+//! - ✅ Optional (kernel works perfectly without them)
+//! - ✅ For hints only (wake-up, notify, nudge)
+//!
+//! Signals are NOT:
+//! - ❌ Execution events (use `kernel/event.rs`)
+//! - ❌ State changes (use `kernel/reducer.rs`)
+//! - ❌ Required for correctness
+//! - ❌ Durable queues (use control plane)
+//!
+//! ## Invariant
+//!
+//! **The kernel must remain correct, deterministic, and replayable
+//! even if all signaling infrastructure is disabled.**
+//!
+//! ## CRITICAL INVARIANT: Signals Never Drive Execution State
+//!
+//! SignalBus implementations MUST NOT have access to:
+//! - ExecutionKernel
+//! - Reducer
+//! - ExecutionState
+//!
+//! Signals are hints only. If someone can "resume execution" via signal,
+//! that is an architectural leak.
+//!
+//! **Enforcement**: SignalBus trait and implementations should not import
+//! any kernel modules. If you find yourself needing kernel types in signal
+//! code, you are violating this invariant.
+//!
+//! ## Use Cases
+//!
+//! ### Allowed Signal Uses
+//! - ✅ Wake a paused execution
+//! - ✅ Notify local UI
+//! - ✅ Tell a worker "check for work"
+//! - ✅ Hint that something changed
+//!
+//! ### Forbidden Signal Uses
+//! - ❌ Carry execution events (use `kernel/event.rs`)
+//! - ❌ Control execution state (use `kernel/reducer.rs`)
+//! - ❌ Replace durable queues (use control plane)
+//! - ❌ Drive orchestration logic (use control plane)
+//!
+//! ## Control Plane Messaging
+//!
+//! Authoritative messaging (Redis, Kafka, durable queues) lives in the
+//! control plane (`apps/api/` or future `enact-control-plane` crate), not here.
+//! The control plane:
+//! - Implements durable queues
+//! - Translates infra messages → kernel invocations
+//! - Fans out kernel events to external systems
+//!
+//! The kernel does not know *how* messages travel. It only knows:
+//! > "I was invoked."
+
+use async_trait::async_trait;
+use std::sync::Arc;
+use tokio::sync::broadcast;
+
+mod inmemory;
+
+pub use inmemory::InMemorySignalBus;
+
+/// Receiver for subscribed signals
+pub type SignalReceiver<T> = broadcast::Receiver<T>;
+
+/// SignalBus trait - Optional, best-effort signaling abstraction
+///
+/// This trait provides a non-authoritative signaling mechanism for hints
+/// and notifications. Implementations should be lightweight and optional.
+///
+/// The kernel must work correctly even if SignalBus is disabled or fails.
+#[async_trait]
+pub trait SignalBus: Send + Sync {
+    /// Emit a signal to a channel (best-effort, may be ignored)
+    async fn emit(&self, channel: &str, signal: &[u8]) -> anyhow::Result<()>;
+
+    /// Subscribe to a channel, returns a receiver for signals
+    async fn subscribe(&self, channel: &str) -> anyhow::Result<SignalReceiver<Vec<u8>>>;
+
+    /// Unsubscribe from a channel
+    async fn unsubscribe(&self, channel: &str) -> anyhow::Result<()>;
+}
+
+/// Boxed SignalBus for dynamic dispatch
+pub type DynSignalBus = Arc<dyn SignalBus>;