enya-agent 0.1.0

package/crates/enact-core/src/kernel/replay.rs

@@ -0,0 +1,153 @@
+//! Replay - Re-execute from event log
+//!
+//! Replay enables:
+//! - Debugging: re-run an execution to understand what happened
+//! - Testing: verify determinism by replaying
+//! - Recovery: resume from a checkpoint
+//!
+//! Replay requires:
+//! - Matching schema version
+//! - Ordered event log
+
+use super::execution_model::Execution;
+use super::reducer::{reduce, ExecutionAction, ReducerError};
+use super::ids::ExecutionId;
+
+/// Replay an execution from an action log
+///
+/// This will recreate the execution state by applying each action
+/// through the reducer, ensuring deterministic reconstruction.
+pub fn replay(
+    execution_id: ExecutionId,
+    actions: Vec<ExecutionAction>,
+    schema_version: Option<&str>,
+) -> Result<Execution, ReplayError> {
+    let mut execution = Execution::with_id(execution_id);
+
+    // Set schema version for validation
+    if let Some(version) = schema_version {
+        execution.schema_version = Some(version.to_string());
+    }
+
+    // Apply each action through the reducer
+    for (index, action) in actions.into_iter().enumerate() {
+        reduce(&mut execution, action).map_err(|e| ReplayError::ReducerError {
+            index,
+            error: e,
+        })?;
+    }
+
+    Ok(execution)
+}
+
+/// Replay error
+#[derive(Debug, thiserror::Error)]
+pub enum ReplayError {
+    #[error("Reducer error at action {index}: {error}")]
+    ReducerError {
+        index: usize,
+        error: ReducerError,
+    },
+    #[error("Schema version mismatch: expected {expected}, got {actual}")]
+    SchemaVersionMismatch {
+        expected: String,
+        actual: String,
+    },
+}
+
+/// Event log for replay
+///
+/// This is a simple in-memory log. In production, you'd persist this
+/// to a database or event store.
+#[derive(Debug, Default)]
+pub struct EventLog {
+    /// Ordered list of actions
+    actions: Vec<ExecutionAction>,
+}
+
+impl EventLog {
+    /// Create a new event log
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Append an action to the log
+    pub fn append(&mut self, action: ExecutionAction) {
+        self.actions.push(action);
+    }
+
+    /// Get all actions
+    pub fn actions(&self) -> &[ExecutionAction] {
+        &self.actions
+    }
+
+    /// Take all actions (consumes the log)
+    pub fn into_actions(self) -> Vec<ExecutionAction> {
+        self.actions
+    }
+
+    /// Get action count
+    pub fn len(&self) -> usize {
+        self.actions.len()
+    }
+
+    /// Check if empty
+    pub fn is_empty(&self) -> bool {
+        self.actions.is_empty()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use super::super::ids::StepType;
+
+    #[test]
+    fn test_replay_simple_execution() {
+        let exec_id = ExecutionId::new();
+
+        let actions = vec![
+            ExecutionAction::Start,
+            ExecutionAction::Complete {
+                output: Some("done".into()),
+            },
+        ];
+
+        let execution = replay(exec_id.clone(), actions, None).unwrap();
+
+        assert_eq!(execution.id.as_str(), exec_id.as_str());
+        assert!(execution.state.is_terminal());
+        assert_eq!(execution.output, Some("done".to_string()));
+    }
+
+    #[test]
+    fn test_replay_with_steps() {
+        let exec_id = ExecutionId::new();
+        let step_id = super::super::ids::StepId::new();
+
+        let actions = vec![
+            ExecutionAction::Start,
+            ExecutionAction::StepStarted {
+                step_id: step_id.clone(),
+                parent_step_id: None,
+                step_type: StepType::LlmNode,
+                name: "test step".into(),
+                source: None,
+            },
+            ExecutionAction::StepCompleted {
+                step_id: step_id.clone(),
+                output: Some("step output".into()),
+                duration_ms: 100,
+            },
+            ExecutionAction::Complete {
+                output: Some("done".into()),
+            },
+        ];
+
+        let execution = replay(exec_id, actions, None).unwrap();
+
+        assert_eq!(execution.steps.len(), 1);
+        let step = execution.get_step(&step_id).unwrap();
+        assert_eq!(step.output, Some("step output".to_string()));
+    }
+}

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

@@ -0,0 +1,413 @@
+//! enact-core - The core runtime for graph-centric agent execution
+//!
+//! This crate provides the foundational types and runtime for executing
+//! agent graphs with full observability and control.
+//!
+//! ## Architecture
+//!
+//! ```text
+//! ┌─────────────────────────────────────────────────────────────────────┐
+//! │                           enact-core                                │
+//! ├─────────────────────────────────────────────────────────────────────┤
+//! │  kernel/       - ExecutionKernel, state machine, reducer, replay    │
+//! │  flow/         - Sequential, parallel, conditional, loop primitives │
+//! │  callable/     - Callable trait, LlmCallable, GraphCallable         │
+//! │  policy/       - Execution, tool, tenant policies and guardrails    │
+//! │  streaming/    - Events, event log, IDs, SSE streaming              │
+//! │  graph/        - StateGraph, CompiledGraph, nodes, edges            │
+//! │  telemetry/    - OpenTelemetry integration, spans, traces           │
+//! │  providers/    - LLM adapters (Azure, Anthropic, Gemini)            │
+//! │  tool/         - Tool trait and implementations                     │
+//! │  memory/       - Episodic, semantic, working memory (future)        │
+//! └─────────────────────────────────────────────────────────────────────┘
+//! ```
+//!
+//! ## Core Concepts
+//!
+//! - **ExecutionId**: One run of a blueprint (Agent/Graph/Workflow)
+//! - **StepId**: A distinct action within that execution
+//! - **ArtifactId**: Data produced by steps
+//! - **RuntimeContext**: The execution context spine
+//! - **TenantContext**: Multi-tenant isolation boundary (REQUIRED)
+//!
+//! ## Getting Started
+//!
+//! Most users should start with:
+//!
+//! ```rust
+//! use enact_core::prelude::*;
+//! ```
+//!
+//! This imports the stable, user-facing API for defining agents, graphs, and executions.
+//! Internal modules remain accessible for advanced use cases.
+//!
+//! @see docs/TECHNICAL/01-EXECUTION-TELEMETRY.md
+//! @see docs/TECHNICAL/02-ENACT-CORE-ARCHITECTURE.md
+
+// =============================================================================
+// Core Modules
+// =============================================================================
+
+pub mod callable; // Callable trait (Agent abstraction)
+pub mod context; // TenantContext, RuntimeContext, TraceContext
+pub mod flow; // Sequential, parallel, conditional, loop
+pub mod kernel; // ExecutionKernel, state machine, reducer, replay
+pub mod policy; // Execution, tool, tenant policies
+
+// =============================================================================
+// Existing Modules
+// =============================================================================
+
+pub mod background; // Background execution and triggers (Phase 5)
+pub mod graph;
+pub mod inbox; // Mid-execution guidance (INV-INBOX-*)
+pub mod memory;
+pub mod providers;
+pub mod runner;
+pub mod signal;
+pub mod streaming; // Events, event log, IDs, SSE streaming
+pub mod telemetry; // OpenTelemetry integration
+pub mod tool;
+pub mod util;
+
+// =============================================================================
+// Re-exports - Kernel
+// =============================================================================
+
+pub use kernel::{
+    reduce, replay, EventLog as KernelEventLog, Execution, ExecutionAction, ExecutionKernel,
+    ExecutionState, ReducerError, ReplayError, Step, StepState, WaitReason,
+};
+
+// =============================================================================
+// Re-exports - Error Taxonomy (feat-02)
+// =============================================================================
+
+pub use kernel::{
+    // Retry policies
+    BackoffStrategy,
+    // Error types
+    ExecutionError,
+    ExecutionErrorCategory,
+    // Specific error codes
+    LlmErrorCode,
+    RetryPolicy,
+    ToolErrorCode,
+};
+
+// =============================================================================
+// Re-exports - Enforcement & Limits (feat-03)
+// =============================================================================
+
+pub use kernel::{
+    // Middleware
+    EnforcementMiddleware,
+    EnforcementPolicy,
+    // Enforcement results
+    EnforcementResult,
+    EnforcementViolation,
+    EnforcementWarning,
+    // Usage tracking
+    ExecutionUsage,
+    // Timeout guard
+    StepTimeoutGuard,
+    UsageSnapshot,
+    ViolationType,
+};
+
+// =============================================================================
+// Re-exports - Artifact Lifecycle (feat-04)
+// =============================================================================
+
+pub use kernel::artifact::{
+    // Metadata
+    ArtifactMetadata,
+    // Store trait and errors
+    ArtifactStore,
+    ArtifactStoreError,
+    ArtifactType,
+    CompressionType,
+    // Implementations
+    FilesystemArtifactStore,
+};
+
+// =============================================================================
+// Re-exports - Flow
+// =============================================================================
+
+pub use flow::{
+    Branch, Condition, ConditionalFlow, FanIn, FanOut, LoopCondition, LoopFlow, ParallelFlow,
+    ParallelResult, SequentialFlow,
+};
+
+// =============================================================================
+// Re-exports - Callable
+// =============================================================================
+
+pub use callable::{
+    Callable, CallableRegistry, DynCallable, GraphCallable, LlmCallable,
+    // Phase 6: Composite Callables
+    CallableDescriptor,
+    CallableInvocation,
+    CallableInvocationResult,
+    CallableInvoker,
+    CostTier,
+    DiscoveryQuery,
+    DiscoveryResult,
+    ResourceAllocation,
+    ResourceAllocationStrategy,
+    ResourceBudget,
+};
+
+// =============================================================================
+// Re-exports - Policy
+// =============================================================================
+
+pub use policy::{
+    ContentFilter,
+    ExecutionLimits,
+    ExecutionPolicy,
+    FeatureFlags,
+    FilterAction,
+    FilterResult,
+    // Input processors (feat-09: Guardrails)
+    InputProcessor,
+    InputProcessorPipeline,
+    InputProcessorResult,
+    PiiInputMode,
+    PiiInputProcessor,
+    PolicyAction,
+    PolicyContext,
+    PolicyDecision,
+    PolicyEvaluator,
+    TenantLimits,
+    TenantPolicy,
+    ToolPermissions,
+    ToolPolicy,
+    ToolTrustLevel,
+};
+
+// =============================================================================
+// Re-exports - Streaming (events, event log, SSE)
+// =============================================================================
+
+pub use streaming::{
+    ControlAction,
+    ControlActor,
+    ControlEvent,
+    ControlOutcome,
+    // Protection layer (feat-09: Guardrails)
+    DataDestination,
+    DecisionRecord,
+    DecisionType,
+    Event,
+    // Wire format for SSE
+    EventEmitter,
+    // Event log (persistence)
+    EventLog,
+    EventLogEntry,
+    EventStore,
+    EventStream,
+    // Domain events
+    ExecutionContext,
+    ExecutionEvent,
+    ExecutionEventType,
+    InMemoryEventStore,
+    OutputProcessor,
+    PiiProtectionProcessor,
+    ProcessedEvent,
+    ProcessorPipeline,
+    // Protected emitter with processor pipeline
+    ProtectedEventEmitter,
+    ProtectionContext,
+    StreamEvent,
+    StreamMode,
+};
+
+// =============================================================================
+// Re-exports - IDs and State Types (from streaming)
+// =============================================================================
+
+pub use streaming::{
+    // ID prefix constants
+    prefixes,
+    // Primary IDs
+    ArtifactId,
+    ExecutionId,
+    GraphId,
+    // Message/Thread IDs
+    MessageId,
+    ThreadId,
+    // Backward compatibility aliases
+    NodeId,
+    // Parent linkage
+    ParentLink,
+    ParentType,
+    RunId,
+    StepId,
+    // Step/Node types
+    StepType,
+    TenantId,
+    UserId,
+};
+
+// =============================================================================
+// Re-exports - MessageStore (feat-05 Persistence)
+// =============================================================================
+
+pub use kernel::{
+    // Message types
+    CostInfo,
+    ExecutionStats,
+    FinishReason,
+    Message,
+    MessageMetadata,
+    MessagePart,
+    MessageRole,
+    Thread,
+    TokenUsage,
+    // Store trait and implementation
+    InMemoryMessageStore,
+    MessageStore,
+};
+
+// =============================================================================
+// Re-exports - Context (TenantContext, RuntimeContext, etc.)
+// =============================================================================
+
+pub use context::{
+    // Invocation context
+    InvocationContext,
+    InvocationServices,
+    ResourceLimits,
+    // Runtime context (the spine)
+    RuntimeContext,
+    RuntimeContextBuilder,
+    SessionContext,
+    // Tenant context (REQUIRED for every execution)
+    TenantContext,
+    // Trace context (OpenTelemetry)
+    TraceContext,
+};
+
+// =============================================================================
+// Re-exports - Graph & Execution
+// =============================================================================
+
+pub use graph::{
+    Checkpoint, CheckpointStore, CompiledGraph, FunctionNode, InMemoryCheckpointStore, Node,
+    NodeState, StateGraph,
+};
+
+// =============================================================================
+// Re-exports - Runner
+// =============================================================================
+
+pub use runner::{run_parallel, DefaultRunner, InterruptableRunner, Runner};
+
+// =============================================================================
+// Re-exports - Inbox (Mid-Execution Guidance)
+// =============================================================================
+
+pub use inbox::{
+    // Message types
+    A2aMessage,
+    ControlAction as InboxControlAction,
+    ControlMessage,
+    EvidenceImpact,
+    EvidenceSource,
+    EvidenceUpdate,
+    GuidanceMessage,
+    GuidancePriority,
+    GuidanceSource,
+    InboxMessage,
+    InboxMessageType,
+    // Store
+    InboxStore,
+    InMemoryInboxStore,
+};
+
+// =============================================================================
+// Re-exports - Background (Phase 5: Background Callables)
+// =============================================================================
+
+pub use background::{
+    // Trigger types
+    RetryConfig,
+    ThresholdOperator,
+    Trigger,
+    TriggerAction,
+    TriggerCondition,
+    TriggerFiredEvent,
+    TriggerId,
+    TriggerStatus,
+    TriggerType,
+    // Executor types
+    BackgroundExecution,
+    BackgroundExecutionConfig,
+    BackgroundExecutionMode,
+    BackgroundExecutionQueue,
+    BackgroundExecutionStatus,
+    // Target binding types
+    TargetBindingConfig,
+    TargetBindingResult,
+    TargetBindingTransform,
+    TargetBindingType,
+    apply_transform,
+};
+
+// =============================================================================
+// Re-exports - Providers & Tools
+// =============================================================================
+
+// Re-export provider trait and types (implementations are in enact-providers)
+pub use providers::{
+    ChatMessage, ChatRequest, ChatResponse, EmbeddingRequest, EmbeddingResponse, ModelCapabilities,
+    ModelProvider,
+};
+pub use tool::{FunctionTool, Tool, ToolExecutionContext, ToolExecutionError, ToolExecutor};
+
+// =============================================================================
+// Prelude - Stable, user-facing API
+// =============================================================================
+
+/// Prelude module - Convenient imports for most users
+///
+/// This module exports the stable, user-facing API for defining agents, graphs,
+/// and executions. It is intentionally small and opinionated.
+///
+/// **Important**: The prelude is semver-sensitive and part of the brand promise.
+/// Changes here should be rare and intentional.
+///
+/// # Usage
+///
+/// ```rust
+/// use enact_core::prelude::*;
+/// ```
+///
+/// This imports:
+/// - Core runtime types (`ExecutionKernel`)
+/// - Graph authoring & execution (`StateGraph`, `CompiledGraph`)
+/// - Execution abstractions (`Callable`, `LlmCallable`, `Tool`, `FunctionTool`)
+/// - Execution identity (`ExecutionId`, `StepId`)
+/// - Observability (`EventStream`, `EventLog`)
+pub mod prelude {
+    // Core runtime
+    pub use crate::kernel::ExecutionKernel;
+
+    // Graph authoring & execution
+    pub use crate::graph::{CompiledGraph, StateGraph};
+
+    // Execution abstractions
+    pub use crate::callable::{Callable, LlmCallable};
+    pub use crate::tool::{FunctionTool, Tool};
+
+    // Execution identity
+    pub use crate::kernel::{ExecutionId, StepId};
+
+    // Error taxonomy (feat-02)
+    pub use crate::kernel::{ExecutionError, ExecutionErrorCategory};
+
+    // Observability
+    pub use crate::streaming::{EventLog, EventStream};
+}

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

@@ -0,0 +1,6 @@
+//! Memory abstractions.
+//!
+//! This module will define traits for episodic, semantic, and working
+//! memory used during execution.
+
+