enya-agent 0.1.0

package/crates/enact-providers/src/openai_compatible.rs

@@ -0,0 +1,167 @@
+//! OpenAI-compatible provider (Ollama, vLLM, LocalAI, etc.)
+//!
+//! This provider works with any service that follows the OpenAI API spec:
+//! - Ollama (local models)
+//! - vLLM (local inference server)
+//! - LocalAI
+//! - Any OpenAI-compatible endpoint
+//!
+//! ## Usage
+//!
+//! ```rust
+//! use enact_providers::OpenAICompatible;
+//!
+//! // For Ollama (no API key needed)
+//! let provider = OpenAICompatible::new(
+//!     "http://localhost:11434",
+//!     "llama3",
+//!     None,
+//! );
+//!
+//! // For OpenAI or other services requiring API key
+//! let provider = OpenAICompatible::new(
+//!     "https://api.openai.com",
+//!     "gpt-4",
+//!     Some("sk-...".to_string()),
+//! );
+//! ```
+
+use crate::http::{HttpRequestSpec, post_json};
+use enact_core::providers::{
+    ChatRequest, ChatResponse, EmbeddingRequest, EmbeddingResponse, ModelCapabilities, ModelProvider,
+};
+use async_trait::async_trait;
+use reqwest::Client;
+use std::time::Duration;
+
+/// OpenAI-compatible provider
+///
+/// Works with any service that follows the OpenAI API specification:
+/// - Ollama (local models)
+/// - vLLM (local inference server)
+/// - LocalAI
+/// - OpenAI API
+/// - Any other OpenAI-compatible endpoint
+pub struct OpenAICompatible {
+    client: Client,
+    base_url: String,
+    api_key: Option<String>,
+    model: String,
+}
+
+impl OpenAICompatible {
+    /// Create a new OpenAI-compatible provider
+    ///
+    /// # Arguments
+    ///
+    /// * `base_url` - Base URL of the API (e.g., "http://localhost:11434" for Ollama)
+    /// * `model` - Model name to use (e.g., "llama3", "gpt-4")
+    /// * `api_key` - Optional API key (Ollama doesn't need one, OpenAI does)
+    pub fn new(
+        base_url: impl Into<String>,
+        model: impl Into<String>,
+        api_key: Option<String>,
+    ) -> Self {
+        Self {
+            client: Client::new(),
+            base_url: base_url.into().trim_end_matches('/').to_string(),
+            api_key,
+            model: model.into(),
+        }
+    }
+
+    fn build_chat_url(&self) -> String {
+        format!("{}/v1/chat/completions", self.base_url)
+    }
+
+    fn build_embedding_url(&self) -> String {
+        format!("{}/v1/embeddings", self.base_url)
+    }
+
+    fn build_headers(&self) -> Vec<(String, String)> {
+        let mut headers = vec![
+            ("Content-Type".to_string(), "application/json".to_string()),
+        ];
+
+        if let Some(api_key) = &self.api_key {
+            headers.push(("Authorization".to_string(), format!("Bearer {}", api_key)));
+        }
+
+        headers
+    }
+}
+
+#[async_trait]
+impl ModelProvider for OpenAICompatible {
+    fn name(&self) -> &str {
+        "openai-compatible"
+    }
+
+    fn model(&self) -> &str {
+        &self.model
+    }
+
+    fn capabilities(&self) -> ModelCapabilities {
+        ModelCapabilities {
+            max_tokens: 8192,
+            max_output_tokens: 4096,
+            supports_streaming: true,
+            supports_tools: true,
+            supports_vision: false, // Most local models don't support vision
+            supports_json_mode: true,
+            supports_embeddings: true,
+            pii_safe: false,
+            cost_per_1k_input: None, // Local models typically have no cost
+            cost_per_1k_output: None,
+        }
+    }
+
+    async fn chat(&self, request: ChatRequest) -> anyhow::Result<ChatResponse> {
+        let url = self.build_chat_url();
+
+        // Build request body with model
+        let mut body = serde_json::to_value(&request)?;
+        body["model"] = serde_json::Value::String(self.model.clone());
+
+        // Build HTTP request spec
+        let http_req = HttpRequestSpec {
+            url,
+            headers: self.build_headers(),
+            body,
+            timeout: Duration::from_secs(60), // Longer timeout for local models
+        };
+
+        // Execute request using HTTP helper
+        let json_response = post_json(&self.client, http_req).await?;
+
+        // Parse response
+        let chat_response: ChatResponse = serde_json::from_value(json_response)?;
+        Ok(chat_response)
+    }
+
+    async fn embed(&self, request: EmbeddingRequest) -> anyhow::Result<EmbeddingResponse> {
+        let url = self.build_embedding_url();
+
+        // Build request body with model
+        let mut body = serde_json::to_value(&request)?;
+        body["model"] = serde_json::Value::String(
+            request.model.clone().unwrap_or_else(|| self.model.clone())
+        );
+
+        // Build HTTP request spec
+        let http_req = HttpRequestSpec {
+            url,
+            headers: self.build_headers(),
+            body,
+            timeout: Duration::from_secs(60),
+        };
+
+        // Execute request using HTTP helper
+        let json_response = post_json(&self.client, http_req).await?;
+
+        // Parse response
+        let embedding_response: EmbeddingResponse = serde_json::from_value(json_response)?;
+        Ok(embedding_response)
+    }
+}
+

