@martian-engineering/lossless-claw 0.6.3 → 0.8.0

package/src/compaction.ts

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
 import type { ConversationStore, CreateMessagePartInput } from "./store/conversation-store.js";
 import type { SummaryStore, SummaryRecord, ContextItemRecord } from "./store/summary-store.js";
+import { estimateTokens, truncateTextToEstimatedTokens } from "./estimate-tokens.js";
 import { extractFileIdsFromContent } from "./large-files.js";
+import { NOOP_LCM_LOGGER, type LcmLogger } from "./lcm-log.js";
 import { LcmProviderAuthError } from "./summarize.js";
 
 // ── Public types ─────────────────────────────────────────────────────────────
@@ -68,7 +70,14 @@ type CompactionSummarizeFn = (
   aggressive?: boolean,
   options?: CompactionSummarizeOptions,
 ) => Promise<string>;
-type PassResult = { summaryId: string; level: CompactionLevel };
+type PassResult = {
+  summaryId: string;
+  level: CompactionLevel;
+  /** Token count of source items removed from context. */
+  removedTokens: number;
+  /** Token count of the newly created summary. */
+  addedTokens: number;
+};
 type LeafChunkSelection = {
   items: ContextItemRecord[];
   rawTokensOutsideTail: number;
@@ -85,10 +94,6 @@ type CondensedPhaseCandidate = {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-/** Estimate token count from character length (~4 chars per token). */
-function estimateTokens(content: string): number {
-  return Math.ceil(content.length / 4);
-}
 
 /** Deterministically cap summary text so the persisted output stays within maxTokens. */
 function capSummaryText(
@@ -104,14 +109,14 @@ function capSummaryText(
   ];
 
   for (const suffix of suffixes) {
-    const maxChars = Math.max(0, maxTokens * 4 - suffix.length);
-    const capped = `${content.slice(0, maxChars)}${suffix}`;
+    const contentBudget = Math.max(0, maxTokens - estimateTokens(suffix));
+    const capped = `${truncateTextToEstimatedTokens(content, contentBudget)}${suffix}`;
     if (estimateTokens(capped) <= maxTokens) {
       return capped;
     }
   }
 
-  return content.slice(0, Math.max(0, maxTokens * 4));
+  return truncateTextToEstimatedTokens(content, maxTokens);
 }
 
 /** Format a timestamp as `YYYY-MM-DD HH:mm TZ` for prompt source text. */
@@ -168,8 +173,8 @@ function generateSummaryId(content: string): string {
   );
 }
 
-/** Maximum characters for the deterministic fallback truncation (512 tokens * 4 chars). */
-const FALLBACK_MAX_CHARS = 512 * 4;
+/** Maximum estimated tokens for the deterministic fallback truncation. */
+const FALLBACK_MAX_TOKENS = 512;
 const DEFAULT_LEAF_CHUNK_TOKENS = 20_000;
 
 /**
@@ -335,12 +340,59 @@ function isMediaAttachmentPart(part: CreateMessagePartInput | { partType: string
 // ── CompactionEngine ─────────────────────────────────────────────────────────
 
 export class CompactionEngine {
+  /**
+   * Per-conversation context items cache, active only during compaction
+   * entry points. null when inactive — external callers (e.g., engine.ts
+   * evaluateLeafTrigger) get uncached reads.
+   *
+   * Uses a reference count so concurrent compactions on different
+   * conversations don't interfere: each withContextCache increments
+   * on entry and decrements on exit; the cache is only destroyed
+   * when all users have exited.
+   */
+  private _contextItemsCache: Map<number, ContextItemRecord[]> | null = null;
+  private _contextItemsCacheRefCount = 0;
+
   constructor(
     private conversationStore: ConversationStore,
     private summaryStore: SummaryStore,
     private config: CompactionConfig,
+    private log: LcmLogger = NOOP_LCM_LOGGER,
   ) {}
 
+  /** Read context items, using per-phase cache when active. */
+  private async getContextItemsCached(conversationId: number): Promise<ContextItemRecord[]> {
+    if (this._contextItemsCache) {
+      if (this._contextItemsCache.has(conversationId)) {
+        return this._contextItemsCache.get(conversationId)!;
+      }
+      const items = await this.summaryStore.getContextItems(conversationId);
+      this._contextItemsCache.set(conversationId, items);
+      return items;
+    }
+    return this.summaryStore.getContextItems(conversationId);
+  }
+
+  /** Invalidate cache for a conversation after context mutation. */
+  private invalidateContextCache(conversationId: number): void {
+    this._contextItemsCache?.delete(conversationId);
+  }
+
+  /** Execute with context cache active. Reference-counted for concurrent use. */
+  private async withContextCache<T>(fn: () => Promise<T>): Promise<T> {
+    if (!this._contextItemsCache) this._contextItemsCache = new Map();
+    this._contextItemsCacheRefCount++;
+    try {
+      return await fn();
+    } finally {
+      this._contextItemsCacheRefCount--;
+      if (this._contextItemsCacheRefCount <= 0) {
+        this._contextItemsCache = null;
+        this._contextItemsCacheRefCount = 0;
+      }
+    }
+  }
+
   // ── evaluate ─────────────────────────────────────────────────────────────
 
   /** Evaluate whether compaction is needed. */
@@ -383,13 +435,13 @@ export class CompactionEngine {
    * `leafChunkTokens`. This lets callers trigger a soft incremental leaf pass
    * before the full context threshold is breached.
    */
-  async evaluateLeafTrigger(conversationId: number): Promise<{
+  async evaluateLeafTrigger(conversationId: number, leafChunkTokensOverride?: number): Promise<{
     shouldCompact: boolean;
     rawTokensOutsideTail: number;
     threshold: number;
   }> {
     const rawTokensOutsideTail = await this.countRawTokensOutsideFreshTail(conversationId);
-    const threshold = this.resolveLeafChunkTokens();
+    const threshold = this.resolveLeafChunkTokens(leafChunkTokensOverride);
     return {
       shouldCompact: rawTokensOutsideTail >= threshold,
       rawTokensOutsideTail,
@@ -409,7 +461,7 @@ export class CompactionEngine {
     hardTrigger?: boolean;
     summaryModel?: string;
   }): Promise<CompactionResult> {
-    return this.compactFullSweep(input);
+    return this.withContextCache(() => this.compactFullSweep(input));
   }
 
   /**
@@ -421,6 +473,20 @@ export class CompactionEngine {
     conversationId: number;
     tokenBudget: number;
     summarize: CompactionSummarizeFn;
+    leafChunkTokens?: number;
+    force?: boolean;
+    previousSummaryContent?: string;
+    summaryModel?: string;
+    allowCondensedPasses?: boolean;
+  }): Promise<CompactionResult> {
+    return this.withContextCache(() => this._compactLeafImpl(input));
+  }
+
+  private async _compactLeafImpl(input: {
+    conversationId: number;
+    tokenBudget: number;
+    summarize: CompactionSummarizeFn;
+    leafChunkTokens?: number;
     force?: boolean;
     previousSummaryContent?: string;
     summaryModel?: string;
@@ -429,7 +495,7 @@ export class CompactionEngine {
 
     const tokensBefore = await this.summaryStore.getContextTokenCount(conversationId);
     const threshold = Math.floor(this.config.contextThreshold * tokenBudget);
-    const leafTrigger = await this.evaluateLeafTrigger(conversationId);
+    const leafTrigger = await this.evaluateLeafTrigger(conversationId, input.leafChunkTokens);
 
     if (!force && tokensBefore <= threshold && !leafTrigger.shouldCompact) {
       return {
@@ -440,7 +506,7 @@ export class CompactionEngine {
       };
     }
 
-    const leafChunk = await this.selectOldestLeafChunk(conversationId);
+    const leafChunk = await this.selectOldestLeafChunk(conversationId, input.leafChunkTokens);
     if (leafChunk.items.length === 0) {
       return {
         actionTaken: false,
@@ -470,7 +536,8 @@ export class CompactionEngine {
         authFailure: true,
       };
     }
-    const tokensAfterLeaf = await this.summaryStore.getContextTokenCount(conversationId);
+    // Delta tracking: compute token change from pass results instead of re-querying DB
+    const tokensAfterLeaf = tokensBefore - leafResult.removedTokens + leafResult.addedTokens;
 
     await this.persistCompactionEvents({
       conversationId,
@@ -488,7 +555,8 @@ export class CompactionEngine {
 
     const incrementalMaxDepth = this.resolveIncrementalMaxDepth();
     const condensedMinChunkTokens = this.resolveCondensedMinChunkTokens();
-    if (incrementalMaxDepth > 0) {
+    let runningTokens = tokensAfterLeaf;
+    if (incrementalMaxDepth > 0 && input.allowCondensedPasses !== false) {
       for (let targetDepth = 0; targetDepth < incrementalMaxDepth; targetDepth++) {
         const fanout = this.resolveFanoutForDepth(targetDepth, false);
         const chunk = await this.selectOldestChunkAtDepth(conversationId, targetDepth);
@@ -496,7 +564,7 @@ export class CompactionEngine {
           break;
         }
 
-        const passTokensBefore = await this.summaryStore.getContextTokenCount(conversationId);
+        const passTokensBefore = runningTokens;
         const condenseResult = await this.condensedPass(
           conversationId,
           chunk.items,
@@ -507,7 +575,7 @@ export class CompactionEngine {
         if (!condenseResult) {
           break;
         }
-        const passTokensAfter = await this.summaryStore.getContextTokenCount(conversationId);
+        const passTokensAfter = passTokensBefore - condenseResult.removedTokens + condenseResult.addedTokens;
         await this.persistCompactionEvents({
           conversationId,
           tokensBefore: passTokensBefore,
@@ -518,6 +586,7 @@ export class CompactionEngine {
         });
 
         tokensAfter = passTokensAfter;
+        runningTokens = passTokensAfter;
         condensed = true;
         createdSummaryId = condenseResult.summaryId;
         level = condenseResult.level;
@@ -568,7 +637,7 @@ export class CompactionEngine {
       };
     }
 
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+    const contextItems = await this.getContextItemsCached(conversationId);
     if (contextItems.length === 0) {
       return {
         actionTaken: false,
@@ -587,13 +656,16 @@ export class CompactionEngine {
     let hadAuthFailure = false;
 
     // Phase 1: leaf passes over oldest raw chunks outside the protected tail.
+    // Delta tracking: maintain a running token count instead of re-querying DB
+    // after each pass. The arithmetic is exact: tokensAfter = tokensBefore - removed + added.
+    let runningTokens = tokensBefore;
     while (true) {
       const leafChunk = await this.selectOldestLeafChunk(conversationId);
       if (leafChunk.items.length === 0) {
         break;
       }
 
-      const passTokensBefore = await this.summaryStore.getContextTokenCount(conversationId);
+      const passTokensBefore = runningTokens;
       const leafResult = await this.leafPass(
         conversationId,
         leafChunk.items,
@@ -605,7 +677,7 @@ export class CompactionEngine {
         hadAuthFailure = true;
         break;
       }
-      const passTokensAfter = await this.summaryStore.getContextTokenCount(conversationId);
+      const passTokensAfter = passTokensBefore - leafResult.removedTokens + leafResult.addedTokens;
       await this.persistCompactionEvents({
         conversationId,
         tokensBefore: passTokensBefore,
@@ -619,6 +691,7 @@ export class CompactionEngine {
       createdSummaryId = leafResult.summaryId;
       level = leafResult.level;
       previousSummaryContent = leafResult.content;
+      runningTokens = passTokensAfter;
 
       if (!force && passTokensAfter <= threshold) {
         previousTokens = passTokensAfter;
@@ -640,7 +713,7 @@ export class CompactionEngine {
         break;
       }
 
-      const passTokensBefore = await this.summaryStore.getContextTokenCount(conversationId);
+      const passTokensBefore = runningTokens;
       const condenseResult = await this.condensedPass(
         conversationId,
         candidate.chunk.items,
@@ -652,7 +725,7 @@ export class CompactionEngine {
         hadAuthFailure = true;
         break;
       }
-      const passTokensAfter = await this.summaryStore.getContextTokenCount(conversationId);
+      const passTokensAfter = passTokensBefore - condenseResult.removedTokens + condenseResult.addedTokens;
       await this.persistCompactionEvents({
         conversationId,
         tokensBefore: passTokensBefore,
@@ -666,6 +739,7 @@ export class CompactionEngine {
       condensed = true;
       createdSummaryId = condenseResult.summaryId;
       level = condenseResult.level;
+      runningTokens = passTokensAfter;
 
       if (!force && passTokensAfter <= threshold) {
         previousTokens = passTokensAfter;
@@ -677,7 +751,7 @@ export class CompactionEngine {
       previousTokens = passTokensAfter;
     }
 
-    const tokensAfter = await this.summaryStore.getContextTokenCount(conversationId);
+    const tokensAfter = runningTokens;
 
     return {
       actionTaken,
@@ -700,6 +774,17 @@ export class CompactionEngine {
     currentTokens?: number;
     summarize: CompactionSummarizeFn;
     summaryModel?: string;
+  }): Promise<{ success: boolean; rounds: number; finalTokens: number; authFailure?: boolean }> {
+    return this.withContextCache(() => this._compactUntilUnderImpl(input));
+  }
+
+  private async _compactUntilUnderImpl(input: {
+    conversationId: number;
+    tokenBudget: number;
+    targetTokens?: number;
+    currentTokens?: number;
+    summarize: CompactionSummarizeFn;
+    summaryModel?: string;
   }): Promise<{ success: boolean; rounds: number; finalTokens: number; authFailure?: boolean }> {
     const { conversationId, tokenBudget, summarize } = input;
     const targetTokens =
@@ -763,8 +848,8 @@ export class CompactionEngine {
       lastTokens = result.tokensAfter;
     }
 
-    // Exhausted all rounds
-    const finalTokens = await this.summaryStore.getContextTokenCount(conversationId);
+    // Exhausted all rounds — use the last known token count from compact() result
+    const finalTokens = lastTokens;
     return {
       success: finalTokens <= targetTokens,
       rounds: this.config.maxRounds,
@@ -775,7 +860,14 @@ export class CompactionEngine {
   // ── Private helpers ──────────────────────────────────────────────────────
 
   /** Normalize configured leaf chunk size to a safe positive integer. */
-  private resolveLeafChunkTokens(): number {
+  private resolveLeafChunkTokens(leafChunkTokensOverride?: number): number {
+    if (
+      typeof leafChunkTokensOverride === "number" &&
+      Number.isFinite(leafChunkTokensOverride) &&
+      leafChunkTokensOverride > 0
+    ) {
+      return Math.floor(leafChunkTokensOverride);
+    }
     if (
       typeof this.config.leafChunkTokens === "number" &&
       Number.isFinite(this.config.leafChunkTokens) &&
@@ -838,7 +930,7 @@ export class CompactionEngine {
 
   /** Sum raw message tokens outside the protected fresh tail. */
   private async countRawTokensOutsideFreshTail(conversationId: number): Promise<number> {
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+    const contextItems = await this.getContextItemsCached(conversationId);
     const freshTailOrdinal = this.resolveFreshTailOrdinal(contextItems);
     let rawTokens = 0;
 
@@ -861,10 +953,13 @@ export class CompactionEngine {
    * The selected chunk size is capped by `leafChunkTokens`, but we always pick
    * at least one message when any compactable message exists.
    */
-  private async selectOldestLeafChunk(conversationId: number): Promise<LeafChunkSelection> {
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+  private async selectOldestLeafChunk(
+    conversationId: number,
+    leafChunkTokensOverride?: number,
+  ): Promise<LeafChunkSelection> {
+    const contextItems = await this.getContextItemsCached(conversationId);
     const freshTailOrdinal = this.resolveFreshTailOrdinal(contextItems);
-    const threshold = this.resolveLeafChunkTokens();
+    const threshold = this.resolveLeafChunkTokens(leafChunkTokensOverride);
 
     let rawTokensOutsideTail = 0;
     for (const item of contextItems) {
@@ -927,7 +1022,7 @@ export class CompactionEngine {
     }
 
     const startOrdinal = Math.min(...messageItems.map((item) => item.ordinal));
-    const priorSummaryItems = (await this.summaryStore.getContextItems(conversationId))
+    const priorSummaryItems = (await this.getContextItemsCached(conversationId))
       .filter(
         (item) =>
           item.ordinal < startOrdinal &&
@@ -1051,7 +1146,7 @@ export class CompactionEngine {
     hardTrigger: boolean;
   }): Promise<CondensedPhaseCandidate | null> {
     const { conversationId, hardTrigger } = params;
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+    const contextItems = await this.getContextItemsCached(conversationId);
     const freshTailOrdinal = this.resolveFreshTailOrdinal(contextItems);
     const minChunkTokens = this.resolveCondensedMinChunkTokens();
     const depthLevels = await this.summaryStore.getDistinctDepthsInContext(conversationId, {
@@ -1088,7 +1183,7 @@ export class CompactionEngine {
     targetDepth: number,
     freshTailOrdinalOverride?: number,
   ): Promise<CondensedChunkSelection> {
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+    const contextItems = await this.getContextItemsCached(conversationId);
     const freshTailOrdinal =
       typeof freshTailOrdinalOverride === "number"
         ? freshTailOrdinalOverride
@@ -1147,7 +1242,7 @@ export class CompactionEngine {
     }
 
     const startOrdinal = Math.min(...summaryItems.map((item) => item.ordinal));
-    const priorSummaryItems = (await this.summaryStore.getContextItems(conversationId))
+    const priorSummaryItems = (await this.getContextItemsCached(conversationId))
       .filter(
         (item) =>
           item.ordinal < startOrdinal &&
@@ -1203,13 +1298,13 @@ export class CompactionEngine {
     }
     const inputTokens = Math.max(1, estimateTokens(sourceText));
     const buildDeterministicFallback = (): { content: string; level: CompactionLevel } => {
-      const truncated =
-        sourceText.length > FALLBACK_MAX_CHARS
-          ? sourceText.slice(0, FALLBACK_MAX_CHARS)
-          : sourceText;
+      const suffix = `\n[Truncated from ${inputTokens} tokens]`;
+      const truncated = truncateTextToEstimatedTokens(
+        sourceText,
+        Math.max(0, FALLBACK_MAX_TOKENS - estimateTokens(suffix)),
+      );
       return {
-        content: `${truncated}
-[Truncated from ${inputTokens} tokens]`,
+        content: `${truncated}${suffix}`,
         level: "fallback",
       };
     };
@@ -1264,7 +1359,7 @@ export class CompactionEngine {
     const maxTokens = Math.ceil(params.targetTokens * this.config.summaryMaxOverageFactor);
 
     if (summaryTokens > Math.ceil(params.targetTokens * 1.5)) {
-      console.warn(
+      this.log.warn(
         `[lcm] summary exceeds target by ${Math.round((summaryTokens / params.targetTokens - 1) * 100)}%: ${summaryTokens} tokens vs target ${params.targetTokens}`,
       );
     }
@@ -1330,7 +1425,7 @@ export class CompactionEngine {
     summarize: CompactionSummarizeFn,
     previousSummaryContent?: string,
     summaryModel?: string,
-  ): Promise<{ summaryId: string; level: CompactionLevel; content: string } | null> {
+  ): Promise<{ summaryId: string; level: CompactionLevel; content: string; removedTokens: number; addedTokens: number } | null> {
     // Fetch full message content for each context item
     const messageContents: { messageId: number; content: string; createdAt: Date; tokenCount: number }[] =
       [];
@@ -1369,7 +1464,7 @@ export class CompactionEngine {
       targetTokens: this.config.leafTargetTokens,
     });
     if (!summary) {
-      console.warn(
+      this.log.warn(
         `[lcm] leaf compaction skipped summary write; conversationId=${conversationId}; chunkMessages=${messageContents.length}`,
       );
       return null;
@@ -1378,6 +1473,16 @@ export class CompactionEngine {
     // Persist the leaf summary
     const summaryId = generateSummaryId(summary.content);
     const tokenCount = estimateTokens(summary.content);
+    // Note: removedTokens uses resolveMessageTokenCount values (which fall back to
+    // estimateTokens for messages with token_count <= 0). This can diverge from
+    // getContextTokenCount() which would sum the stored 0. The delta feeds into
+    // stopping decisions (threshold checks, progress guards), but the divergence
+    // is bounded to empty/corrupt messages (token_count=0) which are rare.
+    // For summaries, removedTokens matches the DB exactly (same tokenCount column).
+    const removedTokens = messageContents.reduce(
+      (sum, message) => sum + Math.max(0, Math.floor(message.tokenCount)),
+      0,
+    );
 
     await this.summaryStore.withTransaction(async () => {
       await this.summaryStore.insertSummary({
@@ -1398,10 +1503,7 @@ export class CompactionEngine {
             : undefined,
         descendantCount: 0,
         descendantTokenCount: 0,
-        sourceMessageTokenCount: messageContents.reduce(
-          (sum, message) => sum + Math.max(0, Math.floor(message.tokenCount)),
-          0,
-        ),
+        sourceMessageTokenCount: removedTokens,
         model: summaryModel,
       });
 
@@ -1421,8 +1523,9 @@ export class CompactionEngine {
         summaryId,
       });
     });
+    this.invalidateContextCache(conversationId);
 
-    return { summaryId, level: summary.level, content: summary.content };
+    return { summaryId, level: summary.level, content: summary.content, removedTokens, addedTokens: tokenCount };
   }
 
   // ── Private: Condensed Pass ──────────────────────────────────────────────
@@ -1479,7 +1582,7 @@ export class CompactionEngine {
       targetTokens: this.config.condensedTargetTokens,
     });
     if (!condensed) {
-      console.warn(
+      this.log.warn(
         `[lcm] condensed compaction skipped summary write; conversationId=${conversationId}; depth=${targetDepth}; chunkSummaries=${summaryRecords.length}`,
       );
       return null;
@@ -1560,8 +1663,13 @@ export class CompactionEngine {
         summaryId,
       });
     });
+    this.invalidateContextCache(conversationId);
 
-    return { summaryId, level: condensed.level };
+    const removedTokens = summaryRecords.reduce(
+      (sum, s) => sum + Math.max(0, Math.floor(s.tokenCount)),
+      0,
+    );
+    return { summaryId, level: condensed.level, removedTokens, addedTokens: tokenCount };
   }
 
   /** Emit compaction telemetry without mutating canonical conversation history. */
@@ -1638,7 +1746,7 @@ export class CompactionEngine {
     condensedPassOccurred: boolean;
   }): Promise<void> {
     const content = `LCM compaction ${input.pass} pass (${input.level}): ${input.tokensBefore} -> ${input.tokensAfter}`;
-    console.info(
+    this.log.info(
       `[lcm] ${content} conversation=${input.conversationId} summary=${input.createdSummaryId}`,
     );
   }

package/src/db/config.ts

@@ -1,6 +1,18 @@
 import { homedir } from "os";
 import { join } from "path";
 
+export type CacheAwareCompactionConfig = {
+  enabled: boolean;
+  maxColdCacheCatchupPasses: number;
+  hotCachePressureFactor: number;
+  hotCacheBudgetHeadroomRatio: number;
+};
+
+export type DynamicLeafChunkTokensConfig = {
+  enabled: boolean;
+  max: number;
+};
+
 export type LcmConfig = {
   enabled: boolean;
   databasePath: string;
@@ -32,10 +44,6 @@ export type LcmConfig = {
   largeFileSummaryProvider: string;
   /** Model override for large-file text summarization. */
   largeFileSummaryModel: string;
-  /** Model override for conversation summarization. */
-  summaryModel: string;
-  /** Provider override for conversation summarization. */
-  summaryProvider: string;
   /** Provider override for lcm_expand_query sub-agent. */
   expansionProvider: string;
   /** Model override for lcm_expand_query sub-agent. */
@@ -58,6 +66,12 @@ export type LcmConfig = {
   circuitBreakerThreshold: number;
   /** Cooldown in milliseconds before the circuit breaker auto-resets (default 30 min). */
   circuitBreakerCooldownMs: number;
+  /** Explicit fallback provider/model pairs for compaction summarization. */
+  fallbackProviders: Array<{ provider: string; model: string }>;
+  /** Cache-sensitive policy for incremental leaf compaction. */
+  cacheAwareCompaction: CacheAwareCompactionConfig;
+  /** Dynamic step-band policy for incremental leaf chunk sizing. */
+  dynamicLeafChunkTokens: DynamicLeafChunkTokensConfig;
 };
 
 /** Safely coerce an unknown value to a finite number, or return undefined. */
@@ -85,6 +99,39 @@ function parseFiniteNumber(value: string | undefined): number | undefined {
   return Number.isFinite(parsed) ? parsed : undefined;
 }
 
+/** Parse fallback providers from env string (format: "provider/model,provider/model"). */
+function parseFallbackProviders(value: string | undefined): Array<{ provider: string; model: string }> | undefined {
+  if (!value?.trim()) return undefined;
+  const entries: Array<{ provider: string; model: string }> = [];
+  for (const part of value.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const slashIdx = trimmed.indexOf("/");
+    if (slashIdx > 0 && slashIdx < trimmed.length - 1) {
+      const provider = trimmed.slice(0, slashIdx).trim();
+      const model = trimmed.slice(slashIdx + 1).trim();
+      if (provider && model) {
+        entries.push({ provider, model });
+      }
+    }
+  }
+  return entries.length > 0 ? entries : undefined;
+}
+
+/** Parse fallback providers from plugin config array (object items only). */
+function toFallbackProviderArray(value: unknown): Array<{ provider: string; model: string }> | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const entries: Array<{ provider: string; model: string }> = [];
+  for (const item of value) {
+    if (item && typeof item === "object" && !Array.isArray(item)) {
+      const p = toStr((item as Record<string, unknown>).provider);
+      const m = toStr((item as Record<string, unknown>).model);
+      if (p && m) entries.push({ provider: p, model: m });
+    }
+  }
+  return entries.length > 0 ? entries : undefined;
+}
+
 /** Safely coerce an unknown value to a boolean, or return undefined. */
 function toBool(value: unknown): boolean | undefined {
   if (typeof value === "boolean") return value;
@@ -120,6 +167,12 @@ function toStrArray(value: unknown): string[] | undefined {
     .filter(Boolean);
 }
 
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
 /**
  * Resolve LCM configuration with three-tier precedence:
  *   1. Environment variables (highest — backward compat)
@@ -131,6 +184,8 @@ export function resolveLcmConfig(
   pluginConfig?: Record<string, unknown>,
 ): LcmConfig {
   const pc = pluginConfig ?? {};
+  const cacheAwareCompaction = toRecord(pc.cacheAwareCompaction);
+  const dynamicLeafChunkTokens = toRecord(pc.dynamicLeafChunkTokens);
   const resolvedLeafChunkTokens =
     parseFiniteInt(env.LCM_LEAF_CHUNK_TOKENS)
       ?? toNumber(pc.leafChunkTokens) ?? 20000;
@@ -142,6 +197,27 @@ export function resolveLcmConfig(
     env.LCM_DELEGATION_TIMEOUT_MS !== undefined
       ? toNumber(env.LCM_DELEGATION_TIMEOUT_MS)
       : undefined;
+  const resolvedDynamicLeafChunkMax = Math.max(
+    resolvedLeafChunkTokens,
+    parseFiniteInt(env.LCM_DYNAMIC_LEAF_CHUNK_TOKENS_MAX)
+      ?? toNumber(dynamicLeafChunkTokens?.max)
+      ?? Math.floor(resolvedLeafChunkTokens * 2),
+  );
+  const resolvedHotCachePressureFactor = Math.max(
+    1,
+    parseFiniteNumber(env.LCM_HOT_CACHE_PRESSURE_FACTOR)
+      ?? toNumber(cacheAwareCompaction?.hotCachePressureFactor)
+      ?? 4,
+  );
+  const resolvedHotCacheBudgetHeadroomRatio = Math.min(
+    0.95,
+    Math.max(
+      0,
+      parseFiniteNumber(env.LCM_HOT_CACHE_BUDGET_HEADROOM_RATIO)
+        ?? toNumber(cacheAwareCompaction?.hotCacheBudgetHeadroomRatio)
+        ?? 0.2,
+    ),
+  );
 
   return {
     enabled:
@@ -243,5 +319,27 @@ export function resolveLcmConfig(
     circuitBreakerCooldownMs:
       parseFiniteInt(env.LCM_CIRCUIT_BREAKER_COOLDOWN_MS)
         ?? toNumber(pc.circuitBreakerCooldownMs) ?? 1_800_000,
+    fallbackProviders:
+      parseFallbackProviders(env.LCM_FALLBACK_PROVIDERS)
+        ?? toFallbackProviderArray(pc.fallbackProviders) ?? [],
+    cacheAwareCompaction: {
+      enabled:
+        env.LCM_CACHE_AWARE_COMPACTION_ENABLED !== undefined
+          ? env.LCM_CACHE_AWARE_COMPACTION_ENABLED !== "false"
+          : toBool(cacheAwareCompaction?.enabled) ?? true,
+      maxColdCacheCatchupPasses:
+        parseFiniteInt(env.LCM_MAX_COLD_CACHE_CATCHUP_PASSES)
+          ?? toNumber(cacheAwareCompaction?.maxColdCacheCatchupPasses)
+          ?? 2,
+      hotCachePressureFactor: resolvedHotCachePressureFactor,
+      hotCacheBudgetHeadroomRatio: resolvedHotCacheBudgetHeadroomRatio,
+    },
+    dynamicLeafChunkTokens: {
+      enabled:
+        env.LCM_DYNAMIC_LEAF_CHUNK_TOKENS_ENABLED !== undefined
+          ? env.LCM_DYNAMIC_LEAF_CHUNK_TOKENS_ENABLED === "true"
+          : toBool(dynamicLeafChunkTokens?.enabled) ?? true,
+      max: resolvedDynamicLeafChunkMax,
+    },
   };
 }