enya-agent 0.1.0

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

@@ -0,0 +1,421 @@
+//! Multi-format tool call parser
+//!
+//! Parses tool calls from LLM output across multiple formats:
+//! JSON → XML → Markdown (priority order).
+//!
+//! Ported from zeroclaw's `parse_tool_calls` which handles JSON, XML,
+//! Markdown, and GLM-style formats for maximum resilience.
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+/// A parsed tool call extracted from LLM output.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ParsedToolCall {
+    /// Tool name to invoke
+    pub name: String,
+    /// Arguments as a JSON value
+    pub arguments: Value,
+    /// Which format was used to detect this call
+    pub format: ToolCallFormat,
+}
+
+/// The format in which the tool call was detected.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ToolCallFormat {
+    /// Standard JSON: `{"tool_call": {"name": "...", "arguments": {...}}}`
+    JsonObject,
+    /// JSON array: `[{"name": "...", "arguments": {...}}]`
+    JsonArray,
+    /// XML: `<tool_call><name>...</name><arguments>...</arguments></tool_call>`
+    Xml,
+    /// Markdown code block: `` ```tool_call\n{"name": "...", ...}\n``` ``
+    Markdown,
+}
+
+/// Result of parsing: extracted text (non-tool-call content) and tool calls.
+pub struct ParseResult {
+    /// Text content that is NOT a tool call
+    pub text: String,
+    /// Parsed tool calls found in the response
+    pub tool_calls: Vec<ParsedToolCall>,
+}
+
+/// Parse tool calls from an LLM response string.
+///
+/// Tries formats in priority order: JSON → XML → Markdown.
+/// Returns all detected tool calls and the remaining text.
+pub fn parse(response: &str) -> ParseResult {
+    // 1. Try JSON object format
+    if let Some(result) = try_parse_json_object(response) {
+        return result;
+    }
+
+    // 2. Try JSON array format
+    if let Some(result) = try_parse_json_array(response) {
+        return result;
+    }
+
+    // 3. Try XML format
+    if let Some(result) = try_parse_xml(response) {
+        return result;
+    }
+
+    // 4. Try Markdown code block format
+    if let Some(result) = try_parse_markdown(response) {
+        return result;
+    }
+
+    // No tool calls found — entire response is text
+    ParseResult {
+        text: response.to_string(),
+        tool_calls: vec![],
+    }
+}
+
+/// Try parsing as a JSON object: `{"tool_call": {"name": "...", "arguments": {...}}}`
+/// Also handles: `{"tool_calls": [...]}`
+fn try_parse_json_object(response: &str) -> Option<ParseResult> {
+    let trimmed = response.trim();
+
+    // Must start with '{' to be a JSON object
+    if !trimmed.starts_with('{') {
+        return None;
+    }
+
+    let parsed: Value = serde_json::from_str(trimmed).ok()?;
+
+    // Format 1: {"tool_call": {"name": "...", "arguments": {...}}}
+    if let Some(tc) = parsed.get("tool_call") {
+        let name = tc.get("name")?.as_str()?.to_string();
+        let arguments = tc
+            .get("arguments")
+            .cloned()
+            .unwrap_or(Value::Object(Default::default()));
+        return Some(ParseResult {
+            text: String::new(),
+            tool_calls: vec![ParsedToolCall {
+                name,
+                arguments,
+                format: ToolCallFormat::JsonObject,
+            }],
+        });
+    }
+
+    // Format 2: {"tool_calls": [{"name": "...", "arguments": {...}}, ...]}
+    if let Some(tcs) = parsed.get("tool_calls").and_then(|v| v.as_array()) {
+        let calls: Vec<ParsedToolCall> = tcs
+            .iter()
+            .filter_map(|tc| {
+                let name = tc.get("name")?.as_str()?.to_string();
+                let arguments = tc
+                    .get("arguments")
+                    .cloned()
+                    .unwrap_or(Value::Object(Default::default()));
+                Some(ParsedToolCall {
+                    name,
+                    arguments,
+                    format: ToolCallFormat::JsonObject,
+                })
+            })
+            .collect();
+
+        if !calls.is_empty() {
+            return Some(ParseResult {
+                text: String::new(),
+                tool_calls: calls,
+            });
+        }
+    }
+
+    // Format 3: {"name": "...", "arguments": {...}} (bare tool call)
+    if let (Some(name), Some(_)) = (
+        parsed.get("name").and_then(|v| v.as_str()),
+        parsed.get("arguments"),
+    ) {
+        return Some(ParseResult {
+            text: String::new(),
+            tool_calls: vec![ParsedToolCall {
+                name: name.to_string(),
+                arguments: parsed
+                    .get("arguments")
+                    .cloned()
+                    .unwrap_or(Value::Object(Default::default())),
+                format: ToolCallFormat::JsonObject,
+            }],
+        });
+    }
+
+    None
+}
+
+/// Try parsing as a JSON array: `[{"name": "...", "arguments": {...}}, ...]`
+fn try_parse_json_array(response: &str) -> Option<ParseResult> {
+    let trimmed = response.trim();
+
+    if !trimmed.starts_with('[') {
+        return None;
+    }
+
+    let parsed: Vec<Value> = serde_json::from_str(trimmed).ok()?;
+
+    let calls: Vec<ParsedToolCall> = parsed
+        .iter()
+        .filter_map(|tc| {
+            let name = tc.get("name")?.as_str()?.to_string();
+            let arguments = tc
+                .get("arguments")
+                .cloned()
+                .unwrap_or(Value::Object(Default::default()));
+            Some(ParsedToolCall {
+                name,
+                arguments,
+                format: ToolCallFormat::JsonArray,
+            })
+        })
+        .collect();
+
+    if calls.is_empty() {
+        return None;
+    }
+
+    Some(ParseResult {
+        text: String::new(),
+        tool_calls: calls,
+    })
+}
+
+/// Try parsing XML format:
+/// `<tool_call><name>tool_name</name><arguments>{"key": "value"}</arguments></tool_call>`
+fn try_parse_xml(response: &str) -> Option<ParseResult> {
+    let mut calls = Vec::new();
+    let mut text_parts = Vec::new();
+    let mut remaining = response;
+
+    while let Some(start) = remaining.find("<tool_call>") {
+        // Collect text before the tool call
+        let before = &remaining[..start];
+        if !before.trim().is_empty() {
+            text_parts.push(before.trim().to_string());
+        }
+
+        let after_start = &remaining[start + "<tool_call>".len()..];
+        let end = after_start.find("</tool_call>")?;
+        let inner = &after_start[..end];
+
+        // Extract name
+        let name_start = inner.find("<name>")? + "<name>".len();
+        let name_end = inner.find("</name>")?;
+        let name = inner[name_start..name_end].trim().to_string();
+
+        // Extract arguments
+        let args = if let Some(args_start_pos) = inner.find("<arguments>") {
+            let args_content_start = args_start_pos + "<arguments>".len();
+            if let Some(args_end_pos) = inner.find("</arguments>") {
+                let args_str = inner[args_content_start..args_end_pos].trim();
+                serde_json::from_str(args_str).unwrap_or(Value::Object(Default::default()))
+            } else {
+                Value::Object(Default::default())
+            }
+        } else {
+            Value::Object(Default::default())
+        };
+
+        calls.push(ParsedToolCall {
+            name,
+            arguments: args,
+            format: ToolCallFormat::Xml,
+        });
+
+        remaining = &after_start[end + "</tool_call>".len()..];
+    }
+
+    // Collect remaining text
+    if !remaining.trim().is_empty() {
+        text_parts.push(remaining.trim().to_string());
+    }
+
+    if calls.is_empty() {
+        return None;
+    }
+
+    Some(ParseResult {
+        text: text_parts.join("\n"),
+        tool_calls: calls,
+    })
+}
+
+/// Try parsing Markdown code block format:
+/// ````tool_call
+/// {"name": "tool_name", "arguments": {"key": "value"}}
+/// ````
+fn try_parse_markdown(response: &str) -> Option<ParseResult> {
+    let mut calls = Vec::new();
+    let mut text_parts = Vec::new();
+    let mut remaining = response;
+
+    let fence_patterns = ["```tool_call\n", "```tool_call\r\n"];
+
+    loop {
+        let mut found = false;
+        for pattern in &fence_patterns {
+            if let Some(start) = remaining.find(pattern) {
+                // Collect text before the code block
+                let before = &remaining[..start];
+                if !before.trim().is_empty() {
+                    text_parts.push(before.trim().to_string());
+                }
+
+                let content_start = start + pattern.len();
+                let after_content = &remaining[content_start..];
+
+                if let Some(end) = after_content.find("```") {
+                    let block_content = after_content[..end].trim();
+
+                    // Parse the JSON inside the code block
+                    if let Ok(parsed) = serde_json::from_str::<Value>(block_content) {
+                        if let Some(name) = parsed.get("name").and_then(|v| v.as_str()) {
+                            let arguments = parsed
+                                .get("arguments")
+                                .cloned()
+                                .unwrap_or(Value::Object(Default::default()));
+                            calls.push(ParsedToolCall {
+                                name: name.to_string(),
+                                arguments,
+                                format: ToolCallFormat::Markdown,
+                            });
+                        }
+                    }
+
+                    remaining = &after_content[end + "```".len()..];
+                    found = true;
+                    break;
+                }
+            }
+        }
+
+        if !found {
+            break;
+        }
+    }
+
+    // Collect remaining text
+    if !remaining.trim().is_empty() {
+        text_parts.push(remaining.trim().to_string());
+    }
+
+    if calls.is_empty() {
+        return None;
+    }
+
+    Some(ParseResult {
+        text: text_parts.join("\n"),
+        tool_calls: calls,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ============ JSON Object Tests ============
+
+    #[test]
+    fn test_parse_json_tool_call() {
+        let input = r#"{"tool_call": {"name": "search", "arguments": {"query": "rust"}}}"#;
+        let result = parse(input);
+        assert_eq!(result.tool_calls.len(), 1);
+        assert_eq!(result.tool_calls[0].name, "search");
+        assert_eq!(result.tool_calls[0].format, ToolCallFormat::JsonObject);
+        assert_eq!(result.tool_calls[0].arguments["query"], "rust");
+    }
+
+    #[test]
+    fn test_parse_json_tool_calls_array() {
+        let input = r#"{"tool_calls": [
+            {"name": "search", "arguments": {"query": "rust"}},
+            {"name": "read_file", "arguments": {"path": "/tmp/test"}}
+        ]}"#;
+        let result = parse(input);
+        assert_eq!(result.tool_calls.len(), 2);
+        assert_eq!(result.tool_calls[0].name, "search");
+        assert_eq!(result.tool_calls[1].name, "read_file");
+    }
+
+    #[test]
+    fn test_parse_bare_json_tool_call() {
+        let input = r#"{"name": "search", "arguments": {"query": "rust"}}"#;
+        let result = parse(input);
+        assert_eq!(result.tool_calls.len(), 1);
+        assert_eq!(result.tool_calls[0].name, "search");
+    }
+
+    // ============ JSON Array Tests ============
+
+    #[test]
+    fn test_parse_json_array() {
+        let input = r#"[{"name": "search", "arguments": {"query": "rust"}}]"#;
+        let result = parse(input);
+        assert_eq!(result.tool_calls.len(), 1);
+        assert_eq!(result.tool_calls[0].format, ToolCallFormat::JsonArray);
+    }
+
+    // ============ XML Tests ============
+
+    #[test]
+    fn test_parse_xml() {
+        let input = r#"Let me search for that.
+<tool_call><name>search</name><arguments>{"query": "rust"}</arguments></tool_call>"#;
+        let result = parse(input);
+        assert_eq!(result.tool_calls.len(), 1);
+        assert_eq!(result.tool_calls[0].name, "search");
+        assert_eq!(result.tool_calls[0].format, ToolCallFormat::Xml);
+        assert!(result.text.contains("Let me search"));
+    }
+
+    #[test]
+    fn test_parse_multiple_xml() {
+        let input = r#"<tool_call><name>search</name><arguments>{"q": "a"}</arguments></tool_call>
+<tool_call><name>read</name><arguments>{"path": "b"}</arguments></tool_call>"#;
+        let result = parse(input);
+        assert_eq!(result.tool_calls.len(), 2);
+    }
+
+    // ============ Markdown Tests ============
+
+    #[test]
+    fn test_parse_markdown() {
+        let input = "Here's what I'll do:\n```tool_call\n{\"name\": \"search\", \"arguments\": {\"query\": \"rust\"}}\n```\n";
+        let result = parse(input);
+        assert_eq!(result.tool_calls.len(), 1);
+        assert_eq!(result.tool_calls[0].name, "search");
+        assert_eq!(result.tool_calls[0].format, ToolCallFormat::Markdown);
+        assert!(result.text.contains("Here's what I'll do"));
+    }
+
+    // ============ No Tool Call Tests ============
+
+    #[test]
+    fn test_parse_plain_text() {
+        let input = "This is just a normal response with no tool calls.";
+        let result = parse(input);
+        assert!(result.tool_calls.is_empty());
+        assert_eq!(result.text, input);
+    }
+
+    #[test]
+    fn test_parse_empty() {
+        let result = parse("");
+        assert!(result.tool_calls.is_empty());
+    }
+
+    // ============ Priority Tests ============
+
+    #[test]
+    fn test_json_takes_priority_over_xml() {
+        // If the response is valid JSON with tool_call, JSON wins
+        let input = r#"{"tool_call": {"name": "search", "arguments": {}}}"#;
+        let result = parse(input);
+        assert_eq!(result.tool_calls[0].format, ToolCallFormat::JsonObject);
+    }
+}

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

