enya-agent 0.1.0

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

@@ -0,0 +1,108 @@
+//! Streaming - Event delivery and persistence
+//!
+//! This module handles **delivery** of events to consumers. It subscribes to
+//! kernel events and delivers them via SSE, persistence, etc.
+//!
+//! ## Important: Source of Truth
+//!
+//! IDs and Events are DEFINED in `kernel/` (source of truth).
+//! This module RE-EXPORTS them for convenience and provides:
+//! - **event_logger.rs**: Append-only event log (EventStore, EventLog)
+//! - **event_stream.rs**: Wire format for SSE (StreamEvent, data-* protocol)
+//!
+//! ## Architecture
+//!
+//! ```text
+//! ExecutionKernel (owns IDs and Events)
+//!       │
+//!       │ emit events
+//!       ▼
+//! ┌─────────────────────────────────────────────────────────┐
+//! │                    streaming/                            │
+//! │  ┌────────────┐  ┌────────────────────┐                 │
+//! │  │event_logger│  │  event_stream.rs   │                 │
+//! │  │ (persist)  │  │  (wire format)     │                 │
+//! │  └────────────┘  └─────────┬──────────┘                 │
+//! └────────────────────────────┼────────────────────────────┘
+//!                              │
+//!                ┌─────────────┼─────────────────┐
+//!                ▼             ▼                 ▼
+//!          ┌──────────┐ ┌───────────┐      ┌───────────┐
+//!          │   TUI    │ │ GUI (SSE) │      │ telemetry │
+//!          │(ratatui) │ │ (web)     │      │  (OTel)   │
+//!          └──────────┘ └───────────┘      └───────────┘
+//! ```
+//!
+//! ## Event Protocol
+//! All events use `data-*` prefix for SSE compatibility:
+//! - Standard: `data-text-start`, `data-text-delta`, `data-finish`, etc.
+//! - Custom: `data-execution-start`, `data-step-start`, etc.
+//!
+//! @see docs/TECHNICAL/01-EXECUTION-TELEMETRY.md
+//! @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
+
+mod event_logger;
+mod event_stream;
+mod pause_cancel;
+mod sse;
+
+// =============================================================================
+// Stream Events (wire format for SSE)
+// =============================================================================
+pub use event_stream::{EventEmitter, EventStream, StreamEvent, StreamMode};
+
+// =============================================================================
+// Event Log (persistence)
+// =============================================================================
+pub use event_logger::{EventLog, EventLogEntry, EventStore, InMemoryEventStore};
+
+// =============================================================================
+// Re-exports from kernel (source of truth)
+// =============================================================================
+// IDs and Events are DEFINED in kernel/. We re-export for convenience.
+pub use crate::kernel::{
+    prefixes,
+    // IDs
+    ArtifactId,
+    ExecutionId,
+    GraphId,
+    MessageId,
+    ThreadId,
+    // Events
+    ControlAction,
+    ControlActor,
+    ControlEvent,
+    ControlOutcome,
+    DecisionAlternative,
+    DecisionInput,
+    DecisionRecord,
+    DecisionType,
+    Event,
+    ExecutionContext,
+    ExecutionEvent,
+    ExecutionEventType,
+    ModelContext,
+    NodeId,
+    ParentLink,
+    ParentType,
+    RunId,
+    StepId,
+    StepType,
+    TenantId,
+    UserId,
+};
+
+// =============================================================================
+// Protection Layer (feat-09: Guardrails)
+// =============================================================================
+// Output processors that run BEFORE storage/streaming.
+// @see docs/TECHNICAL/17-GUARDRAILS-PROTECTION.md
+// @see docs/TECHNICAL/25-STREAM-PROCESSORS.md
+mod protected_emitter;
+pub mod protection;
+
+pub use protected_emitter::ProtectedEventEmitter;
+pub use protection::{
+    DataDestination, EncryptionProcessor, OutputProcessor, PiiProtectionProcessor, ProcessedEvent,
+    ProcessorPipeline, ProtectionContext,
+};

package/crates/enact-core/src/streaming/protected_emitter.rs

