lynkr 9.9.1 → 9.11.0

package/src/config/index.js

@@ -179,14 +179,6 @@ if (!SUPPORTED_MODEL_PROVIDERS.has(rawFallbackProvider)) {
 
 const fallbackProvider = rawFallbackProvider;
 
-// Tool execution mode: server (default), client, or passthrough
-const toolExecutionMode = (process.env.TOOL_EXECUTION_MODE ?? "server").toLowerCase();
-if (!["server", "client", "passthrough"].includes(toolExecutionMode)) {
-  throw new Error(
-    "TOOL_EXECUTION_MODE must be one of: server, client, passthrough (default: server)"
-  );
-}
-
 // Memory system configuration (Titans-inspired long-term memory)
 const memoryEnabled = process.env.MEMORY_ENABLED !== "false"; // default true
 const memoryRetrievalLimit = Number.parseInt(process.env.MEMORY_RETRIEVAL_LIMIT ?? "5", 10);
@@ -201,7 +193,6 @@ const memoryDecayHalfLifeDays = Number.parseInt(process.env.MEMORY_DECAY_HALF_LI
 
 // Token optimization settings
 const tokenTrackingEnabled = process.env.TOKEN_TRACKING_ENABLED !== "false"; // default true
-const toolTruncationEnabled = process.env.TOOL_TRUNCATION_ENABLED !== "false"; // default true
 const memoryFormat = (process.env.MEMORY_FORMAT ?? "compact").toLowerCase();
 const memoryDedupEnabled = process.env.MEMORY_DEDUP_ENABLED !== "false"; // default true
 const memoryDedupLookback = Number.parseInt(process.env.MEMORY_DEDUP_LOOKBACK ?? "5", 10);
@@ -526,14 +517,9 @@ const testProfiles = parseJson(process.env.WORKSPACE_TEST_PROFILES ?? "", null);
 
 // Agents configuration
 const agentsEnabled = process.env.AGENTS_ENABLED === "true";
-const agentsMaxConcurrent = Number.parseInt(process.env.AGENTS_MAX_CONCURRENT ?? "10", 10);
-const agentsDefaultModel = process.env.AGENTS_DEFAULT_MODEL ?? "haiku";
-const agentsMaxSteps = Number.parseInt(process.env.AGENTS_MAX_STEPS ?? "15", 10);
-const agentsTimeout = Number.parseInt(process.env.AGENTS_TIMEOUT ?? "120000", 10);
 
 // Task decomposition configuration (opt-in; builds on the agents subsystem).
 // Single env toggle; everything else is hardcoded below.
-const taskDecompositionEnabled = process.env.TASK_DECOMPOSITION_ENABLED === "true";
 
 // Tier-aware fallback (escalate-then-demote) is always on (hardcoded).
 
@@ -667,7 +653,6 @@ var config = {
     openRouterMaxToolsForRouting,
     fallbackProvider,
   },
-  toolExecutionMode,
   toolResultCompression: {
     enabled: true,
   },
@@ -777,10 +762,6 @@ var config = {
       manifestPath: sandboxManifestPath,
       manifestDirs: sandboxManifestDirs,
     },
-    codeMode: {
-      enabled: process.env.CODE_MODE_ENABLED === 'true',
-      toolListCacheTtl: parseInt(process.env.CODE_MODE_CACHE_TTL, 10) || 60_000,
-    },
   },
   promptCache: {
     enabled: promptCacheEnabled,
@@ -794,25 +775,10 @@ var config = {
     ttlMs: Number.parseInt(process.env.SEMANTIC_CACHE_TTL_MS ?? "300000", 10),  // 5 minutes (was 1 hour)
   },
   agents: {
+    // Sole remaining knob: gates the agent-delegation instructions injected
+    // into the system prompt (the CLIENT's Task tool). Execution-related
+    // agent config died with server-mode tool execution.
     enabled: agentsEnabled,
-    maxConcurrent: Number.isNaN(agentsMaxConcurrent) ? 10 : agentsMaxConcurrent,
-    defaultModel: agentsDefaultModel,
-    maxSteps: Number.isNaN(agentsMaxSteps) ? 15 : agentsMaxSteps,
-    timeout: Number.isNaN(agentsTimeout) ? 120000 : agentsTimeout,
-  },
-  taskDecomposition: {
-    enabled: taskDecompositionEnabled, // only env-driven knob (TASK_DECOMPOSITION_ENABLED)
-    // Hardcoded defaults — tune here if needed.
-    shadow: false,
-    planModel: "sonnet",
-    synthModel: "sonnet",
-    minConfidence: 0.5,
-    gate: {
-      minComplexity: 60,
-      minTokens: 3000,
-      maxSubtasks: 6,
-      minIndependentUnits: 2,
-    },
   },
   tierFallback: {
     enabled: true, // always on (hardcoded): escalate-then-demote on provider failure; floor = SIMPLE
@@ -843,6 +809,33 @@ var config = {
     extraction: {
       enabled: memoryExtractionEnabled,
     },
+    // TencentDB-Agent-Memory-inspired token optimization (L0-L3 pipeline).
+    // Fixed defaults by design — tune here, not via env.
+    distillation: {
+      enabled: true,
+      turnThreshold: 10, // distill once conversation reaches 10 user turns
+      keepRecentTurns: 3, // last 3 user turns stay verbatim
+      // Size-based rescue trigger: fires regardless of turn count once the
+      // history alone hits this many estimated tokens, so small-context
+      // local models (4k-8k) don't overflow before the turn threshold.
+      tokenThreshold: 3000,
+      // Cache-aware routing (Phase 5): once emitted, the distilled block is
+      // frozen and only re-distilled every this-many user turns, so the
+      // block stays byte-identical between refreshes and compounds provider
+      // prompt-cache hits instead of rewriting history on every request.
+      // The stable-breakpoint hierarchy in prompt-cache-injection.js shares
+      // this K for its frozen history boundary.
+      refreshEveryTurns: 5,
+    },
+    skills: {
+      enabled: true,
+      minSavings: 0.6, // compression outcome must save 60%+ to be cached
+    },
+    wiki: {
+      enabled: true,
+      minTokens: 500, // register blocks larger than ~500 tokens
+      similarityThreshold: 0.85,
+    },
     decay: {
       enabled: memoryDecayEnabled,
       halfLifeDays: Number.isNaN(memoryDecayHalfLifeDays) ? 30 : memoryDecayHalfLifeDays,
@@ -851,9 +844,6 @@ var config = {
   tokenTracking: {
     enabled: tokenTrackingEnabled,
   },
-  toolTruncation: {
-    enabled: toolTruncationEnabled,
-  },
   systemPrompt: {
     mode: systemPromptMode,
     toolDescriptions: toolDescriptions,
@@ -925,6 +915,41 @@ var config = {
     provider: headroomProvider,
     logLevel: headroomLogLevel,
   },
+  // TencentDB-Agent-Memory sidecar (memory-core + memory-hub, Docker Hub
+  // `agentmemory/*` images). Opt-in like Headroom; when enabled, `lynkr start`
+  // launches both containers. Their internal LLM calls default to routing
+  // back through Lynkr itself, so no extra API key is needed.
+  tencentdbMemory: {
+    enabled: process.env.TENCENTDB_MEMORY_ENABLED === "true",
+    docker: {
+      enabled: process.env.TENCENTDB_MEMORY_DOCKER_ENABLED !== "false", // default true when sidecar enabled
+      network: "tdai-memory-stack",
+      core: {
+        image: process.env.TENCENTDB_MEMORY_CORE_IMAGE ?? "agentmemory/memory-core:latest",
+        containerName: "tdai-memory-core",
+        port: Number.parseInt(process.env.TENCENTDB_MEMORY_CORE_PORT ?? "8420", 10),
+        volume: "tdai-memory-core-data",
+      },
+      hub: {
+        image: process.env.TENCENTDB_MEMORY_HUB_IMAGE ?? "agentmemory/memory-hub:latest",
+        containerName: "tdai-memory-hub",
+        panelPort: Number.parseInt(process.env.TENCENTDB_MEMORY_PANEL_PORT ?? "8125", 10),
+        knowledgePort: Number.parseInt(process.env.TENCENTDB_MEMORY_KNOWLEDGE_PORT ?? "8424", 10),
+        volume: "tdai-panel-data",
+      },
+    },
+    // LLM the memory services use for extraction/summarization/wiki ingest.
+    // Defaults route through Lynkr's own OpenAI-compatible endpoint (tier
+    // routing decides the actual model), so local Ollama setups run free.
+    llm: {
+      baseUrl: process.env.TENCENTDB_MEMORY_LLM_BASE_URL
+        ?? `http://host.docker.internal:${Number.isNaN(port) ? 8080 : port}/v1`,
+      apiKey: process.env.TENCENTDB_MEMORY_LLM_API_KEY ?? "lynkr-local",
+      model: process.env.TENCENTDB_MEMORY_LLM_MODEL ?? "auto",
+      protocol: process.env.TENCENTDB_MEMORY_LLM_PROTOCOL ?? "openai",
+    },
+    promptMode: process.env.TENCENTDB_MEMORY_PROMPT_MODE ?? "code", // code | chat
+  },
   security: {
     // Content filtering
     contentFilterEnabled: process.env.SECURITY_CONTENT_FILTER_ENABLED !== "false", // default true
@@ -986,6 +1011,21 @@ var config = {
     // If all exit 0, short-circuit the request with zero LLM cost.
     preflightEnabled: process.env.LYNKR_PREFLIGHT_ENABLED === 'true',
     preflightTimeoutMs: Number(process.env.LYNKR_PREFLIGHT_TIMEOUT_MS) || 120000,
+    // Cache-aware routing (Phases 1-3). Fixed defaults by design — tune
+    // here, not via env (same policy as memory.distillation).
+    cacheAware: {
+      enabled: true,
+      // Median remaining turns assumed when telemetry is too sparse to
+      // estimate — conservative so a warm pin isn't dropped for a switch
+      // that only pays off over a long horizon that may not happen.
+      defaultRemainingTurns: 10,
+      // Per-turn size assumptions when the payload gives no better signal.
+      newTokensPerTurn: 2000,
+      outputTokensPerTurn: 800,
+      // Local models: switching costs prefill latency, not dollars. Hold
+      // the pin while the warm prefix exceeds this many tokens.
+      localMaxSwitchPrefixTokens: 16000,
+    },
   },
 
   // Model Tier Configuration (REQUIRED)
@@ -1010,6 +1050,8 @@ var config = {
     command: process.env.CODE_GRAPH_COMMAND || 'graphify',
     workspace: process.env.CODE_GRAPH_WORKSPACE || process.cwd(),
     timeout: parseInt(process.env.CODE_GRAPH_TIMEOUT, 10) || 10000,
+    maxDepth: 2, // symbol dependency depth for graph queries
+    maxFiles: 5, // max files returned as relevant context
   },
 
   // Large payload optimization (skip cloning media blocks that get discarded)
@@ -1092,9 +1134,6 @@ function reloadConfig() {
   // Graphify
   config.codeGraph.enabled = process.env.CODE_GRAPH_ENABLED === 'true';
 
-  // Code Mode
-  config.mcp.codeMode.enabled = process.env.CODE_MODE_ENABLED === 'true';
-
   // Log level
   config.logger.level = process.env.LOG_LEVEL ?? "info";
 

package/src/context/compression.js

@@ -13,6 +13,13 @@ const logger = require('../logger');
 const config = require('../config');
 const distill = require('./distill');
 
+// Lazy-loaded so requiring this module doesn't pull in the SQLite store
+let skillsCache = null;
+function getSkillsCache() {
+  if (!skillsCache) skillsCache = require('../memory/skills-cache');
+  return skillsCache;
+}
+
 /**
  * Compress conversation history to fit within token budget
  *
@@ -277,14 +284,26 @@ function compressToolResultBlock(block, options = {}) {
     tool_use_id: block.tool_use_id,
   };
 
-  // Compress content using Distill when content is large enough to benefit
+  // Compress content using Distill when content is large enough to benefit.
+  // The skills cache remembers how each output shape compressed before:
+  // known-futile shapes skip dedup work, proven-compressible shapes get a
+  // tighter length budget.
+  const compressWithSkills = (text, previousResult) => {
+    const skills = getSkillsCache();
+    const hints = skills.getCompressionHints(text);
+    const result = distill.compressToolResult(text, {
+      previousResult,
+      maxLength: Math.floor(500 * hints.maxLengthFactor),
+      skipDedup: hints.skipDedup,
+    });
+    const savings = text.length > 0 ? 1 - result.text.length / text.length : 0;
+    skills.record(hints.signature, result.method, savings);
+    return result.text;
+  };
+
   if (typeof block.content === 'string') {
     if (block.content.length > 500) {
-      const result = distill.compressToolResult(block.content, {
-        previousResult: options.previousResult,
-        maxLength: 500,
-      });
-      compressed.content = result.text;
+      compressed.content = compressWithSkills(block.content, options.previousResult);
     } else {
       compressed.content = block.content;
     }
@@ -292,14 +311,14 @@ function compressToolResultBlock(block, options = {}) {
     compressed.content = block.content.map(item => {
       if (typeof item === 'string') {
         if (item.length > 500) {
-          return distill.compressToolResult(item, { maxLength: 500 }).text;
+          return compressWithSkills(item);
         }
         return item;
       } else if (item.type === 'text') {
         if (item.text && item.text.length > 500) {
           return {
             type: 'text',
-            text: distill.compressToolResult(item.text, { maxLength: 500 }).text,
+            text: compressWithSkills(item.text),
           };
         }
         return item;

package/src/context/distill.js

@@ -342,6 +342,7 @@ function deduplicateBlocks(blocks, options = {}) {
  * @param {Object} options
  * @param {string} options.previousResult - Previous tool result for delta rendering
  * @param {number} options.maxLength - Max output length (default 1000)
+ * @param {boolean} options.skipDedup - Skip section dedup (known-futile shapes)
  * @returns {Object} { text, method, stats }
  */
 function compressToolResult(text, options = {}) {
@@ -380,7 +381,7 @@ function compressToolResult(text, options = {}) {
   }
 
   // Step 3: Internal dedup — split into logical sections and dedup
-  const sections = result.split(/\n{2,}/);
+  const sections = options.skipDedup ? [] : result.split(/\n{2,}/);
   if (sections.length > 3) {
     const { compressed, stats } = deduplicateBlocks(sections);
     if (stats.duplicatesRemoved > 0) {

package/src/dashboard/api.js

@@ -205,7 +205,11 @@ function routing(req, res) {
       if (s) providerStats[p] = s;
     }
 
-    res.json({ tierDefinitions: TIER_DEFINITIONS, accuracy, stats, providerStats, circuitBreakers: cbStates, window: win.label });
+    // Cache-aware routing (Phase 6): per-decision switch/hold economics,
+    // aggregated into "cache dollars saved by routing".
+    const cacheEconomics = telemetry.getCacheEconomics({ since });
+
+    res.json({ tierDefinitions: TIER_DEFINITIONS, accuracy, stats, providerStats, circuitBreakers: cbStates, cacheEconomics, window: win.label });
   } catch (e) {
     res.status(500).json({ error: 'routing_api_error', detail: e.message });
   }

package/src/memory/distiller.js

@@ -0,0 +1,350 @@
+/**
+ * Conversation Distiller — L0-L3 Pipeline (TencentDB-Agent-Memory inspired)
+ *
+ * Long conversations resend every turn on every request. Once a
+ * conversation reaches the turn threshold, this module replaces the older
+ * turns with one compact distilled block and keeps only the most recent
+ * turns verbatim:
+ *
+ *   L0 — raw turns (the messages themselves, dropped after distillation)
+ *   L1 — facts/decisions extracted from the dropped turns (heuristic)
+ *   L2 — scenario summary: what was asked, done, and decided
+ *   L3 — persona: durable user preferences pulled from the memory store
+ *
+ * Large repeated blocks inside the dropped turns are dereferenced through
+ * the wiki registry before summarization. All processing is local and
+ * synchronous — no LLM calls.
+ */
+
+const store = require("./store");
+const extractor = require("./extractor");
+const wiki = require("./wiki");
+const config = require("../config");
+const logger = require("../logger");
+
+const MAX_SCENARIO_POINTS = 12;
+const MAX_PERSONA_ITEMS = 5;
+const MAX_POINT_CHARS = 140;
+const DEFAULT_REFRESH_EVERY_TURNS = 5;
+const MAX_FROZEN_SESSIONS = 500;
+
+function distillConfig() {
+  return config.memory?.distillation ?? {};
+}
+
+// ---------------------------------------------------------------------------
+// Frozen distilled blocks (Phase 5, cache-aware routing).
+//
+// Re-distilling on every request rewrites the front of the conversation each
+// turn, which invalidates the provider's prompt cache wholesale — on exactly
+// the long sessions where caching matters most. Once emitted, a session's
+// distilled block is frozen: the same block bytes and the same split point
+// are served verbatim until K more user turns have accumulated
+// (config.memory.distillation.refreshEveryTurns, default 5). Each refresh is
+// then ONE deliberate, scheduled cache write instead of one per request.
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, {frozenAtTurns:number, splitIdx:number, boundaryFp:string, distilledContent:string, stats:Object}>} */
+const _frozen = new Map();
+
+function _refreshEveryTurns() {
+  const k = distillConfig().refreshEveryTurns;
+  return Number.isFinite(k) && k > 0 ? k : DEFAULT_REFRESH_EVERY_TURNS;
+}
+
+/**
+ * Cheap byte-stability fingerprint for the frozen prefix: split position
+ * plus samples of the first and boundary messages. Detects client-side
+ * history rewrites (compaction, edits) that make the frozen block stale.
+ */
+function _boundaryFingerprint(messages, splitIdx) {
+  const sample = (m) => {
+    if (!m) return "?";
+    const c = typeof m.content === "string" ? m.content : JSON.stringify(m.content ?? "");
+    return `${m.role}:${c.slice(0, 80)}`;
+  };
+  return `${splitIdx}|${sample(messages[0])}|${sample(messages[splitIdx - 1])}`;
+}
+
+function _rememberFrozen(sessionId, entry) {
+  if (!sessionId) return;
+  _frozen.delete(sessionId);
+  _frozen.set(sessionId, entry);
+  if (_frozen.size > MAX_FROZEN_SESSIONS) {
+    const oldest = _frozen.keys().next().value;
+    if (oldest !== undefined) _frozen.delete(oldest);
+  }
+}
+
+/** Test helper — drop all frozen blocks. */
+function _clearFrozen() {
+  _frozen.clear();
+}
+
+/**
+ * A "real" user turn carries user-authored text — tool_result-only
+ * user-role messages are plumbing, not turns.
+ */
+function isRealUserTurn(msg) {
+  if (msg?.role !== "user") return false;
+  if (typeof msg.content === "string") return msg.content.trim().length > 0;
+  if (Array.isArray(msg.content)) {
+    return msg.content.some(b => b?.type === "text" && b.text?.trim());
+  }
+  return false;
+}
+
+function realUserTurnIndices(messages) {
+  const indices = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (isRealUserTurn(messages[i])) indices.push(i);
+  }
+  return indices;
+}
+
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Rough token estimate for the message history (text + tool content).
+ */
+function estimateHistoryTokens(messages) {
+  let chars = 0;
+  for (const msg of messages) {
+    if (typeof msg.content === "string") {
+      chars += msg.content.length;
+    } else if (Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block?.text) chars += block.text.length;
+        else if (typeof block?.content === "string") chars += block.content.length;
+        else if (Array.isArray(block?.content)) {
+          for (const item of block.content) {
+            chars += typeof item === "string" ? item.length : (item?.text?.length ?? 0);
+          }
+        }
+        if (block?.input) chars += JSON.stringify(block.input).length;
+      }
+    }
+  }
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+
+/**
+ * Whether the conversation should be distilled. Two triggers:
+ *  - turn count: conversation reached turnThreshold user turns, OR
+ *  - size rescue: history alone exceeds tokenThreshold estimated tokens
+ *    (protects small-context models that overflow long before the turn
+ *    threshold — observed with 4k-context Ollama models dying at turn 8).
+ * Either way there must be at least one turn older than the keep window,
+ * or there is nothing to distill.
+ */
+function needsDistillation(messages) {
+  const cfg = distillConfig();
+  if (cfg.enabled === false) return false;
+  if (!messages?.length) return false;
+
+  const turns = realUserTurnIndices(messages).length;
+  const keepRecent = cfg.keepRecentTurns ?? 3;
+  if (turns <= keepRecent) return false;
+
+  if (turns >= (cfg.turnThreshold ?? 10)) return true;
+
+  const tokenThreshold = cfg.tokenThreshold ?? 3000;
+  return estimateHistoryTokens(messages) >= tokenThreshold;
+}
+
+function extractText(msg) {
+  if (typeof msg?.content === "string") return msg.content;
+  if (Array.isArray(msg?.content)) {
+    return msg.content
+      .filter(b => b?.type === "text" && b.text)
+      .map(b => b.text)
+      .join(" ");
+  }
+  return "";
+}
+
+function truncate(text, max = MAX_POINT_CHARS) {
+  const clean = text.replace(/\s+/g, " ").trim();
+  return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+}
+
+/**
+ * L2 — scenario summary of the dropped turns: user asks, decisions and
+ * facts surfaced by the assistant, and tool usage counts.
+ */
+function buildScenario(oldMessages) {
+  const asks = [];
+  const toolCounts = new Map();
+  let assistantText = "";
+
+  for (const msg of oldMessages) {
+    if (isRealUserTurn(msg)) {
+      asks.push(truncate(extractText(msg), 100));
+    } else if (msg.role === "assistant") {
+      assistantText += `${extractText(msg)}\n`;
+      if (Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          if (block?.type === "tool_use" && block.name) {
+            toolCounts.set(block.name, (toolCounts.get(block.name) ?? 0) + 1);
+          }
+        }
+      }
+    }
+  }
+
+  // L1 — reuse the extraction patterns on the dropped assistant output
+  const decisions = extractor.extractByType(assistantText, "decision").slice(0, 4);
+  const facts = extractor.extractByType(assistantText, "fact").slice(0, 4);
+
+  const parts = [];
+  if (asks.length) {
+    const shown = asks.slice(-MAX_SCENARIO_POINTS);
+    const omitted = asks.length - shown.length;
+    parts.push(`Requests${omitted > 0 ? ` (${omitted} earlier omitted)` : ""}: ${shown.join(" → ")}`);
+  }
+  if (decisions.length) parts.push(`Decisions: ${decisions.map(d => truncate(d)).join("; ")}`);
+  if (facts.length) parts.push(`Facts: ${facts.map(f => truncate(f)).join("; ")}`);
+  if (toolCounts.size) {
+    const tools = Array.from(toolCounts.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 8)
+      .map(([name, count]) => (count > 1 ? `${name}×${count}` : name))
+      .join(", ");
+    parts.push(`Tools used: ${tools}`);
+  }
+
+  return parts.join("\n");
+}
+
+/**
+ * L3 — persona line from durable preference memories (global + session).
+ */
+function buildPersona(sessionId) {
+  try {
+    const prefs = store
+      .getMemoriesByType("preference", 50)
+      .filter(m => m.sessionId === null || m.sessionId === sessionId)
+      .sort((a, b) => (b.importance ?? 0) - (a.importance ?? 0))
+      .slice(0, MAX_PERSONA_ITEMS);
+
+    if (!prefs.length) return "";
+    return prefs.map(m => truncate(m.content, 80)).join("; ");
+  } catch (err) {
+    logger.warn({ err, sessionId }, "[distiller] Persona build failed");
+    return "";
+  }
+}
+
+/**
+ * Distill a long conversation: dereference repeated large blocks via wiki,
+ * summarize everything before the last keepRecentTurns user turns into one
+ * block, and keep the recent turns verbatim.
+ *
+ * The split lands on a real user turn boundary, so assistant tool_use /
+ * user tool_result pairs are never separated.
+ *
+ * @param {Array} messages - Full conversation
+ * @param {Object} options
+ * @param {string} options.sessionId
+ * @returns {{messages: Array, applied: boolean, stats: Object}}
+ */
+function distillMessages(messages, options = {}) {
+  const { sessionId = null } = options;
+
+  if (!needsDistillation(messages)) {
+    return { messages, applied: false, stats: {} };
+  }
+
+  const keepRecent = distillConfig().keepRecentTurns ?? 3;
+  const turnIndices = realUserTurnIndices(messages);
+
+  // Phase 5 freeze: serve the session's frozen block verbatim while it is
+  // still fresh (fewer than K user turns since it was built) and the
+  // history prefix it covers is byte-stable. The block and split point are
+  // identical across requests, so the provider prompt cache keeps hitting.
+  if (sessionId) {
+    const cached = _frozen.get(sessionId);
+    if (
+      cached
+      && cached.splitIdx < messages.length
+      && turnIndices.length - cached.frozenAtTurns < _refreshEveryTurns()
+      && _boundaryFingerprint(messages, cached.splitIdx) === cached.boundaryFp
+    ) {
+      return {
+        messages: [
+          { role: "user", content: cached.distilledContent },
+          ...messages.slice(cached.splitIdx),
+        ],
+        applied: true,
+        stats: { ...cached.stats, fromFrozenCache: true },
+      };
+    }
+  }
+
+  const splitIdx = turnIndices[Math.max(0, turnIndices.length - keepRecent)];
+
+  if (!splitIdx) {
+    return { messages, applied: false, stats: {} };
+  }
+
+  const oldMessages = messages.slice(0, splitIdx);
+  const recentMessages = messages.slice(splitIdx);
+
+  // Wiki pass over dropped turns: registers large blocks for cross-request
+  // dedup and shrinks repeats before the scenario is built
+  const { messages: dereferenced, stats: wikiStats } = wiki.dereferenceMessages(oldMessages);
+
+  const scenario = buildScenario(dereferenced);
+  const persona = buildPersona(sessionId);
+
+  const sections = [`[Distilled context — earlier ${turnIndices.length - keepRecent} turns compressed]`];
+  if (persona) sections.push(`User profile: ${persona}`);
+  if (scenario) sections.push(scenario);
+
+  const distilledBlock = {
+    role: "user",
+    content: sections.join("\n"),
+  };
+
+  const originalChars = JSON.stringify(oldMessages).length;
+  const distilledChars = distilledBlock.content.length;
+
+  const stats = {
+    droppedMessages: oldMessages.length,
+    keptMessages: recentMessages.length,
+    originalChars,
+    distilledChars,
+    savingsPct: originalChars > 0
+      ? (((originalChars - distilledChars) / originalChars) * 100).toFixed(1)
+      : "0.0",
+    wiki: wikiStats,
+  };
+
+  logger.debug({ sessionId, ...stats }, "[distiller] Conversation distilled");
+
+  // Freeze the block for the next K user turns (Phase 5). Keyed by the
+  // split fingerprint so a client-side history rewrite invalidates it.
+  _rememberFrozen(sessionId, {
+    frozenAtTurns: turnIndices.length,
+    splitIdx,
+    boundaryFp: _boundaryFingerprint(messages, splitIdx),
+    distilledContent: distilledBlock.content,
+    stats,
+  });
+
+  return {
+    messages: [distilledBlock, ...recentMessages],
+    applied: true,
+    stats,
+  };
+}
+
+module.exports = {
+  needsDistillation,
+  distillMessages,
+  buildScenario,
+  buildPersona,
+  isRealUserTurn,
+  estimateHistoryTokens,
+  _clearFrozen,
+};

package/src/memory/extractor.js

@@ -358,19 +358,11 @@ function calculateInitialImportance(type, surpriseScore) {
   return Math.min(1.0, base + (surpriseScore * 0.3));
 }
 
-/**
- * Parse entities from content
- */
-function parseEntities(content) {
-  return extractEntities(content);
-}
-
 module.exports = {
   extractMemories,
   extractContent,
   extractByType,
   extractEntities,
   extractRelationships,
-  parseEntities,
   classifyCategory,
 };