package/crates/enact-providers/src/openrouter.rs

@@ -0,0 +1,33 @@
+//! OpenRouter provider
+//!
+//! **Status**: [planned]
+//!
+//! ## Implementation Notes
+//!
+//! This provider will implement the `ModelProvider` trait for OpenRouter's unified API.
+//!
+//! - **Endpoint**: HTTP POST to `https://openrouter.ai/api/v1/chat/completions`
+//! - **Documentation**: https://openrouter.ai/docs
+//! - **Authentication**: `Authorization: Bearer <api_key>` header
+//!
+//! ## Environment Variables
+//!
+//! - `OPENROUTER_API_KEY` (required) - Your OpenRouter API key
+//! - `OPENROUTER_MODEL` (optional, default: "openai/gpt-4") - Model to use
+//!
+//! ## Important Notes
+//!
+//! Providers must be side-effect free outside HTTP calls. All retries, rate limiting,
+//! and quotas are enforced by the kernel, not by the provider implementation.
+//!
+//! ## Example Usage (Future)
+//!
+//! ```rust,ignore
+//! use enact_providers::{OpenRouter, ModelProvider};
+//! use enact_config::Config;
+//!
+//! let config = Config::load()?;
+//! let provider = OpenRouter::new(config)?;
+//! let response = provider.chat(request).await?;
+//! ```
+

package/crates/enact-runner/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "enact-runner"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "Robust agent loop runner for Enact — retries, compaction, multi-format parsing"
+repository.workspace = true
+homepage.workspace = true
+keywords = ["runner", "agent", "loop", "retry"]
+categories.workspace = true
+
+[dependencies]
+enact-core = { workspace = true }
+
+tokio.workspace = true
+async-trait.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+tracing.workspace = true
+anyhow.workspace = true
+regex.workspace = true
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["test-util"] }

package/crates/enact-runner/README.md

