feat(adaptive): add opt-in caching for tool results

crates/adaptive/src/config.rs

@@ -7,7 +7,7 @@ use nemo_relay::plugin::ConfigPolicy;
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value as Json};
 
-use crate::response_cache::config::{BackendConfig, KEY_STRATEGY_EXACT_REQUEST};
+use crate::response_cache::config::{BackendConfig, KEY_STRATEGY_EXACT_REQUEST, ToolCacheConfig};
 
 /// Canonical config document for the adaptive plugin component.
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -34,8 +34,8 @@ pub struct AdaptiveConfig {
     /// Adaptive Cache Governor settings.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub acg: Option<AcgComponentConfig>,
-    /// Opt-in LLM response cache (exact-match). When present, the
-    /// adaptive plugin installs the response-cache execution intercept(s).
+    /// Opt-in exact-match LLM response and tool-result cache. When present,
+    /// the adaptive plugin installs the response-cache execution intercept(s).
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub response_cache: Option<ResponseCacheConfig>,
     /// Adaptive-local unsupported-config policy.
@@ -191,7 +191,8 @@ impl Default for AcgComponentConfig {
     }
 }
 
-/// Configuration for the adaptive plugin's `response_cache` feature
+/// Configuration for the adaptive plugin's exact-match LLM response and
+/// opt-in tool-result cache feature.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(default)]
 pub struct ResponseCacheConfig {
@@ -217,6 +218,9 @@ pub struct ResponseCacheConfig {
     pub header_allowlist: Vec<String>,
     /// Storage backend selection.
     pub backend: BackendConfig,
+    /// Opt-in tool-result cache configuration.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tools: Option<ToolCacheConfig>,
 }
 
 impl Default for ResponseCacheConfig {
@@ -230,6 +234,7 @@ impl Default for ResponseCacheConfig {
             key_strategy: KEY_STRATEGY_EXACT_REQUEST.to_string(),
             header_allowlist: Vec::new(),
             backend: BackendConfig::default(),
+            tools: None,
         }
     }
 }
@@ -405,6 +410,13 @@ nemo_relay::editor_config! {
             nested: BackendConfig,
             default: BackendConfig,
         },
+        tools => {
+            label: "tools",
+            kind: Section,
+            optional: true,
+            nested: ToolCacheConfig,
+            default: ToolCacheConfig,
+        },
     }
 }
 

crates/adaptive/src/lib.rs

@@ -34,7 +34,7 @@ pub mod learner;
 pub mod plugin_component;
 #[cfg(feature = "redis-backend")]
 pub mod redis;
-/// Opt-in LLM response cache (exact-match).
+/// Opt-in exact-match LLM response and tool-result cache.
 pub mod response_cache;
 mod runtime;
 /// Storage backends and backend traits for adaptive state persistence.
@@ -58,6 +58,7 @@ pub use error::{AdaptiveError, Result};
 #[cfg(feature = "redis-backend")]
 pub use redis::RedisBackend;
 pub use response_cache::RESPONSE_CACHE_MARK;
+pub use response_cache::config::{ToolCacheConfig, ToolClass, ToolOverride};
 pub use runtime::features::AdaptiveRuntime;
 pub use storage::erased::AnyBackend;
 pub use storage::memory::InMemoryBackend;

crates/adaptive/src/plugin_component.rs

@@ -338,6 +338,7 @@ fn validate_response_cache_section(
             "key_strategy",
             "header_allowlist",
             "backend",
+            "tools",
         ],
     );
     if let Some(backend_json) = response_cache_json.get("backend").and_then(Json::as_object) {
@@ -361,6 +362,9 @@ fn validate_response_cache_section(
             );
         }
     }
+    if let Some(tools_json) = response_cache_json.get("tools").and_then(Json::as_object) {
+        validate_response_cache_tools_fields(diagnostics, policy, tools_json);
+    }
 }
 
 fn validate_response_cache_backend_config_fields(
@@ -383,6 +387,79 @@ fn validate_response_cache_backend_config_fields(
     );
 }
 
+fn validate_response_cache_tools_fields(
+    diagnostics: &mut Vec<ConfigDiagnostic>,
+    policy: &ConfigPolicy,
+    tools_json: &Map<String, Json>,
+) {
+    const CLASS_FIELDS: &[&str] = &[
+        "cacheable",
+        "ttl_seconds",
+        "bypass_rate",
+        "tool_version",
+        "arg_skip",
+        "members",
+    ];
+    const OVERRIDE_FIELDS: &[&str] = &[
+        "cacheable",
+        "ttl_seconds",
+        "bypass_rate",
+        "tool_version",
+        "arg_skip",
+    ];
+
+    validate_unknown_fields(
+        diagnostics,
+        policy,
+        Some("response_cache.tools".to_string()),
+        tools_json,
+        &[
+            "enabled",
+            "priority",
+            "cache_errors",
+            "default",
+            "classes",
+            "overrides",
+        ],
+    );
+
+    if let Some(default_json) = tools_json.get("default").and_then(Json::as_object) {
+        validate_unknown_fields(
+            diagnostics,
+            policy,
+            Some("response_cache.tools.default".to_string()),
+            default_json,
+            CLASS_FIELDS,
+        );
+    }
+    if let Some(classes_json) = tools_json.get("classes").and_then(Json::as_object) {
+        for (class_name, class_value) in classes_json {
+            if let Some(class_object) = class_value.as_object() {
+                validate_unknown_fields(
+                    diagnostics,
+                    policy,
+                    Some(format!("response_cache.tools.classes.{class_name}")),
+                    class_object,
+                    CLASS_FIELDS,
+                );
+            }
+        }
+    }
+    if let Some(overrides_json) = tools_json.get("overrides").and_then(Json::as_object) {
+        for (tool_name, override_value) in overrides_json {
+            if let Some(override_object) = override_value.as_object() {
+                validate_unknown_fields(
+                    diagnostics,
+                    policy,
+                    Some(format!("response_cache.tools.overrides.{tool_name}")),
+                    override_object,
+                    OVERRIDE_FIELDS,
+                );
+            }
+        }
+    }
+}
+
 fn validate_backend_config_fields(
     diagnostics: &mut Vec<ConfigDiagnostic>,
     policy: &ConfigPolicy,

crates/adaptive/src/response_cache/config.rs

@@ -9,6 +9,8 @@
 //! response-cache-specific backend config and the key-strategy constant next to
 //! the key/store code that consumes them.
 
+use std::collections::BTreeMap;
+
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value as Json};
 
