enya-agent 0.1.0

package/crates/enact-core/src/background/executor.rs

@@ -0,0 +1,524 @@
+//! Background Executor - Runs callables in background mode
+//!
+//! The executor handles different background execution modes:
+//! - FireAndForget: Don't wait for result, no streaming
+//! - Silent: Wait for result, but suppress streaming events
+//! - Deferred: Queue for later execution
+//!
+//! @see packages/enact-schemas/src/execution.schemas.ts
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+use crate::kernel::ids::{ExecutionId, SpawnMode, TenantId};
+use crate::kernel::ExecutionError;
+
+use super::target_binding::TargetBindingConfig;
+use super::trigger::{RetryConfig, TriggerId};
+
+/// BackgroundExecutionMode - How to run a background callable
+/// @see packages/enact-schemas/src/execution.schemas.ts - backgroundExecutionModeSchema
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum BackgroundExecutionMode {
+    /// Don't wait for result, no streaming
+    #[default]
+    FireAndForget,
+    /// Wait for result, but no streaming
+    Silent,
+    /// Queue for later execution
+    Deferred,
+}
+
+/// BackgroundExecutionStatus - Status of a background execution
+/// @see packages/enact-schemas/src/execution.schemas.ts - backgroundExecutionStatusSchema
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum BackgroundExecutionStatus {
+    /// Waiting to execute
+    #[default]
+    Queued,
+    /// Currently executing
+    Running,
+    /// Finished successfully
+    Completed,
+    /// Failed with error
+    Failed,
+    /// Cancelled before completion
+    Cancelled,
+    /// Exceeded timeout
+    Timeout,
+}
+
+/// BackgroundExecutionConfig - Configuration for background execution
+/// @see packages/enact-schemas/src/execution.schemas.ts - backgroundExecutionConfigSchema
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BackgroundExecutionConfig {
+    /// Execution mode
+    #[serde(default)]
+    pub mode: BackgroundExecutionMode,
+
+    /// Priority (higher = runs sooner)
+    #[serde(default = "default_priority")]
+    pub priority: u8,
+
+    /// Maximum execution time in milliseconds
+    #[serde(default = "default_timeout_ms")]
+    pub timeout_ms: u64,
+
+    /// Target binding for result
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub target_binding: Option<TargetBindingConfig>,
+
+    /// Callback URL (for deferred mode)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub callback_url: Option<String>,
+
+    /// Retry configuration
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub retry: Option<RetryConfig>,
+}
+
+fn default_priority() -> u8 {
+    50
+}
+
+fn default_timeout_ms() -> u64 {
+    300000 // 5 minutes
+}
+
+impl Default for BackgroundExecutionConfig {
+    fn default() -> Self {
+        Self {
+            mode: BackgroundExecutionMode::FireAndForget,
+            priority: default_priority(),
+            timeout_ms: default_timeout_ms(),
+            target_binding: None,
+            callback_url: None,
+            retry: None,
+        }
+    }
+}
+
+/// BackgroundExecution - A background execution record
+/// @see packages/enact-schemas/src/execution.schemas.ts - backgroundExecutionSchema
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BackgroundExecution {
+    /// Execution ID
+    pub execution_id: ExecutionId,
+
+    /// Tenant that owns this execution
+    pub tenant_id: TenantId,
+
+    /// Callable to invoke
+    pub callable_name: String,
+
+    /// Input to pass to the callable
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub input: Option<String>,
+
+    /// Context to pass
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub context: Option<HashMap<String, String>>,
+
+    /// Configuration
+    pub config: BackgroundExecutionConfig,
+
+    /// Current status
+    #[serde(default)]
+    pub status: BackgroundExecutionStatus,
+
+    /// When execution was queued
+    pub queued_at: DateTime<Utc>,
+
+    /// When execution started
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub started_at: Option<DateTime<Utc>>,
+
+    /// When execution completed
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub completed_at: Option<DateTime<Utc>>,
+
+    /// Output (populated on completion)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub output: Option<serde_json::Value>,
+
+    /// Error (populated on failure)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<ExecutionError>,
+
+    /// Whether target binding was applied
+    #[serde(default)]
+    pub target_binding_applied: bool,
+
+    /// Trigger that spawned this execution (if any)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub trigger_id: Option<TriggerId>,
+
+    /// Metadata
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub metadata: Option<HashMap<String, serde_json::Value>>,
+}
+
+impl BackgroundExecution {
+    /// Create a new background execution
+    pub fn new(
+        tenant_id: TenantId,
+        callable_name: impl Into<String>,
+        config: BackgroundExecutionConfig,
+    ) -> Self {
+        Self {
+            execution_id: ExecutionId::new(),
+            tenant_id,
+            callable_name: callable_name.into(),
+            input: None,
+            context: None,
+            config,
+            status: BackgroundExecutionStatus::Queued,
+            queued_at: Utc::now(),
+            started_at: None,
+            completed_at: None,
+            output: None,
+            error: None,
+            target_binding_applied: false,
+            trigger_id: None,
+            metadata: None,
+        }
+    }
+
+    /// Create from a trigger
+    pub fn from_trigger(
+        tenant_id: TenantId,
+        trigger_id: TriggerId,
+        callable_name: impl Into<String>,
+        input: Option<String>,
+        context: Option<HashMap<String, String>>,
+        target_binding: Option<TargetBindingConfig>,
+        retry: Option<RetryConfig>,
+    ) -> Self {
+        let config = BackgroundExecutionConfig {
+            mode: BackgroundExecutionMode::Silent,
+            target_binding,
+            retry,
+            ..Default::default()
+        };
+
+        let mut execution = Self::new(tenant_id, callable_name, config);
+        execution.trigger_id = Some(trigger_id);
+        execution.input = input;
+        execution.context = context;
+        execution
+    }
+
+    /// Create from SpawnMode::Child
+    ///
+    /// This bridges the gap between SpawnMode::Child { background: true, .. }
+    /// and the BackgroundExecution infrastructure.
+    ///
+    /// @see docs/TECHNICAL/32-SPAWN-MODE.md
+    pub fn from_spawn_mode(
+        spawn_mode: &SpawnMode,
+        tenant_id: TenantId,
+        callable_name: impl Into<String>,
+        input: Option<String>,
+        context: Option<HashMap<String, String>>,
+    ) -> Option<Self> {
+        match spawn_mode {
+            SpawnMode::Child { background: true, .. } => {
+                // Background=true means fire-and-forget execution
+                let config = BackgroundExecutionConfig {
+                    mode: BackgroundExecutionMode::FireAndForget,
+                    ..Default::default()
+                };
+
+                let mut execution = Self::new(tenant_id, callable_name, config);
+                execution.input = input;
+                execution.context = context;
+                Some(execution)
+            }
+            SpawnMode::Child { background: false, .. } => {
+                // Background=false means inline execution - not a background execution
+                None
+            }
+            SpawnMode::Inline => {
+                // Inline mode doesn't create a separate execution
+                None
+            }
+        }
+    }
+
+    /// Check if a SpawnMode should create a background execution
+    pub fn should_run_background(spawn_mode: &SpawnMode) -> bool {
+        matches!(spawn_mode, SpawnMode::Child { background: true, .. })
+    }
+
+    /// Mark execution as started
+    pub fn start(&mut self) {
+        self.status = BackgroundExecutionStatus::Running;
+        self.started_at = Some(Utc::now());
+    }
+
+    /// Mark execution as completed
+    pub fn complete(&mut self, output: serde_json::Value) {
+        self.status = BackgroundExecutionStatus::Completed;
+        self.completed_at = Some(Utc::now());
+        self.output = Some(output);
+    }
+
+    /// Mark execution as failed
+    pub fn fail(&mut self, error: ExecutionError) {
+        self.status = BackgroundExecutionStatus::Failed;
+        self.completed_at = Some(Utc::now());
+        self.error = Some(error);
+    }
+
+    /// Mark execution as cancelled
+    pub fn cancel(&mut self) {
+        self.status = BackgroundExecutionStatus::Cancelled;
+        self.completed_at = Some(Utc::now());
+    }
+
+    /// Mark execution as timed out
+    pub fn timeout(&mut self) {
+        self.status = BackgroundExecutionStatus::Timeout;
+        self.completed_at = Some(Utc::now());
+    }
+
+    /// Check if execution has completed (successfully or not)
+    pub fn is_finished(&self) -> bool {
+        matches!(
+            self.status,
+            BackgroundExecutionStatus::Completed
+                | BackgroundExecutionStatus::Failed
+                | BackgroundExecutionStatus::Cancelled
+                | BackgroundExecutionStatus::Timeout
+        )
+    }
+
+    /// Check if execution succeeded
+    pub fn is_success(&self) -> bool {
+        self.status == BackgroundExecutionStatus::Completed
+    }
+
+    /// Calculate execution duration
+    pub fn duration_ms(&self) -> Option<i64> {
+        match (self.started_at, self.completed_at) {
+            (Some(start), Some(end)) => Some((end - start).num_milliseconds()),
+            _ => None,
+        }
+    }
+
+    /// Check if execution should suppress streaming events (silent mode)
+    pub fn is_silent(&self) -> bool {
+        matches!(
+            self.config.mode,
+            BackgroundExecutionMode::Silent | BackgroundExecutionMode::FireAndForget
+        )
+    }
+
+    /// Check if execution requires waiting for result
+    pub fn requires_result(&self) -> bool {
+        matches!(self.config.mode, BackgroundExecutionMode::Silent)
+    }
+}
+
+/// BackgroundExecutionQueue - Queue for managing background executions
+/// This is an in-memory implementation for testing. Production uses Redis/Postgres.
+#[derive(Debug, Default)]
+pub struct BackgroundExecutionQueue {
+    executions: std::collections::VecDeque<BackgroundExecution>,
+}
+
+impl BackgroundExecutionQueue {
+    /// Create a new empty queue
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Enqueue a new execution
+    pub fn enqueue(&mut self, execution: BackgroundExecution) {
+        // Insert based on priority (higher priority first)
+        let pos = self
+            .executions
+            .iter()
+            .position(|e| e.config.priority < execution.config.priority)
+            .unwrap_or(self.executions.len());
+        self.executions.insert(pos, execution);
+    }
+
+    /// Dequeue the next execution to run
+    pub fn dequeue(&mut self) -> Option<BackgroundExecution> {
+        self.executions.pop_front()
+    }
+
+    /// Peek at the next execution without removing it
+    pub fn peek(&self) -> Option<&BackgroundExecution> {
+        self.executions.front()
+    }
+
+    /// Get queue length
+    pub fn len(&self) -> usize {
+        self.executions.len()
+    }
+
+    /// Check if queue is empty
+    pub fn is_empty(&self) -> bool {
+        self.executions.is_empty()
+    }
+
+    /// Get all queued execution IDs
+    pub fn execution_ids(&self) -> Vec<ExecutionId> {
+        self.executions.iter().map(|e| e.execution_id.clone()).collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_background_execution_modes() {
+        // Test fire and forget
+        let config = BackgroundExecutionConfig {
+            mode: BackgroundExecutionMode::FireAndForget,
+            ..Default::default()
+        };
+        let exec = BackgroundExecution::new(TenantId::new(), "test", config);
+        assert!(exec.is_silent());
+        assert!(!exec.requires_result());
+
+        // Test silent
+        let config = BackgroundExecutionConfig {
+            mode: BackgroundExecutionMode::Silent,
+            ..Default::default()
+        };
+        let exec = BackgroundExecution::new(TenantId::new(), "test", config);
+        assert!(exec.is_silent());
+        assert!(exec.requires_result());
+
+        // Test deferred
+        let config = BackgroundExecutionConfig {
+            mode: BackgroundExecutionMode::Deferred,
+            ..Default::default()
+        };
+        let exec = BackgroundExecution::new(TenantId::new(), "test", config);
+        assert!(!exec.is_silent());
+        assert!(!exec.requires_result());
+    }
+
+    #[test]
+    fn test_background_execution_lifecycle() {
+        let config = BackgroundExecutionConfig::default();
+        let mut exec = BackgroundExecution::new(TenantId::new(), "test", config);
+
+        assert_eq!(exec.status, BackgroundExecutionStatus::Queued);
+        assert!(!exec.is_finished());
+
+        exec.start();
+        assert_eq!(exec.status, BackgroundExecutionStatus::Running);
+        assert!(exec.started_at.is_some());
+
+        exec.complete(serde_json::json!({"result": "success"}));
+        assert_eq!(exec.status, BackgroundExecutionStatus::Completed);
+        assert!(exec.is_finished());
+        assert!(exec.is_success());
+        assert!(exec.output.is_some());
+        assert!(exec.duration_ms().is_some());
+    }
+
+    #[test]
+    fn test_background_execution_queue() {
+        let mut queue = BackgroundExecutionQueue::new();
+        assert!(queue.is_empty());
+
+        // Add low priority
+        let low = BackgroundExecution::new(
+            TenantId::new(),
+            "low",
+            BackgroundExecutionConfig {
+                priority: 10,
+                ..Default::default()
+            },
+        );
+        queue.enqueue(low);
+
+        // Add high priority
+        let high = BackgroundExecution::new(
+            TenantId::new(),
+            "high",
+            BackgroundExecutionConfig {
+                priority: 90,
+                ..Default::default()
+            },
+        );
+        queue.enqueue(high);
+
+        assert_eq!(queue.len(), 2);
+
+        // High priority should come first
+        let first = queue.dequeue().unwrap();
+        assert_eq!(first.callable_name, "high");
+
+        let second = queue.dequeue().unwrap();
+        assert_eq!(second.callable_name, "low");
+
+        assert!(queue.is_empty());
+    }
+
+    #[test]
+    fn test_spawn_mode_integration() {
+        let tenant_id = TenantId::new();
+
+        // SpawnMode::Child with background=true creates a background execution
+        let spawn_mode = SpawnMode::Child {
+            background: true,
+            inherit_inbox: false,
+            policies: None,
+        };
+        assert!(BackgroundExecution::should_run_background(&spawn_mode));
+
+        let exec = BackgroundExecution::from_spawn_mode(
+            &spawn_mode,
+            tenant_id.clone(),
+            "background_callable",
+            Some("input data".to_string()),
+            None,
+        );
+        assert!(exec.is_some());
+        let exec = exec.unwrap();
+        assert_eq!(exec.callable_name, "background_callable");
+        assert_eq!(exec.config.mode, BackgroundExecutionMode::FireAndForget);
+        assert!(exec.is_silent());
+
+        // SpawnMode::Child with background=false does not create a background execution
+        let spawn_mode = SpawnMode::Child {
+            background: false,
+            inherit_inbox: false,
+            policies: None,
+        };
+        assert!(!BackgroundExecution::should_run_background(&spawn_mode));
+        let exec = BackgroundExecution::from_spawn_mode(
+            &spawn_mode,
+            tenant_id.clone(),
+            "sync_callable",
+            None,
+            None,
+        );
+        assert!(exec.is_none());
+
+        // SpawnMode::Inline does not create a background execution
+        let spawn_mode = SpawnMode::Inline;
+        assert!(!BackgroundExecution::should_run_background(&spawn_mode));
+        let exec = BackgroundExecution::from_spawn_mode(
+            &spawn_mode,
+            tenant_id,
+            "inline_callable",
+            None,
+            None,
+        );
+        assert!(exec.is_none());
+    }
+}

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

@@ -0,0 +1,48 @@
+//! Background Module - Background execution and triggers
+//!
+//! This module provides the infrastructure for background callable execution:
+//!
+//! - **Triggers**: Event-based callable invocation
+//! - **Executor**: Background execution with different modes
+//! - **Target Binding**: Binds execution results to targets
+//!
+//! ## Background Execution Modes
+//!
+//! - `FireAndForget`: Don't wait for result, no streaming
+//! - `Silent`: Wait for result, but suppress streaming events
+//! - `Deferred`: Queue for later execution
+//!
+//! ## Triggers
+//!
+//! Triggers watch for specific events and spawn background executions:
+//! - Event: Fired by execution/step events
+//! - Schedule: Fired by cron/interval schedules
+//! - Webhook: Fired by external webhooks
+//! - Threshold: Fired when metrics cross thresholds
+//! - Lifecycle: Fired by thread/user lifecycle events
+//!
+//! @see packages/enact-schemas/src/execution.schemas.ts
+//! @see docs/TECHNICAL/32-SPAWN-MODE.md
+
+pub mod executor;
+pub mod target_binding;
+pub mod trigger;
+
+// Re-exports - Trigger
+pub use trigger::{
+    RetryConfig, TargetBindingConfig as TriggerTargetBindingConfig, TargetBindingType as TriggerTargetBindingType,
+    ThresholdOperator, Trigger, TriggerAction, TriggerCondition, TriggerFiredEvent, TriggerId,
+    TriggerStatus, TriggerType,
+};
+
+// Re-exports - Executor
+pub use executor::{
+    BackgroundExecution, BackgroundExecutionConfig, BackgroundExecutionMode,
+    BackgroundExecutionQueue, BackgroundExecutionStatus,
+};
+
+// Re-exports - Target Binding
+pub use target_binding::{
+    apply_transform, TargetBindingConfig, TargetBindingResult, TargetBindingTransform,
+    TargetBindingType,
+};