@@ -0,0 +1,76 @@
+# enact-runner
+
+> Robust agent loop runner for Enact — retries, compaction, multi-format parsing.
+
+## What Is This?
+
+`enact-runner` is the **"missing middle"** between the apps (`cli`, `api`) and `enact-core`'s deterministic kernel. It implements the robust agent loop mandated by the technical specs but never built.
+
+## Quick Start
+
+```rust
+use enact_runner::{AgentRunner, DefaultAgentRunner, RunnerConfig, LoopOutcome};
+
+// Default config (max 25 iterations, compaction at 40 messages)
+let mut runner = DefaultAgentRunner::default_new()
+    .add_tool(my_search_tool)
+    .add_tool(my_read_file_tool);
+
+let outcome = runner.run(&my_llm_callable, "user input").await?;
+
+match outcome {
+    LoopOutcome::Completed(output) => println!("Done: {}", output),
+    LoopOutcome::MaxIterationsReached { .. } => println!("Hit limit"),
+    LoopOutcome::Cancelled => println!("Cancelled"),
+    LoopOutcome::TimedOut { .. } => println!("Timed out"),
+}
+```
+
+## Presets
+
+```rust
+// Short interactive sessions (10 iterations, 2 min timeout)
+let config = RunnerConfig::interactive();
+
+// Long-running background agents (100 iterations, 1 hour timeout)
+let config = RunnerConfig::long_running();
+```
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **Multi-format parsing** | Parses tool calls from JSON, XML, and Markdown |
+| **Retry with backoff** | Exponential backoff for rate-limits and transient errors |
+| **Error classification** | Distinguishes retryable (rate-limit, network) from fatal (auth, invalid) |
+| **Auto-compaction** | Summarizes older messages when history exceeds threshold |
+| **Checkpointing** | Saves state at configurable intervals |
+| **Cancel/Pause** | Delegates to `enact-core::Runner` for cancel/pause signals |
+| **Stream events** | Emits `StreamEvent`s for real-time observability |
+
+## Module Structure
+
+```
+src/
+├── lib.rs           # Module root + re-exports
+├── config.rs        # RunnerConfig, RetryConfig, presets
+├── loop_driver.rs   # AgentRunner::run() — the core loop
+├── parser.rs        # Multi-format tool call parsing
+├── compaction.rs    # Auto context summarization
+└── retry.rs         # Error classification + backoff
+tests/
+└── integration.rs   # Full loop integration tests
+```
+
+## Testing
+
+```bash
+# All tests (31 total)
+cargo test -p enact-runner
+
+# Only integration tests
+cargo test -p enact-runner --test integration
+
+# Specific test
+cargo test -p enact-runner test_retry_on_transient_error
+```

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

