enya-agent 0.1.0

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

@@ -0,0 +1,511 @@
+//! Trigger System for Background Callables
+//!
+//! Triggers enable event-based callable invocation. A trigger watches for
+//! specific events and spawns background executions when conditions are met.
+//!
+//! ## Trigger Types
+//!
+//! - **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
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use svix_ksuid::KsuidLike;
+
+use crate::kernel::ids::{ExecutionId, TenantId};
+
+/// TriggerId - Unique identifier for a trigger
+/// Format: trigger_[27-char KSUID]
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct TriggerId(String);
+
+impl TriggerId {
+    /// Create a new TriggerId
+    pub fn new() -> Self {
+        Self(format!("trigger_{}", svix_ksuid::Ksuid::new(None, None)))
+    }
+
+    /// Create from string (for deserialization)
+    pub fn from_string(s: String) -> Self {
+        Self(s)
+    }
+
+    /// Get the inner string
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl Default for TriggerId {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl std::fmt::Display for TriggerId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+/// TriggerType - What kind of trigger this is
+/// @see packages/enact-schemas/src/execution.schemas.ts - triggerTypeSchema
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TriggerType {
+    /// Fired by an event (e.g., execution.completed, step.failed)
+    Event,
+    /// Fired by a schedule (cron, interval)
+    Schedule,
+    /// Fired by an external webhook
+    Webhook,
+    /// Fired when a metric crosses a threshold
+    Threshold,
+    /// Fired manually by user
+    Manual,
+    /// Fired by lifecycle events (thread.created, user.signup)
+    Lifecycle,
+}
+
+/// TriggerStatus - Current status of a trigger
+/// @see packages/enact-schemas/src/execution.schemas.ts - triggerStatusSchema
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum TriggerStatus {
+    /// Trigger is active and will fire
+    #[default]
+    Active,
+    /// Trigger is paused (won't fire)
+    Paused,
+    /// Trigger is disabled (won't fire, hidden)
+    Disabled,
+    /// Trigger has fired (for one-shot triggers)
+    Fired,
+    /// Trigger has expired (past end_at)
+    Expired,
+}
+
+/// ThresholdOperator - Comparison operator for threshold triggers
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ThresholdOperator {
+    Gt,
+    Gte,
+    Lt,
+    Lte,
+    Eq,
+    Neq,
+}
+
+/// TriggerCondition - When the trigger should fire
+/// @see packages/enact-schemas/src/execution.schemas.ts - triggerConditionSchema
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TriggerCondition {
+    /// Event type to match (for event triggers)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub event_type: Option<String>,
+
+    /// Pattern to match against event data
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub event_pattern: Option<HashMap<String, serde_json::Value>>,
+
+    /// Cron expression (for schedule triggers)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cron_expression: Option<String>,
+
+    /// Interval in seconds (for schedule triggers)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub interval_seconds: Option<u64>,
+
+    /// Metric name (for threshold triggers)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub metric_name: Option<String>,
+
+    /// Threshold value (for threshold triggers)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub threshold_value: Option<f64>,
+
+    /// Threshold operator
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub threshold_operator: Option<ThresholdOperator>,
+}
+
+/// RetryConfig - Configuration for retry behavior
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RetryConfig {
+    /// Maximum number of retry attempts
+    #[serde(default = "default_max_attempts")]
+    pub max_attempts: u32,
+
+    /// Initial backoff in milliseconds
+    #[serde(default = "default_backoff_ms")]
+    pub backoff_ms: u64,
+
+    /// Backoff multiplier for exponential backoff
+    #[serde(default = "default_backoff_multiplier")]
+    pub backoff_multiplier: f64,
+}
+
+fn default_max_attempts() -> u32 {
+    3
+}
+
+fn default_backoff_ms() -> u64 {
+    1000
+}
+
+fn default_backoff_multiplier() -> f64 {
+    2.0
+}
+
+impl Default for RetryConfig {
+    fn default() -> Self {
+        Self {
+            max_attempts: default_max_attempts(),
+            backoff_ms: default_backoff_ms(),
+            backoff_multiplier: default_backoff_multiplier(),
+        }
+    }
+}
+
+/// TargetBindingConfig - Where to write the result
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TargetBindingConfig {
+    /// Target type (where to write the result)
+    pub target_type: TargetBindingType,
+
+    /// Custom target path (for custom target type)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub target_path: Option<String>,
+}
+
+/// TargetBindingType - What kind of target to bind to
+/// @see packages/enact-schemas/src/execution.schemas.ts - targetBindingTypeSchema
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TargetBindingType {
+    /// Set thread title
+    #[serde(rename = "thread.title")]
+    ThreadTitle,
+    /// Set thread summary
+    #[serde(rename = "thread.summary")]
+    ThreadSummary,
+    /// Set execution summary
+    #[serde(rename = "execution.summary")]
+    ExecutionSummary,
+    /// Add to message metadata
+    #[serde(rename = "message.metadata")]
+    MessageMetadata,
+    /// Create an artifact
+    #[serde(rename = "artifact.create")]
+    ArtifactCreate,
+    /// Write to memory
+    #[serde(rename = "memory.write")]
+    MemoryWrite,
+    /// Custom target (requires targetPath)
+    Custom,
+}
+
+/// TriggerAction - What to do when the trigger fires
+/// @see packages/enact-schemas/src/execution.schemas.ts - triggerActionSchema
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TriggerAction {
+    /// 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>>,
+
+    /// System prompt override
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub system_prompt: Option<String>,
+
+    /// Target binding for the result
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub target_binding: Option<TargetBindingConfig>,
+
+    /// Execute in background (fire-and-forget)
+    #[serde(default = "default_background")]
+    pub background: bool,
+
+    /// Retry configuration
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub retry: Option<RetryConfig>,
+}
+
+fn default_background() -> bool {
+    true
+}
+
+/// Trigger - Event-based callable invocation definition
+/// @see packages/enact-schemas/src/execution.schemas.ts - triggerSchema
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Trigger {
+    /// Unique trigger identifier
+    pub trigger_id: TriggerId,
+
+    /// Tenant that owns this trigger
+    pub tenant_id: TenantId,
+
+    /// Human-readable name
+    pub name: String,
+
+    /// Optional description
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+
+    /// Trigger type
+    #[serde(rename = "type")]
+    pub trigger_type: TriggerType,
+
+    /// Current status
+    #[serde(default)]
+    pub status: TriggerStatus,
+
+    /// Condition (when to fire)
+    pub condition: TriggerCondition,
+
+    /// Action (what to do when fired)
+    pub action: TriggerAction,
+
+    /// When to start listening
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub start_at: Option<DateTime<Utc>>,
+
+    /// When to stop (expire)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub end_at: Option<DateTime<Utc>>,
+
+    /// Max times to fire (None = unlimited)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_fires: Option<u32>,
+
+    /// Times fired so far
+    #[serde(default)]
+    pub fire_count: u32,
+
+    /// Cooldown in milliseconds (prevent rapid re-firing)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cooldown_ms: Option<u64>,
+
+    /// Last time this trigger fired
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_fired_at: Option<DateTime<Utc>>,
+
+    /// When the trigger was created
+    pub created_at: DateTime<Utc>,
+
+    /// When the trigger was last updated
+    pub updated_at: DateTime<Utc>,
+}
+
+impl Trigger {
+    /// Create a new trigger
+    pub fn new(
+        tenant_id: TenantId,
+        name: impl Into<String>,
+        trigger_type: TriggerType,
+        condition: TriggerCondition,
+        action: TriggerAction,
+    ) -> Self {
+        let now = Utc::now();
+        Self {
+            trigger_id: TriggerId::new(),
+            tenant_id,
+            name: name.into(),
+            description: None,
+            trigger_type,
+            status: TriggerStatus::Active,
+            condition,
+            action,
+            start_at: None,
+            end_at: None,
+            max_fires: None,
+            fire_count: 0,
+            cooldown_ms: None,
+            last_fired_at: None,
+            created_at: now,
+            updated_at: now,
+        }
+    }
+
+    /// Check if the trigger can fire right now
+    pub fn can_fire(&self) -> bool {
+        // Must be active
+        if self.status != TriggerStatus::Active {
+            return false;
+        }
+
+        let now = Utc::now();
+
+        // Check start_at
+        if let Some(start_at) = self.start_at {
+            if now < start_at {
+                return false;
+            }
+        }
+
+        // Check end_at
+        if let Some(end_at) = self.end_at {
+            if now > end_at {
+                return false;
+            }
+        }
+
+        // Check max_fires
+        if let Some(max_fires) = self.max_fires {
+            if self.fire_count >= max_fires {
+                return false;
+            }
+        }
+
+        // Check cooldown
+        if let (Some(cooldown_ms), Some(last_fired_at)) = (self.cooldown_ms, self.last_fired_at) {
+            let cooldown = chrono::Duration::milliseconds(cooldown_ms as i64);
+            if now < last_fired_at + cooldown {
+                return false;
+            }
+        }
+
+        true
+    }
+
+    /// Record that the trigger fired
+    pub fn record_fire(&mut self) {
+        self.fire_count += 1;
+        self.last_fired_at = Some(Utc::now());
+        self.updated_at = Utc::now();
+
+        // Check if we've hit max_fires
+        if let Some(max_fires) = self.max_fires {
+            if self.fire_count >= max_fires {
+                self.status = TriggerStatus::Fired;
+            }
+        }
+    }
+
+    /// Pause the trigger
+    pub fn pause(&mut self) {
+        self.status = TriggerStatus::Paused;
+        self.updated_at = Utc::now();
+    }
+
+    /// Resume the trigger
+    pub fn resume(&mut self) {
+        if self.status == TriggerStatus::Paused {
+            self.status = TriggerStatus::Active;
+            self.updated_at = Utc::now();
+        }
+    }
+
+    /// Disable the trigger
+    pub fn disable(&mut self) {
+        self.status = TriggerStatus::Disabled;
+        self.updated_at = Utc::now();
+    }
+}
+
+/// TriggerFiredEvent - Emitted when a trigger fires
+/// @see packages/enact-schemas/src/execution.schemas.ts - triggerFiredEventSchema
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TriggerFiredEvent {
+    pub trigger_id: TriggerId,
+    pub trigger_name: String,
+    pub trigger_type: TriggerType,
+    pub execution_id: ExecutionId,
+    pub fired_at: DateTime<Utc>,
+    pub trigger_source: serde_json::Value,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_trigger_id_generation() {
+        let id = TriggerId::new();
+        assert!(id.as_str().starts_with("trigger_"));
+        assert_eq!(id.as_str().len(), 35); // "trigger_" + 27 chars
+    }
+
+    #[test]
+    fn test_trigger_can_fire() {
+        let tenant_id = TenantId::new();
+        let condition = TriggerCondition {
+            event_type: Some("execution.completed".to_string()),
+            ..Default::default()
+        };
+        let action = TriggerAction {
+            callable_name: "summarizer".to_string(),
+            input: None,
+            context: None,
+            system_prompt: None,
+            target_binding: Some(TargetBindingConfig {
+                target_type: TargetBindingType::ThreadTitle,
+                target_path: None,
+            }),
+            background: true,
+            retry: None,
+        };
+
+        let mut trigger = Trigger::new(
+            tenant_id,
+            "Auto-title",
+            TriggerType::Event,
+            condition,
+            action,
+        );
+
+        assert!(trigger.can_fire());
+
+        // Record fire and check again
+        trigger.record_fire();
+        assert_eq!(trigger.fire_count, 1);
+        assert!(trigger.last_fired_at.is_some());
+    }
+
+    #[test]
+    fn test_trigger_max_fires() {
+        let tenant_id = TenantId::new();
+        let mut trigger = Trigger::new(
+            tenant_id,
+            "One-shot",
+            TriggerType::Event,
+            TriggerCondition::default(),
+            TriggerAction {
+                callable_name: "task".to_string(),
+                input: None,
+                context: None,
+                system_prompt: None,
+                target_binding: None,
+                background: true,
+                retry: None,
+            },
+        );
+
+        trigger.max_fires = Some(1);
+
+        assert!(trigger.can_fire());
+        trigger.record_fire();
+        assert!(!trigger.can_fire());
+        assert_eq!(trigger.status, TriggerStatus::Fired);
+    }
+}

package/crates/enact-core/src/callable/callable.rs

@@ -0,0 +1,152 @@
+//! Callable trait definition
+//!
+//! The core abstraction for anything that can be invoked.
+
+use async_trait::async_trait;
+use std::sync::Arc;
+
+/// Core Callable trait - the fundamental execution unit
+///
+/// Everything that can be "run" implements this trait:
+/// - LLM agents
+/// - Graph nodes
+/// - Tools (when wrapped)
+/// - Flow compositions
+///
+/// ## Design Principles
+///
+/// 1. **Simple**: Just run with input, get output
+/// 2. **Async**: All execution is async by default
+/// 3. **Named**: Every callable has a name for logging/debugging
+/// 4. **Composable**: Callables can wrap other callables
+#[async_trait]
+pub trait Callable: Send + Sync {
+    /// Callable logical name (for logging, debugging, UI)
+    fn name(&self) -> &str;
+
+    /// Callable description (optional, for documentation)
+    fn description(&self) -> Option<&str> {
+        None
+    }
+
+    /// Execute the callable with the given input
+    ///
+    /// This is the core execution method. Implementations should:
+    /// - Be idempotent when possible
+    /// - Handle their own retries if needed
+    /// - Return meaningful error messages
+    async fn run(&self, input: &str) -> anyhow::Result<String>;
+}
+
+/// Boxed callable for dynamic dispatch
+///
+/// Use this when you need to store heterogeneous callables together
+/// or pass them through dynamic boundaries.
+pub type DynCallable = Arc<dyn Callable>;
+
+/// A simple function-based callable
+///
+/// Wraps a closure to implement Callable.
+#[allow(dead_code)]
+pub struct FnCallable<F>
+where
+    F: Fn(&str) -> anyhow::Result<String> + Send + Sync,
+{
+    name: String,
+    description: Option<String>,
+    func: F,
+}
+
+#[allow(dead_code)]
+impl<F> FnCallable<F>
+where
+    F: Fn(&str) -> anyhow::Result<String> + Send + Sync,
+{
+    /// Create a new function-based callable
+    pub fn new(name: impl Into<String>, func: F) -> Self {
+        Self {
+            name: name.into(),
+            description: None,
+            func,
+        }
+    }
+
+    /// Add a description
+    pub fn with_description(mut self, desc: impl Into<String>) -> Self {
+        self.description = Some(desc.into());
+        self
+    }
+}
+
+#[async_trait]
+impl<F> Callable for FnCallable<F>
+where
+    F: Fn(&str) -> anyhow::Result<String> + Send + Sync,
+{
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn description(&self) -> Option<&str> {
+        self.description.as_deref()
+    }
+
+    async fn run(&self, input: &str) -> anyhow::Result<String> {
+        (self.func)(input)
+    }
+}
+
+/// Create a callable from an async function
+#[allow(dead_code)]
+pub struct AsyncFnCallable<F, Fut>
+where
+    F: Fn(String) -> Fut + Send + Sync,
+    Fut: std::future::Future<Output = anyhow::Result<String>> + Send + Sync,
+{
+    name: String,
+    description: Option<String>,
+    func: F,
+    _phantom: std::marker::PhantomData<fn() -> Fut>,
+}
+
+#[allow(dead_code)]
+impl<F, Fut> AsyncFnCallable<F, Fut>
+where
+    F: Fn(String) -> Fut + Send + Sync,
+    Fut: std::future::Future<Output = anyhow::Result<String>> + Send + Sync,
+{
+    /// Create a new async function-based callable
+    pub fn new(name: impl Into<String>, func: F) -> Self {
+        Self {
+            name: name.into(),
+            description: None,
+            func,
+            _phantom: std::marker::PhantomData,
+        }
+    }
+
+    /// Add a description
+    pub fn with_description(mut self, desc: impl Into<String>) -> Self {
+        self.description = Some(desc.into());
+        self
+    }
+}
+
+#[async_trait]
+impl<F, Fut> Callable for AsyncFnCallable<F, Fut>
+where
+    F: Fn(String) -> Fut + Send + Sync,
+    Fut: std::future::Future<Output = anyhow::Result<String>> + Send + Sync,
+{
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn description(&self) -> Option<&str> {
+        self.description.as_deref()
+    }
+
+    async fn run(&self, input: &str) -> anyhow::Result<String> {
+        (self.func)(input.to_string()).await
+    }
+}