enya-agent 0.1.0

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

@@ -0,0 +1,63 @@
+//! enact-runner — The Robust Agent Loop for Enact
+//!
+//! This crate fills the gap between `enact-core`'s deterministic kernel and the
+//! applications (CLI, API) that assume the Rust layer handles retries, context
+//! compaction, and multi-format tool call parsing.
+//!
+//! ## Architecture
+//!
+//! ```text
+//! ┌─────────────────────────────────────────────────────┐
+//! │  CLI / API / Web (thin clients)                     │
+//! └──────────────────────┬──────────────────────────────┘
+//!                        │ Execution Intent
+//!                        ▼
+//! ┌─────────────────────────────────────────────────────┐
+//! │  enact-runner (THIS CRATE)                          │
+//! │  ┌─────────────────────────────────────────────┐    │
+//! │  │  AgentRunner::run()                         │    │
+//! │  │  • Multi-iteration tool call loop           │    │
+//! │  │  • Retry with exponential backoff           │    │
+//! │  │  • Auto context compaction                  │    │
+//! │  │  • Multi-format parsing (JSON/XML/MD)       │    │
+//! │  │  • Checkpoint at intervals                  │    │
+//! │  │  • Stream event emission                    │    │
+//! │  └─────────────────────────────────────────────┘    │
+//! └──────────────────────┬──────────────────────────────┘
+//!                        │ Callable::run()
+//!                        ▼
+//! ┌─────────────────────────────────────────────────────┐
+//! │  enact-core kernel (deterministic DAG engine)       │
+//! └─────────────────────────────────────────────────────┘
+//! ```
+//!
+//! ## Quick Start
+//!
+//! ```rust,no_run
+//! use enact_runner::{AgentRunner, RunnerConfig, DefaultAgentRunner};
+//!
+//! # async fn example() -> anyhow::Result<()> {
+//! // Create runner with default config
+//! let mut runner = DefaultAgentRunner::default_new();
+//!
+//! // Or configure for long-running tasks
+//! let mut runner = DefaultAgentRunner::with_config(RunnerConfig::long_running());
+//!
+//! // Run an agent through the robust loop
+//! // let outcome = runner.run(&my_callable, "user input").await?;
+//! # Ok(())
+//! # }
+//! ```
+
+pub mod compaction;
+pub mod config;
+pub mod loop_driver;
+pub mod parser;
+pub mod retry;
+
+// Re-exports for convenient access
+pub use compaction::HistoryMessage;
+pub use config::{RetryConfig, RunnerConfig};
+pub use loop_driver::{AgentRunner, DefaultAgentRunner, LoopOutcome};
+pub use parser::{ParseResult, ParsedToolCall, ToolCallFormat};
+pub use retry::{classify_error, ErrorKind, RetryHandler};

package/crates/enact-runner/src/loop_driver.rs