@@ -0,0 +1,225 @@
+//! Context compaction for long-running agent loops
+//!
+//! When message history exceeds a threshold, older messages are summarized
+//! into a single context message to prevent context window overflow.
+//!
+//! Ported from zeroclaw's `auto_compact_history` which uses the LLM itself
+//! to generate a summary of older conversation history.
+
+use enact_core::callable::Callable;
+
+/// A message in the conversation history.
+#[derive(Debug, Clone)]
+pub struct HistoryMessage {
+    /// Role: "system", "user", "assistant", "tool"
+    pub role: String,
+    /// Message content
+    pub content: String,
+}
+
+impl HistoryMessage {
+    pub fn system(content: impl Into<String>) -> Self {
+        Self {
+            role: "system".to_string(),
+            content: content.into(),
+        }
+    }
+
+    pub fn user(content: impl Into<String>) -> Self {
+        Self {
+            role: "user".to_string(),
+            content: content.into(),
+        }
+    }
+
+    pub fn assistant(content: impl Into<String>) -> Self {
+        Self {
+            role: "assistant".to_string(),
+            content: content.into(),
+        }
+    }
+
+    pub fn tool_result(name: &str, content: impl Into<String>) -> Self {
+        Self {
+            role: "tool".to_string(),
+            content: format!("[{}]: {}", name, content.into()),
+        }
+    }
+}
+
+/// Check if compaction is needed based on message count.
+pub fn needs_compaction(history: &[HistoryMessage], threshold: usize) -> bool {
+    history.len() > threshold
+}
+
+/// Compact the conversation history by summarizing older messages.
+///
+/// Keeps the system message (index 0) and the `keep_recent` most recent messages.
+/// Everything in between is summarized into a single "context summary" message.
+///
+/// # Arguments
+/// * `history` — mutable reference to the message history
+/// * `summarizer` — a Callable used to generate the summary (typically the LLM itself)
+/// * `keep_recent` — how many recent messages to preserve verbatim
+///
+/// # Returns
+/// `true` if compaction was performed, `false` if history was too short.
+pub async fn compact_history(
+    history: &mut Vec<HistoryMessage>,
+    summarizer: &dyn Callable,
+    keep_recent: usize,
+) -> anyhow::Result<bool> {
+    // Need at least: system + some old messages + keep_recent
+    if history.len() <= keep_recent + 2 {
+        return Ok(false);
+    }
+
+    // Split: [system] [old messages to summarize] [recent messages to keep]
+    let split_point = history.len() - keep_recent;
+
+    // Build a transcript of the old messages (skip system at index 0)
+    let old_messages = &history[1..split_point];
+
+    if old_messages.is_empty() {
+        return Ok(false);
+    }
+
+    let transcript = old_messages
+        .iter()
+        .map(|m| format!("{}: {}", m.role, m.content))
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    // Ask the LLM to summarize the old conversation
+    let summary_prompt = format!(
+        "Summarize the following conversation history into a concise context summary. \
+         Preserve key facts, decisions, tool results, and any state that would be needed \
+         to continue the conversation. Be concise but complete.\n\n\
+         CONVERSATION:\n{}\n\n\
+         SUMMARY:",
+        transcript
+    );
+
+    let summary = summarizer.run(&summary_prompt).await?;
+
+    tracing::info!(
+        old_messages = old_messages.len(),
+        summary_len = summary.len(),
+        "Compacted conversation history"
+    );
+
+    // Reconstruct history: [system] [summary] [recent messages]
+    let system_msg = history[0].clone();
+    let recent_messages: Vec<HistoryMessage> = history[split_point..].to_vec();
+
+    history.clear();
+    history.push(system_msg);
+    history.push(HistoryMessage {
+        role: "system".to_string(),
+        content: format!(
+            "[Context Summary from earlier conversation]\n{}",
+            summary
+        ),
+    });
+    history.extend(recent_messages);
+
+    Ok(true)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_needs_compaction() {
+        let history: Vec<HistoryMessage> = (0..50)
+            .map(|i| HistoryMessage::user(format!("msg {}", i)))
+            .collect();
+
+        assert!(needs_compaction(&history, 40));
+        assert!(!needs_compaction(&history, 50));
+        assert!(!needs_compaction(&history, 100));
+    }
+
+    #[test]
+    fn test_history_message_constructors() {
+        let sys = HistoryMessage::system("You are helpful");
+        assert_eq!(sys.role, "system");
+
+        let user = HistoryMessage::user("Hello");
+        assert_eq!(user.role, "user");
+
+        let asst = HistoryMessage::assistant("Hi there");
+        assert_eq!(asst.role, "assistant");
+
+        let tool = HistoryMessage::tool_result("search", "found 5 results");
+        assert_eq!(tool.role, "tool");
+        assert!(tool.content.contains("[search]"));
+    }
+
+    #[tokio::test]
+    async fn test_compact_short_history_is_noop() {
+        use async_trait::async_trait;
+
+        struct MockSummarizer;
+
+        #[async_trait]
+        impl Callable for MockSummarizer {
+            fn name(&self) -> &str {
+                "mock"
+            }
+            async fn run(&self, _input: &str) -> anyhow::Result<String> {
+                Ok("summary".to_string())
+            }
+        }
+
+        let mut history = vec![
+            HistoryMessage::system("system"),
+            HistoryMessage::user("hello"),
+        ];
+
+        let result = compact_history(&mut history, &MockSummarizer, 10).await.unwrap();
+        assert!(!result, "Should not compact when history is short");
+        assert_eq!(history.len(), 2);
+    }
+
+    #[tokio::test]
+    async fn test_compact_long_history() {
+        use async_trait::async_trait;
+
+        struct MockSummarizer;
+
+        #[async_trait]
+        impl Callable for MockSummarizer {
+            fn name(&self) -> &str {
+                "mock"
+            }
+            async fn run(&self, _input: &str) -> anyhow::Result<String> {
+                Ok("Summarized: user asked about Rust, assistant explained ownership.".to_string())
+            }
+        }
+
+        let mut history = vec![HistoryMessage::system("Be helpful")];
+        // Add 30 old messages
+        for i in 0..30 {
+            history.push(HistoryMessage::user(format!("question {}", i)));
+            history.push(HistoryMessage::assistant(format!("answer {}", i)));
+        }
+
+        let original_len = history.len(); // 61
+
+        let result = compact_history(&mut history, &MockSummarizer, 5).await.unwrap();
+        assert!(result, "Should have compacted");
+
+        // Should now be: system + summary + 5 recent = 7
+        assert_eq!(history.len(), 7);
+        assert!(history.len() < original_len);
+
+        // First should still be system
+        assert_eq!(history[0].role, "system");
+        assert_eq!(history[0].content, "Be helpful");
+
+        // Second should be the context summary
+        assert!(history[1].content.contains("[Context Summary"));
+    }
+}

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