@@ -63,3 +65,129 @@ nemo_relay::editor_config! {
         config => { label: "config", kind: Json },
     }
 }
+
+/// Opt-in tool-result cache configuration.
+///
+/// Cache only tools that are read-only and stable for their TTL.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default)]
+pub struct ToolCacheConfig {
+    /// Master switch; off by default.
+    pub enabled: bool,
+    /// Tool execution-intercept priority. The default keeps standard
+    /// priority-100 guardrails outside cache hits.
+    pub priority: i32,
+    /// Whether conventional in-band tool error results may be stored.
+    pub cache_errors: bool,
+    /// Policy for unclassified tools; not cacheable by default.
+    pub default: ToolClass,
+    /// Named tool classes.
+    pub classes: BTreeMap<String, ToolClass>,
+    /// Per-tool refinements keyed by exact name, `prefix*`, `*suffix`, or `*contains*`.
+    pub overrides: BTreeMap<String, ToolOverride>,
+}
+
+impl Default for ToolCacheConfig {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            priority: 150,
+            cache_errors: false,
+            default: ToolClass::default(),
+            classes: BTreeMap::new(),
+            overrides: BTreeMap::new(),
+        }
+    }
+}
+
+nemo_relay::editor_config! {
+    impl ToolCacheConfig {
+        enabled => { label: "enabled", kind: Boolean },
+        priority => { label: "priority", kind: Integer },
+        cache_errors => { label: "cache_errors", kind: Boolean },
+        default => {
+            label: "default",
+            kind: Section,
+            nested: ToolClass,
+            default: ToolClass,
+        },
+        classes => { label: "classes", kind: Json },
+        overrides => { label: "overrides", kind: Json },
+    }
+}
+
+/// Policy shared by a class of tools.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(default)]
+pub struct ToolClass {
+    /// Whether class members may be served from cache.
+    pub cacheable: bool,
+    /// TTL in seconds; inherits the response-cache TTL when unset.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ttl_seconds: Option<u64>,
+    /// Live-rerun probability; inherits the response-cache rate when unset.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub bypass_rate: Option<f64>,
+    /// Version string folded into cache keys for members of this class.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_version: Option<String>,
+    /// Top-level argument keys dropped before keying.
+    pub arg_skip: Vec<String>,
+    /// Exact tool names, `prefix*`, `*suffix`, or `*contains*` patterns in this class.
+    pub members: Vec<String>,
+}
+
+/// Per-tool refinement applied after class resolution.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(default)]
+pub struct ToolOverride {
+    /// Overrides the class cacheability.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cacheable: Option<bool>,
+    /// Overrides the class TTL.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ttl_seconds: Option<u64>,
+    /// Overrides the class bypass rate.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub bypass_rate: Option<f64>,
+    /// Version string folded into the cache key.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_version: Option<String>,
+    /// Replaces the class argument skip list when set.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub arg_skip: Option<Vec<String>>,
+}
+
+nemo_relay::editor_config! {
+    impl ToolClass {
+        cacheable => { label: "cacheable", kind: Boolean },
+        ttl_seconds => { label: "ttl_seconds", kind: Integer, optional: true },
+        bypass_rate => { label: "bypass_rate", kind: Float, optional: true },
+        tool_version => { label: "tool_version", kind: String, optional: true },
+        arg_skip => {
+            label: "arg_skip",
+            kind: List,
+            list: &nemo_relay::config_editor::STRING_LIST_ITEM,
+        },
+        members => {
+            label: "members",
+            kind: List,
+            list: &nemo_relay::config_editor::STRING_LIST_ITEM,
+        },
+    }
+}
+
+nemo_relay::editor_config! {
+    impl ToolOverride {
+        cacheable => { label: "cacheable", kind: Boolean, optional: true },
+        ttl_seconds => { label: "ttl_seconds", kind: Integer, optional: true },
+        bypass_rate => { label: "bypass_rate", kind: Float, optional: true },
+        tool_version => { label: "tool_version", kind: String, optional: true },
+        arg_skip => {
+            label: "arg_skip",
+            kind: List,
+            optional: true,
+            list: &nemo_relay::config_editor::STRING_LIST_ITEM,
+        },
+    }
+}