@@ -0,0 +1,173 @@
+//! Protected Event Emitter
+//!
+//! Wraps EventEmitter with output processor pipeline to ensure all events
+//! pass through protection before storage/streaming.
+//!
+//! @see docs/TECHNICAL/17-GUARDRAILS-PROTECTION.md
+
+use super::protection::{OutputProcessor, ProcessorPipeline, ProtectionContext};
+use super::{EventEmitter, StreamEvent, StreamMode};
+use std::sync::Arc;
+
+/// Protected Event Emitter
+///
+/// Wraps EventEmitter with output processor pipeline.
+/// All events pass through protection before being added to the stream.
+///
+/// ## Usage
+///
+/// ```ignore
+/// use enact_core::streaming::{ProtectedEventEmitter, PiiProtectionProcessor};
+///
+/// let emitter = ProtectedEventEmitter::new()
+///     .with_processor(Arc::new(PiiProtectionProcessor::new()))
+///     .with_context(ProtectionContext::for_stream());
+/// ```
+pub struct ProtectedEventEmitter {
+    inner: EventEmitter,
+    pipeline: ProcessorPipeline,
+    context: ProtectionContext,
+}
+
+impl ProtectedEventEmitter {
+    /// Create a new protected event emitter
+    pub fn new() -> Self {
+        Self {
+            inner: EventEmitter::new(),
+            pipeline: ProcessorPipeline::new(),
+            context: ProtectionContext::for_stream(),
+        }
+    }
+
+    /// Create with a specific stream mode
+    pub fn with_mode(mode: StreamMode) -> Self {
+        Self {
+            inner: EventEmitter::with_mode(mode),
+            pipeline: ProcessorPipeline::new(),
+            context: ProtectionContext::for_stream(),
+        }
+    }
+
+    /// Add a processor to the pipeline
+    pub fn with_processor(mut self, processor: Arc<dyn OutputProcessor>) -> Self {
+        self.pipeline = self.pipeline.add(processor);
+        self
+    }
+
+    /// Set the protection context
+    pub fn with_context(mut self, context: ProtectionContext) -> Self {
+        self.context = context;
+        self
+    }
+
+    /// Set the protection context (mutable)
+    pub fn set_context(&mut self, context: ProtectionContext) {
+        self.context = context;
+    }
+
+    /// Get the protection context
+    pub fn context(&self) -> &ProtectionContext {
+        &self.context
+    }
+
+    /// Emit an event (runs through protection pipeline)
+    ///
+    /// This is async because processors may need async operations
+    pub async fn emit(&self, event: StreamEvent) -> anyhow::Result<()> {
+        if self.pipeline.is_empty() {
+            // No processors, emit directly
+            self.inner.emit(event);
+            return Ok(());
+        }
+
+        // Run through protection pipeline
+        let processed = self.pipeline.process(event, &self.context).await?;
+        self.inner.emit(processed.event);
+        Ok(())
+    }
+
+    /// Emit an event synchronously (bypasses protection pipeline)
+    ///
+    /// Use only for events that are guaranteed safe (control events, etc.)
+    pub fn emit_unprotected(&self, event: StreamEvent) {
+        self.inner.emit(event);
+    }
+
+    /// Emit an event unconditionally (ignores mode, runs through protection)
+    pub async fn emit_force(&self, event: StreamEvent) -> anyhow::Result<()> {
+        if self.pipeline.is_empty() {
+            self.inner.emit_force(event);
+            return Ok(());
+        }
+
+        let processed = self.pipeline.process(event, &self.context).await?;
+        self.inner.emit_force(processed.event);
+        Ok(())
+    }
+
+    /// Get all collected events
+    pub fn drain(&self) -> Vec<StreamEvent> {
+        self.inner.drain()
+    }
+
+    /// Get the current stream mode
+    pub fn mode(&self) -> StreamMode {
+        self.inner.mode()
+    }
+
+    /// Get reference to inner emitter (for compatibility)
+    pub fn inner(&self) -> &EventEmitter {
+        &self.inner
+    }
+}
+
+impl Default for ProtectedEventEmitter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::kernel::ExecutionId;
+
+    #[tokio::test]
+    async fn test_protected_emitter_no_processors() {
+        let emitter = ProtectedEventEmitter::new();
+        let exec_id = ExecutionId::new();
+
+        emitter
+            .emit(StreamEvent::execution_start(&exec_id))
+            .await
+            .unwrap();
+
+        let events = emitter.drain();
+        assert_eq!(events.len(), 1);
+    }
+
+    #[tokio::test]
+    async fn test_protected_emitter_emit_unprotected() {
+        let emitter = ProtectedEventEmitter::new();
+        let exec_id = ExecutionId::new();
+
+        // Emit synchronously
+        emitter.emit_unprotected(StreamEvent::execution_start(&exec_id));
+
+        let events = emitter.drain();
+        assert_eq!(events.len(), 1);
+    }
+
+    #[tokio::test]
+    async fn test_protected_emitter_context() {
+        let emitter = ProtectedEventEmitter::new().with_context(ProtectionContext::for_storage());
+
+        assert!(emitter.context().destination.requires_encryption());
+    }
+
+    #[tokio::test]
+    async fn test_protected_emitter_mode() {
+        let emitter = ProtectedEventEmitter::with_mode(StreamMode::Summary);
+        assert_eq!(emitter.mode(), StreamMode::Summary);
+    }
+}

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