@@ -0,0 +1,118 @@
+//! Runner configuration
+//!
+//! Defines `RunnerConfig` — the knobs that control the robust agent loop.
+//! Ported from zeroclaw's iteration limits, compaction thresholds, and retry policies.
+
+use std::time::Duration;
+
+/// Configuration for the `AgentRunner` loop.
+///
+/// Controls iteration limits, context compaction, retry behavior,
+/// and checkpointing intervals.
+#[derive(Debug, Clone)]
+pub struct RunnerConfig {
+    /// Maximum number of tool-call iterations before the loop terminates.
+    /// Prevents runaway executions.
+    /// Default: 25 (zeroclaw uses configurable `max_tool_iterations`)
+    pub max_iterations: usize,
+
+    /// Maximum wall-clock duration for the entire run.
+    /// Default: 10 minutes
+    pub max_duration: Duration,
+
+    /// Number of messages in history before auto-compaction triggers.
+    /// When exceeded, older messages are summarized into a single context message.
+    /// Default: 40 messages
+    pub compaction_threshold: usize,
+
+    /// How many messages to keep verbatim after compaction.
+    /// The rest are summarized.
+    /// Default: 10 (keep the 10 most recent messages)
+    pub compaction_keep_recent: usize,
+
+    /// Retry configuration for transient errors.
+    pub retry: RetryConfig,
+
+    /// Checkpoint every N steps. `None` disables periodic checkpointing.
+    /// Default: Some(5)
+    pub checkpoint_interval: Option<usize>,
+
+    /// Whether to emit verbose stream events for each iteration.
+    /// Default: true
+    pub emit_events: bool,
+}
+
+/// Retry configuration for transient errors.
+#[derive(Debug, Clone)]
+pub struct RetryConfig {
+    /// Maximum number of retries for a single operation.
+    /// Default: 3
+    pub max_retries: u32,
+
+    /// Initial delay before the first retry.
+    /// Default: 1 second
+    pub initial_delay: Duration,
+
+    /// Maximum delay between retries (caps exponential growth).
+    /// Default: 30 seconds
+    pub max_delay: Duration,
+
+    /// Multiplier for exponential backoff.
+    /// Default: 2.0
+    pub backoff_multiplier: f64,
+}
+
+impl Default for RunnerConfig {
+    fn default() -> Self {
+        Self {
+            max_iterations: 25,
+            max_duration: Duration::from_secs(600),
+            compaction_threshold: 40,
+            compaction_keep_recent: 10,
+            retry: RetryConfig::default(),
+            checkpoint_interval: Some(5),
+            emit_events: true,
+        }
+    }
+}
+
+impl Default for RetryConfig {
+    fn default() -> Self {
+        Self {
+            max_retries: 3,
+            initial_delay: Duration::from_secs(1),
+            max_delay: Duration::from_secs(30),
+            backoff_multiplier: 2.0,
+        }
+    }
+}
+
+impl RunnerConfig {
+    /// Create a config tuned for short, interactive sessions.
+    pub fn interactive() -> Self {
+        Self {
+            max_iterations: 10,
+            max_duration: Duration::from_secs(120),
+            compaction_threshold: 20,
+            compaction_keep_recent: 6,
+            checkpoint_interval: None,
+            ..Default::default()
+        }
+    }
+
+    /// Create a config tuned for long-running background agents.
+    pub fn long_running() -> Self {
+        Self {
+            max_iterations: 100,
+            max_duration: Duration::from_secs(3600),
+            compaction_threshold: 60,
+            compaction_keep_recent: 15,
+            checkpoint_interval: Some(10),
+            retry: RetryConfig {
+                max_retries: 5,
+                ..Default::default()
+            },
+            ..Default::default()
+        }
+    }
+}