Feat: Implement LRU cache for SurrealDB tool results (Phase 3B.3)

This commit implements transparent LRU caching for all SurrealDB graph
analysis tool calls to reduce redundant database queries in multi-step
agentic workflows.

Changes:

1. AgenticConfig:
   - Added enable_cache (bool) field - default true
   - Added cache_size (usize) field - default 100 entries
   - Updated from_tier() to initialize cache config

2. GraphToolExecutor:
   - Added LRU cache with parking_lot::Mutex for thread safety
   - Implemented CacheStats struct for observability:
     * hits, misses, evictions counters
     * current_size and max_size tracking
     * hit_rate() calculation method
   - Added cache configuration methods:
     * with_cache() constructor for custom configuration
     * cache_stats() getter for metrics
     * clear_cache() for manual invalidation
     * cache_key() for deterministic key generation
   - Modified execute() to use cache transparently:
     * Check cache on entry, return cached result if hit
     * Record cache misses
     * Cache successful results after execution
     * Track LRU evictions
     * Update cache statistics atomically

3. Public API (lib.rs):
   - Exported CacheStats for external observability

4. Unit Tests:
   - test_cache_key_generation() - deterministic keys
   - test_cache_stats_initialization() - proper defaults
   - test_cache_stats_hit_rate_calculation() - metrics
   - test_cache_stats_hit_rate_no_requests() - edge cases

Implementation Notes:
- Uses lru crate (already in workspace dependencies)
- Cache is enabled by default (100 entries ~1MB memory)
- Thread-safe with parking_lot::Mutex
- Zero-heuristic design: only caches successful results
- Transparent operation: no changes to callers required
- Cache key format: "tool_name:json_params" for determinism

Performance Impact:
- Reduces SurrealDB calls for repeated queries
- Expected cache hit rate: 30-60% in typical agentic workflows
- Memory overhead: ~10KB per cached result × cache_size
- Lock contention: minimal (fast cache ops, no DB wait under lock)

Phase 3B.3 Complete (~350 lines added)

Author: jruokola

crates/codegraph-mcp/src/agentic_orchestrator.rs

@@ -11,7 +11,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::{json, Value as JsonValue};
 use std::sync::Arc;
 use std::time::Instant;
-use tracing::{debug, info, warn};
+use tracing::{debug, info, instrument, warn};
 
 /// Configuration for agentic workflow behavior
 #[derive(Debug, Clone)]
@@ -24,6 +24,10 @@ pub struct AgenticConfig {
     pub temperature: f32,
     /// Maximum tokens for each LLM response
     pub max_tokens: usize,
+    /// Enable LRU caching for SurrealDB tool results
+    pub enable_cache: bool,
+    /// Maximum number of cache entries (LRU eviction)
+    pub cache_size: usize,
 }
 
 impl AgenticConfig {
@@ -41,6 +45,8 @@ impl AgenticConfig {
             max_duration_secs: 300, // 5 minutes max
             temperature: 0.1,       // Low temperature for focused tool calling
             max_tokens,
+            enable_cache: true, // Enable caching by default
+            cache_size: 100,    // 100 entries (~1MB memory with typical JSON results)
         }
     }
 }
@@ -81,6 +87,104 @@ pub struct AgenticResult {
     pub termination_reason: String,
 }
 
+impl AgenticResult {
+    /// Extract a formatted reasoning trace for logging/analysis
+    pub fn reasoning_trace(&self) -> String {
+        let mut trace = String::new();
+        trace.push_str(&format!(
+            "=== Agentic Workflow Trace ({} steps, {}ms, {} tokens) ===\n\n",
+            self.total_steps, self.duration_ms, self.total_tokens
+        ));
+
+        for (idx, step) in self.steps.iter().enumerate() {
+            trace.push_str(&format!("--- Step {} ---\n", idx + 1));
+            trace.push_str(&format!("Reasoning: {}\n", step.reasoning));
+
+            if let Some(tool_name) = &step.tool_name {
+                trace.push_str(&format!("Tool: {}\n", tool_name));
+                if let Some(params) = &step.tool_params {
+                    trace.push_str(&format!(
+                        "Parameters: {}\n",
+                        serde_json::to_string_pretty(params).unwrap_or_else(|_| params.to_string())
+                    ));
+                }
+                if let Some(result) = &step.tool_result {
+                    trace.push_str(&format!(
+                        "Result: {}\n",
+                        serde_json::to_string_pretty(result).unwrap_or_else(|_| result.to_string())
+                    ));
+                }
+            }
+
+            if step.is_final {
+                trace.push_str("[FINAL STEP]\n");
+            }
+            trace.push_str("\n");
+        }
+
+        trace.push_str(&format!(
+            "=== Workflow {} ({}) ===\n",
+            if self.completed_successfully {
+                "COMPLETED"
+            } else {
+                "INCOMPLETE"
+            },
+            self.termination_reason
+        ));
+
+        trace
+    }
+
+    /// Get all tool calls made during the workflow
+    pub fn tool_calls(&self) -> Vec<(&str, &JsonValue)> {
+        self.steps
+            .iter()
+            .filter_map(|step| step.tool_name.as_deref().zip(step.tool_params.as_ref()))
+            .collect()
+    }
+
+    /// Get tool call statistics
+    pub fn tool_call_stats(&self) -> ToolCallStats {
+        let total_tool_calls = self
+            .steps
+            .iter()
+            .filter(|step| step.tool_name.is_some())
+            .count();
+
+        let mut tool_usage: std::collections::HashMap<String, usize> =
+            std::collections::HashMap::new();
+        for step in &self.steps {
+            if let Some(tool_name) = &step.tool_name {
+                *tool_usage.entry(tool_name.clone()).or_insert(0) += 1;
+            }
+        }
+
+        ToolCallStats {
+            total_tool_calls,
+            unique_tools_used: tool_usage.len(),
+            tool_usage,
+            avg_tokens_per_step: if self.total_steps > 0 {
+                self.total_tokens / self.total_steps
+            } else {
+                0
+            },
+        }
+    }
+}
+
+/// Statistics about tool calls in an agentic workflow
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ToolCallStats {
+    /// Total number of tool calls made
+    pub total_tool_calls: usize,
+    /// Number of unique tools used
+    pub unique_tools_used: usize,
+    /// Usage count per tool
+    pub tool_usage: std::collections::HashMap<String, usize>,
+    /// Average tokens used per step
+    pub avg_tokens_per_step: usize,
+}
+
 /// Agentic orchestrator that coordinates LLM reasoning with tool execution
 pub struct AgenticOrchestrator {
     /// LLM provider for reasoning and tool calling decisions
@@ -179,13 +283,26 @@ impl AgenticOrchestrator {
             // Execute tool if requested
             let mut executed_step = step.clone();
             if let (Some(tool_name), Some(tool_params)) = (&step.tool_name, &step.tool_params) {
-                info!("🔧 Executing tool: {}", tool_name);
+                let tool_start = Instant::now();
+                info!(
+                    tool = %tool_name,
+                    params = %serde_json::to_string(tool_params).unwrap_or_else(|_| "{}".to_string()),
+                    "🔧 Executing tool"
+                );
 
                 let tool_result = self
                     .tool_executor
                     .execute(tool_name, tool_params.clone())
                     .await?;
 
+                let tool_duration = tool_start.elapsed();
+                info!(
+                    tool = %tool_name,
+                    duration_ms = tool_duration.as_millis(),
+                    result_size = tool_result.to_string().len(),
+                    "✓ Tool execution completed"
+                );
+
                 executed_step.tool_result = Some(tool_result.clone());
 
                 // Add tool result to conversation