@@ -0,0 +1,262 @@
+//! Retry handler with exponential backoff and error classification
+//!
+//! Classifies errors as retryable (rate-limit, network, transient) vs
+//! fatal (auth, invalid request, tool not found) and manages backoff.
+//! Ported from patterns in zeroclaw and openclaw.
+
+use crate::config::RetryConfig;
+use std::time::Duration;
+
+/// Error classification for retry decisions.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ErrorKind {
+    /// Rate limited by provider — always retryable
+    RateLimited,
+    /// Network/connection error — retryable
+    NetworkError,
+    /// Transient server error (5xx) — retryable
+    ServerError,
+    /// Authentication failure — NOT retryable
+    AuthError,
+    /// Invalid request (bad input, schema mismatch) — NOT retryable
+    InvalidRequest,
+    /// Tool not found — NOT retryable
+    ToolNotFound,
+    /// Context window exceeded — needs compaction, not retry
+    ContextOverflow,
+    /// Unknown error — retryable with caution
+    Unknown,
+}
+
+impl ErrorKind {
+    /// Whether this error class is retryable.
+    pub fn is_retryable(&self) -> bool {
+        matches!(
+            self,
+            ErrorKind::RateLimited
+                | ErrorKind::NetworkError
+                | ErrorKind::ServerError
+                | ErrorKind::Unknown
+        )
+    }
+}
+
+/// Classifies an error string into an `ErrorKind`.
+///
+/// Uses heuristic keyword matching on error messages.
+/// This is intentionally simple — real providers should return structured errors.
+pub fn classify_error(error_msg: &str) -> ErrorKind {
+    let lower = error_msg.to_lowercase();
+
+    if lower.contains("rate limit") || lower.contains("429") || lower.contains("too many requests")
+    {
+        ErrorKind::RateLimited
+    } else if lower.contains("connection")
+        || lower.contains("timeout")
+        || lower.contains("network")
+        || lower.contains("dns")
+    {
+        ErrorKind::NetworkError
+    } else if lower.contains("500")
+        || lower.contains("502")
+        || lower.contains("503")
+        || lower.contains("internal server error")
+        || lower.contains("service unavailable")
+    {
+        ErrorKind::ServerError
+    } else if lower.contains("auth")
+        || lower.contains("unauthorized")
+        || lower.contains("401")
+        || lower.contains("403")
+        || lower.contains("forbidden")
+        || lower.contains("invalid api key")
+    {
+        ErrorKind::AuthError
+    } else if lower.contains("context")
+        && (lower.contains("length") || lower.contains("window") || lower.contains("exceeded"))
+    {
+        ErrorKind::ContextOverflow
+    } else if lower.contains("not found") && lower.contains("tool") {
+        ErrorKind::ToolNotFound
+    } else if lower.contains("invalid")
+        || lower.contains("malformed")
+        || lower.contains("400")
+        || lower.contains("bad request")
+    {
+        ErrorKind::InvalidRequest
+    } else {
+        ErrorKind::Unknown
+    }
+}
+
+/// Manages retry state and computes backoff delays.
+pub struct RetryHandler {
+    config: RetryConfig,
+    attempt: u32,
+}
+
+impl RetryHandler {
+    /// Create a new retry handler from config.
+    pub fn new(config: RetryConfig) -> Self {
+        Self { config, attempt: 0 }
+    }
+
+    /// Check if we should retry the given error.
+    /// Returns `Some(delay)` if retryable, `None` if fatal or max retries exceeded.
+    pub fn should_retry(&mut self, error_msg: &str) -> Option<Duration> {
+        let kind = classify_error(error_msg);
+
+        if !kind.is_retryable() {
+            tracing::warn!(
+                error_kind = ?kind,
+                "Non-retryable error, failing immediately"
+            );
+            return None;
+        }
+
+        if self.attempt >= self.config.max_retries {
+            tracing::warn!(
+                attempt = self.attempt,
+                max = self.config.max_retries,
+                "Max retries exceeded"
+            );
+            return None;
+        }
+
+        let delay = self.next_delay();
+        self.attempt += 1;
+
+        tracing::info!(
+            attempt = self.attempt,
+            delay_ms = delay.as_millis() as u64,
+            error_kind = ?kind,
+            "Retrying after transient error"
+        );
+
+        Some(delay)
+    }
+
+    /// Compute the next backoff delay using exponential backoff.
+    fn next_delay(&self) -> Duration {
+        let base = self.config.initial_delay.as_millis() as f64;
+        let multiplied = base * self.config.backoff_multiplier.powi(self.attempt as i32);
+        let capped = multiplied.min(self.config.max_delay.as_millis() as f64);
+        Duration::from_millis(capped as u64)
+    }
+
+    /// Reset retry state (call after a successful operation).
+    pub fn reset(&mut self) {
+        self.attempt = 0;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_classify_rate_limit() {
+        assert_eq!(
+            classify_error("Rate limit exceeded"),
+            ErrorKind::RateLimited
+        );
+        assert_eq!(
+            classify_error("HTTP 429 Too Many Requests"),
+            ErrorKind::RateLimited
+        );
+    }
+
+    #[test]
+    fn test_classify_network() {
+        assert_eq!(
+            classify_error("Connection refused"),
+            ErrorKind::NetworkError
+        );
+        assert_eq!(
+            classify_error("Request timeout after 30s"),
+            ErrorKind::NetworkError
+        );
+    }
+
+    #[test]
+    fn test_classify_auth() {
+        assert_eq!(classify_error("401 Unauthorized"), ErrorKind::AuthError);
+        assert_eq!(
+            classify_error("Invalid API key provided"),
+            ErrorKind::AuthError
+        );
+    }
+
+    #[test]
+    fn test_classify_context_overflow() {
+        assert_eq!(
+            classify_error("Context length exceeded: 128000 tokens"),
+            ErrorKind::ContextOverflow
+        );
+    }
+
+    #[test]
+    fn test_classify_unknown() {
+        assert_eq!(
+            classify_error("Something weird happened"),
+            ErrorKind::Unknown
+        );
+    }
+
+    #[test]
+    fn test_retryable() {
+        assert!(ErrorKind::RateLimited.is_retryable());
+        assert!(ErrorKind::NetworkError.is_retryable());
+        assert!(ErrorKind::ServerError.is_retryable());
+        assert!(ErrorKind::Unknown.is_retryable());
+        assert!(!ErrorKind::AuthError.is_retryable());
+        assert!(!ErrorKind::InvalidRequest.is_retryable());
+        assert!(!ErrorKind::ContextOverflow.is_retryable());
+    }
+
+    #[test]
+    fn test_retry_handler_backoff() {
+        let config = RetryConfig {
+            max_retries: 3,
+            initial_delay: Duration::from_secs(1),
+            max_delay: Duration::from_secs(30),
+            backoff_multiplier: 2.0,
+        };
+        let mut handler = RetryHandler::new(config);
+
+        // First retry: 1s
+        let delay = handler.should_retry("rate limit exceeded").unwrap();
+        assert_eq!(delay, Duration::from_secs(1));
+
+        // Second retry: 2s
+        let delay = handler.should_retry("rate limit exceeded").unwrap();
+        assert_eq!(delay, Duration::from_secs(2));
+
+        // Third retry: 4s
+        let delay = handler.should_retry("rate limit exceeded").unwrap();
+        assert_eq!(delay, Duration::from_secs(4));
+
+        // Fourth: exceeded max_retries=3
+        assert!(handler.should_retry("rate limit exceeded").is_none());
+    }
+
+    #[test]
+    fn test_retry_handler_non_retryable() {
+        let mut handler = RetryHandler::new(RetryConfig::default());
+        assert!(handler.should_retry("401 Unauthorized").is_none());
+    }
+
+    #[test]
+    fn test_retry_handler_reset() {
+        let mut handler = RetryHandler::new(RetryConfig {
+            max_retries: 1,
+            ..Default::default()
+        });
+
+        handler.should_retry("rate limit").unwrap();
+        assert!(handler.should_retry("rate limit").is_none());
+
+        handler.reset();
+        assert!(handler.should_retry("rate limit").is_some());
+    }
+}