enya-agent 0.1.0

package/crates/enact-core/src/streaming/protection/mod.rs

@@ -0,0 +1,43 @@
+//! Streaming Protection Layer
+//!
+//! Output processors that run AFTER kernel execution, BEFORE storage/streaming.
+//!
+//! ## Architecture
+//!
+//! This module implements the protection layer from [17-GUARDRAILS-PROTECTION.md].
+//! All observability data passes through this layer before storage or transmission.
+//!
+//! ```text
+//! ExecutionKernel
+//!       │
+//!       ▼ (StreamEvent)
+//! ┌─────────────────────────────────────┐
+//! │      Protection Pipeline            │
+//! │  ┌───────────┐  ┌────────────────┐ │
+//! │  │    PII    │→ │   Encryption   │ │
+//! │  │ Protection│  │   (storage)    │ │
+//! │  └───────────┘  └────────────────┘ │
+//! └─────────────────────────────────────┘
+//!       │                    │
+//!       ▼ (masked)           ▼ (encrypted)
+//!    SSE/GUI              EventStore
+//! ```
+//!
+//! ## Key Invariants
+//!
+//! - **No raw PII to frontend**: Kernel never emits raw PII to frontend-visible channels
+//! - **Protection before storage**: All events pass through protection before storage
+//! - **Streaming is read-only**: Processors transform payloads, don't mutate state
+//!
+//! @see docs/TECHNICAL/17-GUARDRAILS-PROTECTION.md
+//! @see docs/TECHNICAL/25-STREAM-PROCESSORS.md
+
+mod context;
+mod encryption;
+mod pii_protection;
+mod processor;
+
+pub use context::{DataDestination, ProtectionContext};
+pub use encryption::EncryptionProcessor;
+pub use pii_protection::PiiProtectionProcessor;
+pub use processor::{OutputProcessor, ProcessedEvent, ProcessorPipeline};

package/crates/enact-core/src/streaming/protection/pii_protection.rs