@@ -0,0 +1,136 @@
+//! Protection Context
+//!
+//! Context types that determine how data is protected based on its destination.
+
+use crate::kernel::TenantId;
+
+/// Data destination - where the data is going
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DataDestination {
+    /// Storage (PostgreSQL, Blob Storage, EventStore)
+    /// Treatment: Encrypt sensitive fields
+    Storage,
+
+    /// Streaming to frontend (SSE, gRPC)
+    /// Treatment: Mask PII, never send encrypted or raw
+    Stream,
+
+    /// Structured logs (telemetry, observability)
+    /// Treatment: Hash or mask, never raw
+    Log,
+
+    /// Audit export (JSON, PDF)
+    /// Treatment: Decrypt for internal, mask for external
+    AuditExport,
+}
+
+impl DataDestination {
+    /// Returns true if this destination is frontend-visible
+    pub fn is_frontend_visible(&self) -> bool {
+        matches!(self, DataDestination::Stream)
+    }
+
+    /// Returns true if this destination requires encryption
+    pub fn requires_encryption(&self) -> bool {
+        matches!(self, DataDestination::Storage)
+    }
+}
+
+/// Protection context - information needed to make protection decisions
+#[derive(Debug, Clone)]
+pub struct ProtectionContext {
+    /// Where the data is going
+    pub destination: DataDestination,
+
+    /// Tenant context (for tenant-specific policies)
+    pub tenant_id: Option<TenantId>,
+
+    /// Whether this is an internal audit export (can decrypt)
+    pub is_internal_audit: bool,
+}
+
+impl ProtectionContext {
+    /// Create a new protection context
+    pub fn new(destination: DataDestination) -> Self {
+        Self {
+            destination,
+            tenant_id: None,
+            is_internal_audit: false,
+        }
+    }
+
+    /// Create context for streaming to frontend
+    pub fn for_stream() -> Self {
+        Self::new(DataDestination::Stream)
+    }
+
+    /// Create context for storage
+    pub fn for_storage() -> Self {
+        Self::new(DataDestination::Storage)
+    }
+
+    /// Create context for logging
+    pub fn for_log() -> Self {
+        Self::new(DataDestination::Log)
+    }
+
+    /// Create context for audit export
+    pub fn for_audit(is_internal: bool) -> Self {
+        Self {
+            destination: DataDestination::AuditExport,
+            tenant_id: None,
+            is_internal_audit: is_internal,
+        }
+    }
+
+    /// Add tenant context
+    pub fn with_tenant(mut self, tenant_id: TenantId) -> Self {
+        self.tenant_id = Some(tenant_id);
+        self
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_data_destination_frontend_visible() {
+        assert!(DataDestination::Stream.is_frontend_visible());
+        assert!(!DataDestination::Storage.is_frontend_visible());
+        assert!(!DataDestination::Log.is_frontend_visible());
+        assert!(!DataDestination::AuditExport.is_frontend_visible());
+    }
+
+    #[test]
+    fn test_data_destination_requires_encryption() {
+        assert!(DataDestination::Storage.requires_encryption());
+        assert!(!DataDestination::Stream.requires_encryption());
+        assert!(!DataDestination::Log.requires_encryption());
+        assert!(!DataDestination::AuditExport.requires_encryption());
+    }
+
+    #[test]
+    fn test_protection_context_factories() {
+        let stream_ctx = ProtectionContext::for_stream();
+        assert_eq!(stream_ctx.destination, DataDestination::Stream);
+
+        let storage_ctx = ProtectionContext::for_storage();
+        assert_eq!(storage_ctx.destination, DataDestination::Storage);
+
+        let log_ctx = ProtectionContext::for_log();
+        assert_eq!(log_ctx.destination, DataDestination::Log);
+
+        let audit_ctx = ProtectionContext::for_audit(true);
+        assert_eq!(audit_ctx.destination, DataDestination::AuditExport);
+        assert!(audit_ctx.is_internal_audit);
+    }
+
+    #[test]
+    fn test_protection_context_with_tenant() {
+        let tenant_id = TenantId::from_string("tenant_123");
+        let ctx = ProtectionContext::for_stream().with_tenant(tenant_id);
+        assert!(ctx.tenant_id.is_some());
+        assert_eq!(ctx.tenant_id.unwrap().as_str(), "tenant_123");
+    }
+}

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

@@ -0,0 +1,289 @@
+//! Encryption Processor
+//!
+//! Output processor that encrypts sensitive data for storage destinations.
+//! Uses AES-256-GCM for symmetric encryption.
+//!
+//! @see docs/TECHNICAL/17-GUARDRAILS-PROTECTION.md
+
+use super::context::ProtectionContext;
+use super::processor::{OutputProcessor, ProcessedEvent};
+use crate::streaming::StreamEvent;
+use aes_gcm::{
+    aead::{Aead, KeyInit},
+    Aes256Gcm, Nonce,
+};
+use async_trait::async_trait;
+use rand::RngCore;
+
+/// 256-bit encryption key
+pub type EncryptionKey = [u8; 32];
+
+/// Encryption processor for storage destinations
+///
+/// Encrypts text content when the destination requires encryption (Storage).
+/// Streaming destinations receive the original (unencrypted) content.
+///
+/// ## Design Notes
+///
+/// This is a placeholder implementation. In production:
+/// - Use proper key derivation (HKDF)
+/// - Integrate with KMS (AWS KMS, GCP KMS, etc.)
+/// - Use envelope encryption for large payloads
+/// - Store nonces with ciphertext
+pub struct EncryptionProcessor {
+    /// Whether encryption is enabled
+    enabled: bool,
+    /// Symmetric key material
+    key: EncryptionKey,
+}
+
+impl EncryptionProcessor {
+    /// Create a new encryption processor (disabled by default)
+    pub fn new() -> Self {
+        Self {
+            enabled: false,
+            key: [0u8; 32],
+        }
+    }
+
+    /// Provide a specific encryption key (32 bytes)
+    pub fn with_key(mut self, key: EncryptionKey) -> Self {
+        self.key = key;
+        self
+    }
+
+    /// Enable encryption
+    pub fn enabled(mut self) -> Self {
+        self.enabled = true;
+        self
+    }
+
+    /// Check if encryption is enabled
+    pub fn is_enabled(&self) -> bool {
+        self.enabled
+    }
+
+    /// Encrypt a string using AES-256-GCM
+    fn encrypt_text(&self, text: &str) -> anyhow::Result<String> {
+        let key = aes_gcm::Key::<Aes256Gcm>::from_slice(&self.key);
+        let cipher = Aes256Gcm::new(key);
+
+        let mut nonce_bytes = [0u8; 12];
+        rand::thread_rng().fill_bytes(&mut nonce_bytes);
+        let nonce = Nonce::from_slice(&nonce_bytes);
+
+        let ciphertext = cipher
+            .encrypt(nonce, text.as_bytes())
+            .map_err(|e| anyhow::anyhow!("encryption failed: {:?}", e))?;
+
+        // Store nonce + ciphertext as hex for transport
+        let mut payload = Vec::with_capacity(nonce_bytes.len() + ciphertext.len());
+        payload.extend_from_slice(&nonce_bytes);
+        payload.extend_from_slice(&ciphertext);
+
+        Ok(format!("ENC:{}", hex::encode(payload)))
+    }
+
+    /// Check if event has text content that should be encrypted
+    fn should_encrypt_event(&self, event: &StreamEvent, ctx: &ProtectionContext) -> bool {
+        // Only encrypt for storage destination
+        if !ctx.destination.requires_encryption() {
+            return false;
+        }
+
+        // Check if event has sensitive content
+        matches!(
+            event,
+            StreamEvent::TextDelta { .. }
+                | StreamEvent::StepEnd {
+                    output: Some(_),
+                    ..
+                }
+                | StreamEvent::ExecutionEnd {
+                    final_output: Some(_),
+                    ..
+                }
+        )
+    }
+
+    /// Encrypt event content
+    fn encrypt_event(&self, event: StreamEvent) -> anyhow::Result<(StreamEvent, Option<String>)> {
+        match event {
+            StreamEvent::TextDelta { id, delta } => {
+                let encrypted = self.encrypt_text(&delta)?;
+                Ok((
+                    StreamEvent::TextDelta {
+                        id,
+                        delta: "[ENCRYPTED]".to_string(),
+                    },
+                    Some(encrypted),
+                ))
+            }
+            StreamEvent::StepEnd {
+                execution_id,
+                step_id,
+                output: Some(text),
+                duration_ms,
+                timestamp,
+            } => {
+                let encrypted = self.encrypt_text(&text)?;
+                Ok((
+                    StreamEvent::StepEnd {
+                        execution_id,
+                        step_id,
+                        output: Some("[ENCRYPTED]".to_string()),
+                        duration_ms,
+                        timestamp,
+                    },
+                    Some(encrypted),
+                ))
+            }
+            StreamEvent::ExecutionEnd {
+                execution_id,
+                final_output: Some(text),
+                duration_ms,
+                timestamp,
+            } => {
+                let encrypted = self.encrypt_text(&text)?;
+                Ok((
+                    StreamEvent::ExecutionEnd {
+                        execution_id,
+                        final_output: Some("[ENCRYPTED]".to_string()),
+                        duration_ms,
+                        timestamp,
+                    },
+                    Some(encrypted),
+                ))
+            }
+            _ => Ok((event, None)),
+        }
+    }
+}
+
+impl Default for EncryptionProcessor {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl OutputProcessor for EncryptionProcessor {
+    fn name(&self) -> &str {
+        "encryption"
+    }
+
+    async fn process(
+        &self,
+        event: StreamEvent,
+        ctx: &ProtectionContext,
+    ) -> anyhow::Result<ProcessedEvent> {
+        // Skip if not enabled
+        if !self.enabled {
+            return Ok(ProcessedEvent::unchanged(event));
+        }
+
+        // Skip if not storage destination
+        if !self.should_encrypt_event(&event, ctx) {
+            return Ok(ProcessedEvent::unchanged(event));
+        }
+
+        // Encrypt the event
+        let (encrypted_event, encrypted_payload) = self.encrypt_event(event)?;
+
+        Ok(ProcessedEvent {
+            event: encrypted_event,
+            was_modified: true,
+            encrypted_payload,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::kernel::ExecutionId;
+
+    #[tokio::test]
+    async fn test_encryption_processor_name() {
+        let processor = EncryptionProcessor::new();
+        assert_eq!(processor.name(), "encryption");
+    }
+
+    #[tokio::test]
+    async fn test_encryption_processor_disabled_by_default() {
+        let processor = EncryptionProcessor::new();
+        assert!(!processor.is_enabled());
+    }
+
+    #[tokio::test]
+    async fn test_encryption_processor_can_enable() {
+        let processor = EncryptionProcessor::new().enabled();
+        assert!(processor.is_enabled());
+    }
+
+    #[tokio::test]
+    async fn test_encryption_skips_when_disabled() {
+        let processor = EncryptionProcessor::new();
+        let ctx = ProtectionContext::for_storage();
+        let event = StreamEvent::text_delta("id", "secret data");
+
+        let result = processor.process(event, &ctx).await.unwrap();
+
+        // Should pass through unchanged
+        assert!(!result.was_modified);
+    }
+
+    #[tokio::test]
+    async fn test_encryption_skips_streaming_destination() {
+        let processor = EncryptionProcessor::new().enabled();
+        let ctx = ProtectionContext::for_stream(); // Not storage
+        let event = StreamEvent::text_delta("id", "secret data");
+
+        let result = processor.process(event, &ctx).await.unwrap();
+
+        // Should pass through unchanged (streaming doesn't encrypt)
+        assert!(!result.was_modified);
+    }
+
+    #[tokio::test]
+    async fn test_encryption_encrypts_for_storage() {
+        let processor = EncryptionProcessor::new()
+            .with_key([1u8; 32])
+            .enabled();
+        let ctx = ProtectionContext::for_storage();
+        let event = StreamEvent::text_delta("id", "secret data");
+
+        let result = processor.process(event, &ctx).await.unwrap();
+
+        // Should be modified
+        assert!(result.was_modified);
+
+        // Event should show [ENCRYPTED]
+        if let StreamEvent::TextDelta { delta, .. } = result.event {
+            assert_eq!(delta, "[ENCRYPTED]");
+        } else {
+            panic!("Expected TextDelta");
+        }
+
+        // Encrypted payload should exist
+        let payload = result.encrypted_payload.expect("expected encrypted payload");
+        assert!(payload.starts_with("ENC:"));
+        assert!(
+            !payload.contains("secret data"),
+            "ciphertext should not contain plaintext"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_encryption_control_events_pass_through() {
+        let processor = EncryptionProcessor::new().enabled();
+        let ctx = ProtectionContext::for_storage();
+        let exec_id = ExecutionId::new();
+        let event = StreamEvent::execution_start(&exec_id);
+
+        let result = processor.process(event, &ctx).await.unwrap();
+
+        // Control events should pass through unchanged
+        assert!(!result.was_modified);
+    }
+}