@@ -0,0 +1,414 @@
+//! Core agent loop driver
+//!
+//! `AgentRunner` is the "missing middle" — the robust loop that sits between
+//! the apps (CLI, API) and the `enact-core` kernel. It implements:
+//!
+//! - Multi-iteration tool call loop (ported from zeroclaw's `run_tool_call_loop`)
+//! - Multi-format tool call parsing (JSON, XML, Markdown)
+//! - Auto context compaction when history grows too large
+//! - Retry with exponential backoff for transient errors
+//! - Checkpoint saving at configured intervals
+//! - Stream event emission throughout
+//!
+//! This fulfills the mandate from `28-TS-RUST-INTEGRATION.md`:
+//! "Rust handles retries/fallbacks" and `27-LONG-RUNNING-EXECUTIONS.md`:
+//! "Unified long-running agentic loop".
+
+use crate::compaction::{self, HistoryMessage};
+use crate::config::RunnerConfig;
+use crate::parser;
+use crate::retry::RetryHandler;
+
+use enact_core::callable::Callable;
+use enact_core::graph::CheckpointStore;
+use enact_core::kernel::{ExecutionError, StepId, StepType};
+use enact_core::runner::Runner;
+use enact_core::streaming::StreamEvent;
+use enact_core::tool::Tool;
+
+use std::sync::Arc;
+use std::time::Instant;
+
+/// Outcome of a runner loop execution.
+#[derive(Debug)]
+pub enum LoopOutcome {
+    /// The agent produced a final response (no more tool calls).
+    Completed(String),
+    /// The loop hit the maximum iteration limit.
+    MaxIterationsReached {
+        last_output: String,
+        iterations: usize,
+    },
+    /// The execution was cancelled externally.
+    Cancelled,
+    /// The execution exceeded the configured timeout.
+    TimedOut {
+        elapsed_secs: u64,
+    },
+}
+
+impl LoopOutcome {
+    /// Whether the outcome represents a successful completion.
+    pub fn is_completed(&self) -> bool {
+        matches!(self, LoopOutcome::Completed(_))
+    }
+
+    /// Get the final output text, if any.
+    pub fn output(&self) -> Option<&str> {
+        match self {
+            LoopOutcome::Completed(s) => Some(s),
+            LoopOutcome::MaxIterationsReached { last_output, .. } => Some(last_output),
+            _ => None,
+        }
+    }
+}
+
+/// The robust agent runner — drives the tool call loop with retries,
+/// compaction, and multi-format parsing.
+pub struct AgentRunner<S: CheckpointStore> {
+    /// The underlying enact-core runner (provides cancel/pause/checkpoint/events)
+    runner: Runner<S>,
+    /// Configuration for iteration limits, compaction, retries
+    config: RunnerConfig,
+    /// Registered tools available to the agent
+    tools: Vec<Arc<dyn Tool>>,
+}
+
+impl<S: CheckpointStore> AgentRunner<S> {
+    /// Create a new `AgentRunner` wrapping an existing `Runner`.
+    pub fn new(runner: Runner<S>, config: RunnerConfig) -> Self {
+        Self {
+            runner,
+            config,
+            tools: Vec::new(),
+        }
+    }
+
+    /// Register a tool for use in the loop.
+    pub fn add_tool(mut self, tool: impl Tool + 'static) -> Self {
+        self.tools.push(Arc::new(tool));
+        self
+    }
+
+    /// Register multiple tools at once.
+    pub fn add_tools(mut self, tools: Vec<Arc<dyn Tool>>) -> Self {
+        self.tools.extend(tools);
+        self
+    }
+
+    /// Access the underlying runner.
+    pub fn inner(&self) -> &Runner<S> {
+        &self.runner
+    }
+
+    /// Access the underlying runner mutably.
+    pub fn inner_mut(&mut self) -> &mut Runner<S> {
+        &mut self.runner
+    }
+
+    /// Run the robust agent loop.
+    ///
+    /// This is the core method — it replaces both `AgenticLoop::run` (which was
+    /// a skeleton) and `LlmCallable::run` (which had a basic loop but no
+    /// retries, compaction, or multi-format parsing).
+    ///
+    /// # Flow
+    ///
+    /// 1. Call the callable with current input
+    /// 2. Parse the response for tool calls (JSON → XML → Markdown)
+    /// 3. If tool calls found: execute them, append results to history, loop
+    /// 4. If no tool calls: return the final response
+    /// 5. Throughout: check limits, retry on errors, compact history, checkpoint
+    pub async fn run(
+        &mut self,
+        callable: &dyn Callable,
+        input: &str,
+    ) -> anyhow::Result<LoopOutcome> {
+        let start_time = Instant::now();
+        let mut retry_handler = RetryHandler::new(self.config.retry.clone());
+
+        // Build initial history
+        let mut history = vec![
+            HistoryMessage::user(input),
+        ];
+
+        // Emit execution start
+        if self.config.emit_events {
+            self.runner.emitter().emit(StreamEvent::execution_start(
+                self.runner.execution_id(),
+            ));
+        }
+
+        tracing::info!(
+            execution_id = %self.runner.execution_id(),
+            callable = callable.name(),
+            max_iterations = self.config.max_iterations,
+            "Starting robust agent loop"
+        );
+
+        let mut last_output = String::new();
+
+        for iteration in 0..self.config.max_iterations {
+            // ── Check cancellation ──
+            if self.runner.is_cancelled() {
+                tracing::info!("Execution cancelled");
+                return Ok(LoopOutcome::Cancelled);
+            }
+
+            // ── Check timeout ──
+            let elapsed = start_time.elapsed();
+            if elapsed > self.config.max_duration {
+                tracing::warn!(
+                    elapsed_secs = elapsed.as_secs(),
+                    "Execution timed out"
+                );
+                return Ok(LoopOutcome::TimedOut {
+                    elapsed_secs: elapsed.as_secs(),
+                });
+            }
+
+            // ── Wait if paused ──
+            while self.runner.is_paused() {
+                tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
+                if self.runner.is_cancelled() {
+                    return Ok(LoopOutcome::Cancelled);
+                }
+            }
+
+            // ── Build input for this iteration ──
+            let current_input = self.build_iteration_input(&history);
+            let step_id = StepId::new();
+            let step_start = Instant::now();
+
+            if self.config.emit_events {
+                self.runner.emitter().emit(StreamEvent::step_start(
+                    self.runner.execution_id(),
+                    &step_id,
+                    StepType::LlmNode,
+                    format!("iteration_{}", iteration),
+                ));
+            }
+
+            tracing::debug!(iteration, "Running callable");
+
+            // ── Call the LLM ──
+            let response = match callable.run(&current_input).await {
+                Ok(output) => {
+                    retry_handler.reset();
+                    output
+                }
+                Err(e) => {
+                    let err_msg = e.to_string();
+                    tracing::warn!(iteration, error = %err_msg, "Callable error");
+
+                    // Check if we should retry
+                    if let Some(delay) = retry_handler.should_retry(&err_msg) {
+                        if self.config.emit_events {
+                            self.runner.emitter().emit(StreamEvent::step_end(
+                                self.runner.execution_id(),
+                                &step_id,
+                                Some(format!("Retrying after error: {}", err_msg)),
+                                step_start.elapsed().as_millis() as u64,
+                            ));
+                        }
+                        tokio::time::sleep(delay).await;
+                        continue; // Retry this iteration
+                    }
+
+                    // Non-retryable or max retries exceeded
+                    let exec_error = ExecutionError::kernel_internal(err_msg);
+                    if self.config.emit_events {
+                        self.runner.emitter().emit(StreamEvent::execution_failed(
+                            self.runner.execution_id(),
+                            exec_error,
+                        ));
+                    }
+                    return Err(e);
+                }
+            };
+
+            // ── Parse for tool calls ──
+            let parse_result = parser::parse(&response);
+
+            if parse_result.tool_calls.is_empty() {
+                // No tool calls — this is the final response
+                last_output = if parse_result.text.is_empty() {
+                    response.clone()
+                } else {
+                    parse_result.text.clone()
+                };
+
+                let step_duration = step_start.elapsed().as_millis() as u64;
+                if self.config.emit_events {
+                    self.runner.emitter().emit(StreamEvent::step_end(
+                        self.runner.execution_id(),
+                        &step_id,
+                        Some(last_output.clone()),
+                        step_duration,
+                    ));
+                    let total_duration = start_time.elapsed().as_millis() as u64;
+                    self.runner.emitter().emit(StreamEvent::execution_end(
+                        self.runner.execution_id(),
+                        Some(last_output.clone()),
+                        total_duration,
+                    ));
+                }
+
+                tracing::info!(
+                    iteration,
+                    output_len = last_output.len(),
+                    "Agent loop completed with final response"
+                );
+
+                return Ok(LoopOutcome::Completed(last_output));
+            }
+
+            // ── Execute tool calls ──
+            history.push(HistoryMessage::assistant(&response));
+
+            for tool_call in &parse_result.tool_calls {
+                tracing::debug!(
+                    tool = %tool_call.name,
+                    format = ?tool_call.format,
+                    "Executing tool call"
+                );
+
+                // Find the tool in our registry
+                let tool = self.tools.iter().find(|t| t.name() == tool_call.name);
+
+                let tool_result = match tool {
+                    Some(t) => {
+                        match t.execute(tool_call.arguments.clone()).await {
+                            Ok(result) => serde_json::to_string(&result)
+                                .unwrap_or_else(|_| format!("{:?}", result)),
+                            Err(e) => format!("Tool error: {}", e),
+                        }
+                    }
+                    None => {
+                        format!(
+                            "Error: Tool '{}' not found. Available tools: {:?}",
+                            tool_call.name,
+                            self.tools.iter().map(|t| t.name()).collect::<Vec<_>>()
+                        )
+                    }
+                };
+
+                history.push(HistoryMessage::tool_result(&tool_call.name, &tool_result));
+            }
+
+            let step_duration = step_start.elapsed().as_millis() as u64;
+            if self.config.emit_events {
+                self.runner.emitter().emit(StreamEvent::step_end(
+                    self.runner.execution_id(),
+                    &step_id,
+                    Some(format!(
+                        "Executed {} tool(s)",
+                        parse_result.tool_calls.len()
+                    )),
+                    step_duration,
+                ));
+            }
+
+            last_output = response;
+
+            // ── Auto-compact history if needed ──
+            if compaction::needs_compaction(&history, self.config.compaction_threshold) {
+                tracing::info!(
+                    history_len = history.len(),
+                    threshold = self.config.compaction_threshold,
+                    "Triggering auto-compaction"
+                );
+
+                match compaction::compact_history(
+                    &mut history,
+                    callable,
+                    self.config.compaction_keep_recent,
+                )
+                .await
+                {
+                    Ok(true) => {
+                        tracing::info!(
+                            new_len = history.len(),
+                            "History compacted successfully"
+                        );
+                    }
+                    Ok(false) => {
+                        tracing::debug!("Compaction skipped (not enough messages)");
+                    }
+                    Err(e) => {
+                        // Compaction failure is non-fatal — log and continue
+                        tracing::warn!(error = %e, "History compaction failed, continuing");
+                    }
+                }
+            }
+
+            // ── Checkpoint at intervals ──
+            if let Some(interval) = self.config.checkpoint_interval {
+                if (iteration + 1) % interval == 0 {
+                    let state = enact_core::graph::NodeState::from_str(&last_output);
+                    if let Err(e) = self
+                        .runner
+                        .save_checkpoint(state, Some(callable.name()))
+                        .await
+                    {
+                        tracing::warn!(error = %e, "Failed to save checkpoint, continuing");
+                    } else {
+                        tracing::debug!(iteration, "Checkpoint saved");
+                    }
+                }
+            }
+        }
+
+        // Max iterations reached
+        tracing::warn!(
+            max = self.config.max_iterations,
+            "Max iterations reached"
+        );
+
+        if self.config.emit_events {
+            let duration = start_time.elapsed().as_millis() as u64;
+            self.runner.emitter().emit(StreamEvent::execution_end(
+                self.runner.execution_id(),
+                Some(last_output.clone()),
+                duration,
+            ));
+        }
+
+        Ok(LoopOutcome::MaxIterationsReached {
+            last_output,
+            iterations: self.config.max_iterations,
+        })
+    }
+
+    /// Build the input string for a given iteration from history.
+    ///
+    /// Concatenates all history messages into a single prompt string.
+    fn build_iteration_input(&self, history: &[HistoryMessage]) -> String {
+        history
+            .iter()
+            .map(|m| format!("{}: {}", m.role, m.content))
+            .collect::<Vec<_>>()
+            .join("\n\n")
+    }
+}
+
+/// Convenience: create an `AgentRunner` with default in-memory checkpoint store.
+pub type DefaultAgentRunner = AgentRunner<enact_core::graph::InMemoryCheckpointStore>;
+
+impl DefaultAgentRunner {
+    /// Create a new `AgentRunner` with default in-memory store and default config.
+    pub fn default_new() -> Self {
+        Self::new(
+            enact_core::runner::DefaultRunner::default_new(),
+            RunnerConfig::default(),
+        )
+    }
+
+    /// Create with a specific config.
+    pub fn with_config(config: RunnerConfig) -> Self {
+        Self::new(
+            enact_core::runner::DefaultRunner::default_new(),
+            config,
+        )
+    }
+}