@@ -0,0 +1,243 @@
+//! PII Protection Processor
+//!
+//! Masks PII in stream events before storage or streaming to frontend.
+//! Uses `enact-guardrails` for detection and redaction.
+
+use super::context::{DataDestination, ProtectionContext};
+use super::processor::{OutputProcessor, ProcessedEvent};
+use crate::streaming::StreamEvent;
+use async_trait::async_trait;
+
+#[cfg(feature = "guardrails")]
+use enact_guardrails::{PiiDetector, PiiRedactor};
+
+/// PII Protection Processor
+///
+/// Detects and masks PII in event payloads based on destination:
+/// - Stream (frontend): Always mask
+/// - Storage: Mask + optionally encrypt (future)
+/// - Log: Hash sensitive fields
+/// - AuditExport: Mask for external, allow for internal
+pub struct PiiProtectionProcessor {
+    #[cfg(feature = "guardrails")]
+    detector: PiiDetector,
+}
+
+impl PiiProtectionProcessor {
+    /// Create a new PII protection processor
+    #[cfg(feature = "guardrails")]
+    pub fn new() -> Self {
+        Self {
+            detector: PiiDetector::new(),
+        }
+    }
+
+    /// Create a new PII protection processor (no-op when guardrails feature disabled)
+    #[cfg(not(feature = "guardrails"))]
+    pub fn new() -> Self {
+        Self {}
+    }
+
+    /// Mask PII in a text field
+    #[cfg(feature = "guardrails")]
+    fn mask_text(&self, text: &str) -> (String, bool) {
+        let matches = self.detector.detect(text);
+        if matches.is_empty() {
+            (text.to_string(), false)
+        } else {
+            (PiiRedactor::redact_matches(text, &matches), true)
+        }
+    }
+
+    /// Mask PII in a text field (no-op when guardrails disabled)
+    #[cfg(not(feature = "guardrails"))]
+    fn mask_text(&self, text: &str) -> (String, bool) {
+        (text.to_string(), false)
+    }
+
+    /// Process a StreamEvent, masking any PII in text fields
+    fn mask_event(&self, event: StreamEvent, ctx: &ProtectionContext) -> ProcessedEvent {
+        // For internal audit exports, don't mask (they need full access)
+        if ctx.destination == DataDestination::AuditExport && ctx.is_internal_audit {
+            return ProcessedEvent::unchanged(event);
+        }
+
+        match event {
+            StreamEvent::TextDelta { id, delta } => {
+                let (masked_delta, was_modified) = self.mask_text(&delta);
+                if was_modified {
+                    ProcessedEvent::modified(StreamEvent::TextDelta {
+                        id,
+                        delta: masked_delta,
+                    })
+                } else {
+                    ProcessedEvent::unchanged(StreamEvent::TextDelta { id, delta })
+                }
+            }
+            StreamEvent::StepEnd {
+                execution_id,
+                step_id,
+                output,
+                duration_ms,
+                timestamp,
+            } => {
+                let (masked_output, was_modified) = match output {
+                    Some(ref text) => {
+                        let (masked, modified) = self.mask_text(text);
+                        (Some(masked), modified)
+                    }
+                    None => (None, false),
+                };
+                if was_modified {
+                    ProcessedEvent::modified(StreamEvent::StepEnd {
+                        execution_id,
+                        step_id,
+                        output: masked_output,
+                        duration_ms,
+                        timestamp,
+                    })
+                } else {
+                    ProcessedEvent::unchanged(StreamEvent::StepEnd {
+                        execution_id,
+                        step_id,
+                        output,
+                        duration_ms,
+                        timestamp,
+                    })
+                }
+            }
+            StreamEvent::ExecutionEnd {
+                execution_id,
+                final_output,
+                duration_ms,
+                timestamp,
+            } => {
+                let (masked_output, was_modified) = match final_output {
+                    Some(ref text) => {
+                        let (masked, modified) = self.mask_text(text);
+                        (Some(masked), modified)
+                    }
+                    None => (None, false),
+                };
+                if was_modified {
+                    ProcessedEvent::modified(StreamEvent::ExecutionEnd {
+                        execution_id,
+                        final_output: masked_output,
+                        duration_ms,
+                        timestamp,
+                    })
+                } else {
+                    ProcessedEvent::unchanged(StreamEvent::ExecutionEnd {
+                        execution_id,
+                        final_output,
+                        duration_ms,
+                        timestamp,
+                    })
+                }
+            }
+            StreamEvent::Error { error } => {
+                // Mask error messages - they might contain PII
+                let (masked_message, was_modified) = self.mask_text(&error.message);
+                if was_modified {
+                    let mut masked_error = error.clone();
+                    masked_error.message = masked_message;
+                    ProcessedEvent::modified(StreamEvent::Error {
+                        error: masked_error,
+                    })
+                } else {
+                    ProcessedEvent::unchanged(StreamEvent::Error { error })
+                }
+            }
+            // Events without text content pass through unchanged
+            _ => ProcessedEvent::unchanged(event),
+        }
+    }
+}
+
+impl Default for PiiProtectionProcessor {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl OutputProcessor for PiiProtectionProcessor {
+    fn name(&self) -> &str {
+        "pii-protection"
+    }
+
+    async fn process(
+        &self,
+        event: StreamEvent,
+        ctx: &ProtectionContext,
+    ) -> anyhow::Result<ProcessedEvent> {
+        Ok(self.mask_event(event, ctx))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::kernel::ExecutionId;
+
+    #[tokio::test]
+    async fn test_pii_protection_processor_name() {
+        let processor = PiiProtectionProcessor::new();
+        assert_eq!(processor.name(), "pii-protection");
+    }
+
+    #[cfg(feature = "guardrails")]
+    #[tokio::test]
+    async fn test_pii_protection_masks_email_in_text_delta() {
+        let processor = PiiProtectionProcessor::new();
+        let ctx = ProtectionContext::for_stream();
+
+        let event = StreamEvent::TextDelta {
+            id: "test".to_string(),
+            delta: "Contact me at user@example.com".to_string(),
+        };
+
+        let result = processor.process(event, &ctx).await.unwrap();
+        assert!(result.was_modified);
+
+        if let StreamEvent::TextDelta { delta, .. } = result.event {
+            assert!(delta.contains("us***@example.com"));
+            assert!(!delta.contains("user@example.com"));
+        } else {
+            panic!("Expected TextDelta event");
+        }
+    }
+
+    #[cfg(feature = "guardrails")]
+    #[tokio::test]
+    async fn test_pii_protection_skips_internal_audit() {
+        let processor = PiiProtectionProcessor::new();
+        let ctx = ProtectionContext::for_audit(true); // internal audit
+
+        let event = StreamEvent::TextDelta {
+            id: "test".to_string(),
+            delta: "Contact me at user@example.com".to_string(),
+        };
+
+        let result = processor.process(event, &ctx).await.unwrap();
+        // Internal audit should NOT mask
+        assert!(!result.was_modified);
+
+        if let StreamEvent::TextDelta { delta, .. } = result.event {
+            assert!(delta.contains("user@example.com")); // unmasked
+        }
+    }
+
+    #[tokio::test]
+    async fn test_pii_protection_unchanged_event() {
+        let processor = PiiProtectionProcessor::new();
+        let ctx = ProtectionContext::for_stream();
+
+        // Events without text content pass through unchanged
+        let exec_id = ExecutionId::new();
+        let event = StreamEvent::execution_start(&exec_id);
+
+        let result = processor.process(event, &ctx).await.unwrap();
+        assert!(!result.was_modified);
+    }
+}

package/crates/enact-core/src/streaming/protection/processor.rs

@@ -0,0 +1,166 @@
+//! Output Processor Trait
+//!
+//! Defines the trait for output processors that transform events before
+//! storage or streaming.
+
+use super::context::ProtectionContext;
+use crate::streaming::StreamEvent;
+use async_trait::async_trait;
+use std::sync::Arc;
+
+/// Result of processing an event
+#[derive(Debug, Clone)]
+pub struct ProcessedEvent {
+    /// The processed event (may be transformed)
+    pub event: StreamEvent,
+
+    /// Whether the event was modified
+    pub was_modified: bool,
+
+    /// Optional: encrypted payload for storage (if applicable)
+    pub encrypted_payload: Option<String>,
+}
+
+impl ProcessedEvent {
+    /// Create a processed event that was not modified
+    pub fn unchanged(event: StreamEvent) -> Self {
+        Self {
+            event,
+            was_modified: false,
+            encrypted_payload: None,
+        }
+    }
+
+    /// Create a processed event that was modified
+    pub fn modified(event: StreamEvent) -> Self {
+        Self {
+            event,
+            was_modified: true,
+            encrypted_payload: None,
+        }
+    }
+
+    /// Add an encrypted payload (for storage destination)
+    pub fn with_encrypted(mut self, encrypted: String) -> Self {
+        self.encrypted_payload = Some(encrypted);
+        self
+    }
+}
+
+/// Output Processor trait
+///
+/// Processors run AFTER kernel execution, BEFORE storage/streaming.
+/// They MUST NOT mutate execution state (streaming is read-only).
+#[async_trait]
+pub trait OutputProcessor: Send + Sync {
+    /// Processor name for logging/metrics
+    fn name(&self) -> &str;
+
+    /// Process an event before storage/streaming
+    ///
+    /// # Arguments
+    /// * `event` - The event to process
+    /// * `ctx` - Protection context (destination, tenant, etc.)
+    ///
+    /// # Returns
+    /// The processed event, potentially transformed
+    async fn process(
+        &self,
+        event: StreamEvent,
+        ctx: &ProtectionContext,
+    ) -> anyhow::Result<ProcessedEvent>;
+}
+
+/// Processor Pipeline - chains multiple processors
+pub struct ProcessorPipeline {
+    processors: Vec<Arc<dyn OutputProcessor>>,
+}
+
+impl ProcessorPipeline {
+    /// Create a new empty pipeline
+    pub fn new() -> Self {
+        Self { processors: vec![] }
+    }
+
+    /// Add a processor to the pipeline
+    pub fn add(mut self, processor: Arc<dyn OutputProcessor>) -> Self {
+        self.processors.push(processor);
+        self
+    }
+
+    /// Run all processors in sequence
+    pub async fn process(
+        &self,
+        event: StreamEvent,
+        ctx: &ProtectionContext,
+    ) -> anyhow::Result<ProcessedEvent> {
+        let mut current_event = event;
+        let mut any_modified = false;
+        let mut encrypted_payload = None;
+
+        for processor in &self.processors {
+            let result = processor.process(current_event, ctx).await?;
+            any_modified = any_modified || result.was_modified;
+            encrypted_payload = result.encrypted_payload.or(encrypted_payload);
+            current_event = result.event;
+        }
+
+        Ok(ProcessedEvent {
+            event: current_event,
+            was_modified: any_modified,
+            encrypted_payload,
+        })
+    }
+
+    /// Check if the pipeline is empty
+    pub fn is_empty(&self) -> bool {
+        self.processors.is_empty()
+    }
+
+    /// Get the number of processors
+    pub fn len(&self) -> usize {
+        self.processors.len()
+    }
+}
+
+impl Default for ProcessorPipeline {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_processed_event_unchanged() {
+        let event = StreamEvent::text_start(None);
+        let processed = ProcessedEvent::unchanged(event);
+        assert!(!processed.was_modified);
+        assert!(processed.encrypted_payload.is_none());
+    }
+
+    #[test]
+    fn test_processed_event_modified() {
+        let event = StreamEvent::text_start(None);
+        let processed = ProcessedEvent::modified(event);
+        assert!(processed.was_modified);
+    }
+
+    #[test]
+    fn test_processed_event_with_encrypted() {
+        let event = StreamEvent::text_start(None);
+        let processed =
+            ProcessedEvent::modified(event).with_encrypted("encrypted_data".to_string());
+        assert!(processed.encrypted_payload.is_some());
+        assert_eq!(processed.encrypted_payload.unwrap(), "encrypted_data");
+    }
+
+    #[test]
+    fn test_pipeline_new() {
+        let pipeline = ProcessorPipeline::new();
+        assert!(pipeline.is_empty());
+        assert_eq!(pipeline.len(), 0);
+    }
+}

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

@@ -0,0 +1,49 @@
+//! Telemetry module - OpenTelemetry integration
+//!
+//! This module bridges core execution IDs and events into OpenTelemetry spans/traces.
+//!
+//! ## Important: Source of Truth
+//!
+//! IDs and Events are DEFINED in `kernel/` (source of truth).
+//! This module bridges them into OpenTelemetry spans/traces.
+//! No new domain types defined here.
+//!
+//! ## What This Module Provides
+//!
+//! - **Span attribute types**: ExecutionSpanAttributes, StepSpanAttributes, etc.
+//! - **Span name generators**: execution_span_name, step_span_name, etc.
+//! - **Trace context extraction**: extract_trace_context
+//!
+//! ## Architecture
+//!
+//! ```text
+//! kernel/ (source of truth)
+//!   │
+//!   │ IDs and Events
+//!   ▼
+//! ┌─────────────────────────────────────────────────────────┐
+//! │                    telemetry/                            │
+//! │  ┌────────────┐  ┌────────────┐  ┌────────────┐       │
+//! │  │   spans    │  │  exporter  │  │    init    │       │
+//! │  │(attributes)│  │  (OTel)    │  │  (setup)   │       │
+//! │  └────────────┘  └────────────┘  └────────────┘       │
+//! └────────────────────────────┬────────────────────────────┘
+//!                              │
+//!                              ▼
+//!                    OpenTelemetry Collector
+//! ```
+//!
+//! @see docs/TECHNICAL/01-EXECUTION-TELEMETRY.md
+
+mod exporter;
+mod init;
+mod spans;
+
+pub use spans::{
+    // Span attribute types
+    ExecutionSpanAttributes, LlmSpanAttributes, StepSpanAttributes, ToolSpanAttributes,
+    // Span name generators
+    execution_span_name, llm_span_name, step_span_name, tool_span_name,
+    // Trace utilities
+    extract_trace_context,
+};