fix(mlx): tools-aware prefix-cache boundary + incremental default-on

Agentic (tools) requests cold-re-prefilled the full ~48K system+tools
head on every client compaction. The tools path stored the full prompt
and matched via starts_with, so it only HIT on turn-to-turn extension;
a compaction (rewritten early messages -> divergent tail) missed and
re-prefilled from scratch (~98s for a 48K head).

Two-part fix:
- detect_system_tools_prefix_len[_from_turns]: snapshot the boundary at
  the rendered system+tools head (~47980 tok) instead of system-only
  (~22830), so the ~25K-token tool-schema block is inside the pinned
  boundary. Wired into all 4 tools call sites; render_tools_system_block
  made pub(crate). Safe: the store snapshots prompt_ids[..b] (real token
  prefix), so an off-by-a-token boundary can only under/over-cache,
  never corrupt KV.
- DEFAULT_INCREMENTAL false -> true: incremental boundary caching now
  default-on (revert with LUMEN_MLX_PREFIX_INCREMENTAL=0).

Verified on live 35B: second same-system/same-tools request forks the
1733-token head and prefills only the 20-token divergent tail
(2357ms -> 102ms, 23x), output correct.

Author: rabbitson87

crates/lumen-mlx/src/lib.rs

@@ -3449,7 +3449,7 @@ impl MlxQwen35Backend {
         let grammar = self.build_qwen35_tool_grammar(tools, tool_choice);
         let prefix_key = auto_prefix_key(messages);
         let incremental_boundary = self
-            .detect_system_prefix_len(messages)
+            .detect_system_tools_prefix_len(messages, tools)
             .ok()
             .filter(|&b| b > 0 && b < prompt_ids.len());
         self.chat_with_tools_impl(
@@ -3492,7 +3492,7 @@ impl MlxQwen35Backend {
         let grammar = self.build_qwen35_tool_grammar(tools, tool_choice);
         let prefix_key = auto_prefix_key(messages);
         let incremental_boundary = self
-            .detect_system_prefix_len(messages)
+            .detect_system_tools_prefix_len(messages, tools)
             .ok()
             .filter(|&b| b > 0 && b < prompt_ids.len());
         self.chat_with_tools_impl(
@@ -3528,7 +3528,7 @@ impl MlxQwen35Backend {
         let grammar = self.build_qwen35_tool_grammar(tools, tool_choice);
         let prefix_key = auto_prefix_key_from_turns(turns);
         let incremental_boundary = self
-            .detect_system_prefix_len_from_turns(turns)
+            .detect_system_tools_prefix_len_from_turns(turns, tools)
             .ok()
             .filter(|&b| b > 0 && b < prompt_ids.len());
         self.chat_with_tools_impl(
@@ -3568,7 +3568,7 @@ impl MlxQwen35Backend {
         let grammar = self.build_qwen35_tool_grammar(tools, tool_choice);
         let prefix_key = auto_prefix_key_from_turns(turns);
         let incremental_boundary = self
-            .detect_system_prefix_len_from_turns(turns)
+            .detect_system_tools_prefix_len_from_turns(turns, tools)
             .ok()
             .filter(|&b| b > 0 && b < prompt_ids.len());
         self.chat_with_tools_impl(
@@ -4194,6 +4194,52 @@ impl MlxQwen35Backend {
         Ok(sys_ids.len())
     }
 
+    /// Tools-aware variant of [`Self::detect_system_prefix_len`]: returns the
+    /// token length of the **system + rendered-tools** head — the stable prefix
+    /// every same-system/same-tools request shares, which is what the agentic
+    /// chat path actually re-uses across turns and client compactions. The
+    /// plain system-only boundary leaves the ~25K-token tool-schema block out
+    /// of the snapshot, so it gets cold-prefilled every divergent turn; this
+    /// captures it. Mirrors exactly what `format_qwen3_chat_with_tools_*` emits
+    /// before the first body turn (`render_tools_system_block`), so
+    /// `prompt_ids[..len]` is a strict prefix. Falls back to the system-only
+    /// boundary when there are no tools.
+    fn detect_system_tools_prefix_len(
+        &self,
+        messages: &[(String, String)],
+        tools: &[crate::chat_io::ToolDef<'_>],
+    ) -> Result<usize> {
+        if tools.is_empty() {
+            return self.detect_system_prefix_len(messages);
+        }
+        let leading_system = match messages.first() {
+            Some((role, text)) if role == "system" && !text.is_empty() => Some(text.as_str()),
+            _ => None,
+        };
+        let block = crate::qwen3_5_tools::render_tools_system_block(tools, leading_system);
+        let ids = self.encode(&block)?;
+        Ok(ids.len())
+    }
+
+    /// `detect_system_tools_prefix_len` for the structured-history shape.
+    fn detect_system_tools_prefix_len_from_turns(
+        &self,
+        turns: &[crate::chat_io::ChatTurn<'_>],
+        tools: &[crate::chat_io::ToolDef<'_>],
+    ) -> Result<usize> {
+        use crate::chat_io::ChatTurn;
+        if tools.is_empty() {
+            return self.detect_system_prefix_len_from_turns(turns);
+        }
+        let leading_system = match turns.first() {
+            Some(ChatTurn::System(s)) if !s.is_empty() => Some(*s),
+            _ => None,
+        };
+        let block = crate::qwen3_5_tools::render_tools_system_block(tools, leading_system);
+        let ids = self.encode(&block)?;
+        Ok(ids.len())
+    }
+
     /// Drop a prefix-cache entry by key, releasing its master snapshot.
     /// Returns true if the entry existed.
     pub fn drop_prefix_cache(&mut self, key: &str) -> bool {

crates/lumen-mlx/src/prefix_cache.rs

@@ -38,10 +38,14 @@ use std::time::{Duration, Instant};
 /// Default per-key branch cap when `LUMEN_MLX_PREFIX_CACHE_BRANCHES` is unset.
 const DEFAULT_BRANCHES: usize = 4;
 
-/// Default for incremental chunked-prefill boundary caching (Phase 0). OFF so
-/// the cold-MISS path is byte-identical to the pre-Phase-0 single-prefill until
-/// explicitly enabled via `LUMEN_MLX_PREFIX_INCREMENTAL`.
-const DEFAULT_INCREMENTAL: bool = false;
+/// Default for incremental chunked-prefill boundary caching (Phase 0). **ON**:
+/// on a cold MISS the stable head (system + rendered tools, via the tools-aware
+/// boundary in `lib.rs::detect_system_tools_prefix_len*`) is snapshotted as a
+/// `pinned_boundary` branch so a later same-system/same-tools but divergent-tail
+/// prompt (e.g. a client compaction/resume) FORKS the ~48K head instead of
+/// cold-prefilling it again (~98s → ~1-2s on the agentic path). Set
+/// `LUMEN_MLX_PREFIX_INCREMENTAL=0` to revert to the byte-identical single-prefill.
+const DEFAULT_INCREMENTAL: bool = true;
 
 /// The minimal runner surface the prefix cache needs. A backend implements this
 /// for its runner type — e.g. a blanket impl over a richer internal `Runner`

crates/lumen-mlx/src/qwen3_5_tools.rs

@@ -85,7 +85,10 @@ const TOOL_INSTRUCTION_BLOCK: &str = "\n\nIf you choose to call a function ONLY
 /// Render the system prefix containing the `<tools>` block + instruction.
 /// Optional existing system content is appended after the IMPORTANT block,
 /// separated by `\n\n` — matches Qwen's template behavior.
-fn render_tools_system_block(tools: &[ToolDef<'_>], extra_system: Option<&str>) -> String {
+pub(crate) fn render_tools_system_block(
+    tools: &[ToolDef<'_>],
+    extra_system: Option<&str>,
+) -> String {
     let mut s = String::new();
     s.push_str("<|im_start|>system\n");
     s.push_str("# Tools\n\nYou have access to the following functions:\n\n<tools>");