@martian-engineering/lossless-claw 0.5.2 → 0.6.0

package/src/engine.ts

@@ -5,6 +5,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import type { DatabaseSync } from "node:sqlite";
 import { createInterface } from "node:readline";
+import { SessionManager } from "@mariozechner/pi-coding-agent";
 import type {
   ContextEngine,
   ContextEngineInfo,
@@ -16,7 +17,14 @@ import type {
   SubagentEndReason,
   SubagentSpawnPreparation,
 } from "openclaw/plugin-sdk";
-import { blockFromPart, ContextAssembler } from "./assembler.js";
+import {
+  blockFromPart,
+  contentFromParts,
+  ContextAssembler,
+  pickToolCallId,
+  pickToolIsError,
+  pickToolName,
+} from "./assembler.js";
 import { CompactionEngine, type CompactionConfig } from "./compaction.js";
 import type { LcmConfig } from "./db/config.js";
 import { getLcmDbFeatures } from "./db/features.js";
@@ -50,6 +58,30 @@ import type { LcmDependencies } from "./types.js";
 
 type AgentMessage = Parameters<ContextEngine["ingest"]>[0]["message"];
 type AssembleResultWithSystemPrompt = AssembleResult & { systemPromptAddition?: string };
+type CircuitBreakerState = {
+  failures: number;
+  openSince: number | null;
+};
+type TranscriptRewriteReplacement = {
+  entryId: string;
+  message: AgentMessage;
+};
+type TranscriptRewriteRequest = {
+  replacements: TranscriptRewriteReplacement[];
+};
+type ContextEngineMaintenanceResult = {
+  changed: boolean;
+  bytesFreed: number;
+  rewrittenEntries: number;
+  reason?: string;
+};
+type ContextEngineMaintenanceRuntimeContext = Record<string, unknown> & {
+  rewriteTranscriptEntries?: (
+    request: TranscriptRewriteRequest,
+  ) => Promise<ContextEngineMaintenanceResult>;
+};
+
+const TRANSCRIPT_GC_BATCH_SIZE = 12;
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -77,6 +109,71 @@ function safeBoolean(value: unknown): boolean | undefined {
   return typeof value === "boolean" ? value : undefined;
 }
 
+function extractTranscriptToolCallId(message: AgentMessage): string | undefined {
+  const topLevel = message as Record<string, unknown>;
+  const direct =
+    safeString(topLevel.toolCallId) ??
+    safeString(topLevel.tool_call_id) ??
+    safeString(topLevel.toolUseId) ??
+    safeString(topLevel.tool_use_id) ??
+    safeString(topLevel.call_id) ??
+    safeString(topLevel.id);
+  if (direct) {
+    return direct;
+  }
+
+  if (!Array.isArray(topLevel.content)) {
+    return undefined;
+  }
+
+  for (const item of topLevel.content) {
+    const record = asRecord(item);
+    if (!record) {
+      continue;
+    }
+    const nested =
+      safeString(record.toolCallId) ??
+      safeString(record.tool_call_id) ??
+      safeString(record.toolUseId) ??
+      safeString(record.tool_use_id) ??
+      safeString(record.call_id) ??
+      safeString(record.id);
+    if (nested) {
+      return nested;
+    }
+  }
+
+  return undefined;
+}
+
+function listTranscriptToolResultEntryIdsByCallId(sessionFile: string): Map<string, string> {
+  const sessionManager = SessionManager.open(sessionFile);
+  const branch = sessionManager.getBranch();
+  const entryIdsByCallId = new Map<string, string>();
+  const duplicateCallIds = new Set<string>();
+
+  for (const entry of branch) {
+    if (entry.type !== "message" || entry.message.role !== "toolResult") {
+      continue;
+    }
+    const toolCallId = extractTranscriptToolCallId(entry.message as AgentMessage);
+    if (!toolCallId) {
+      continue;
+    }
+    if (entryIdsByCallId.has(toolCallId)) {
+      duplicateCallIds.add(toolCallId);
+      continue;
+    }
+    entryIdsByCallId.set(toolCallId, entry.id);
+  }
+
+  for (const duplicateCallId of duplicateCallIds) {
+    entryIdsByCallId.delete(duplicateCallId);
+  }
+
+  return entryIdsByCallId;
+}
+
 function appendTextValue(value: unknown, out: string[]): void {
   if (typeof value === "string") {
     out.push(value);
@@ -535,7 +632,15 @@ function buildMessageParts(params: {
   for (let ordinal = 0; ordinal < message.content.length; ordinal++) {
     const block = normalizeUnknownBlock(message.content[ordinal]);
     const metadataRecord = block.metadata.raw as Record<string, unknown> | undefined;
-    const partType = toPartType(block.type);
+    const rawBlockType = safeString(metadataRecord?.rawType) ?? block.type;
+    const partType = toPartType(rawBlockType);
+    const rawBlock =
+      metadataRecord && rawBlockType !== block.type
+        ? {
+            ...metadataRecord,
+            type: rawBlockType,
+          }
+        : (metadataRecord ?? message.content[ordinal]);
     const toolCallId =
       safeString(metadataRecord?.toolCallId) ??
       safeString(metadataRecord?.tool_call_id) ??
@@ -582,8 +687,8 @@ function buildMessageParts(params: {
             : undefined,
         toolOutputExternalized: safeBoolean(metadataRecord?.toolOutputExternalized),
         externalizationReason: safeString(metadataRecord?.externalizationReason),
-        rawType: block.type,
-        raw: metadataRecord ?? message.content[ordinal],
+        rawType: rawBlockType,
+        raw: rawBlock,
       }),
     });
   }
@@ -826,6 +931,70 @@ async function readLeafPathMessages(sessionFile: string): Promise<AgentMessage[]
   }
 }
 
+/**
+ * Resolve the first-time bootstrap token budget.
+ *
+ * When unset, bootstrap keeps a modest suffix of the parent session rather than
+ * inheriting the full raw history into a brand-new conversation.
+ */
+function resolveBootstrapMaxTokens(config: Pick<LcmConfig, "bootstrapMaxTokens" | "leafChunkTokens">): number {
+  if (
+    typeof config.bootstrapMaxTokens === "number" &&
+    Number.isFinite(config.bootstrapMaxTokens) &&
+    config.bootstrapMaxTokens > 0
+  ) {
+    return Math.floor(config.bootstrapMaxTokens);
+  }
+
+  const leafChunkTokens =
+    typeof config.leafChunkTokens === "number" &&
+    Number.isFinite(config.leafChunkTokens) &&
+    config.leafChunkTokens > 0
+      ? Math.floor(config.leafChunkTokens)
+      : 20_000;
+  return Math.max(6000, Math.floor(leafChunkTokens * 0.3));
+}
+
+/**
+ * Keep only the newest bootstrap messages that fit within the token budget.
+ *
+ * The newest message is always preserved so a fork never starts empty when the
+ * parent transcript has any recoverable content at all.
+ */
+function trimBootstrapMessagesToBudget(messages: AgentMessage[], maxTokens: number): AgentMessage[] {
+  if (messages.length === 0) {
+    return [];
+  }
+
+  const safeMaxTokens = Number.isFinite(maxTokens) ? Math.floor(maxTokens) : 0;
+  if (safeMaxTokens <= 0) {
+    return [messages[messages.length - 1]!];
+  }
+
+  const kept: AgentMessage[] = [];
+  let totalTokens = 0;
+
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index]!;
+    const tokenCount = toStoredMessage(message).tokenCount;
+    if (kept.length > 0 && totalTokens + tokenCount > safeMaxTokens) {
+      break;
+    }
+    kept.push(message);
+    totalTokens += tokenCount;
+  }
+
+  // If a single oversized tail message exceeds the budget, return empty
+  // rather than silently bypassing the budget cap. An empty bootstrap is
+  // safer than an exploding one.
+  if (kept.length === 1 && totalTokens > safeMaxTokens) {
+    return [];
+  }
+
+  kept.reverse();
+  return kept;
+}
+
 function readFileSegment(sessionFile: string, offset: number): string | null {
   let fd: number | null = null;
   try {
@@ -975,6 +1144,9 @@ export class LcmContextEngine implements ContextEngine {
   private largeFileTextSummarizer?: (prompt: string) => Promise<string | null>;
   private deps: LcmDependencies;
 
+  // ── Circuit breaker for compaction auth failures ──
+  private circuitBreakerStates = new Map<string, CircuitBreakerState>();
+
   constructor(deps: LcmDependencies, database: DatabaseSync) {
     this.deps = deps;
     this.config = deps.config;
@@ -1064,6 +1236,7 @@ export class LcmContextEngine implements ContextEngine {
       condensedTargetTokens: this.config.condensedTargetTokens,
       maxRounds: 10,
       timezone: this.config.timezone,
+      summaryMaxOverageFactor: this.config.summaryMaxOverageFactor,
     };
     this.compaction = new CompactionEngine(
       this.conversationStore,
@@ -1110,6 +1283,56 @@ export class LcmContextEngine implements ContextEngine {
     return matchesSessionPattern(trimmedKey, this.statelessSessionPatterns);
   }
 
+  // ── Circuit breaker helpers ──────────────────────────────────────────────
+
+  private getCircuitBreakerState(key: string): CircuitBreakerState {
+    let state = this.circuitBreakerStates.get(key);
+    if (!state) {
+      state = { failures: 0, openSince: null };
+      this.circuitBreakerStates.set(key, state);
+    }
+    return state;
+  }
+
+  private isCircuitBreakerOpen(key: string): boolean {
+    const state = this.circuitBreakerStates.get(key);
+    if (!state || state.openSince === null) return false;
+    const elapsed = Date.now() - state.openSince;
+    if (elapsed >= this.config.circuitBreakerCooldownMs) {
+      this.resetCircuitBreaker(key);
+      return false;
+    }
+    return true;
+  }
+
+  private recordCompactionAuthFailure(key: string): void {
+    const state = this.getCircuitBreakerState(key);
+    state.failures++;
+    if (state.failures >= this.config.circuitBreakerThreshold) {
+      state.openSince = Date.now();
+      console.error(
+        `[lcm] compaction circuit breaker OPEN: ${state.failures} consecutive auth failures for ${key}. Compaction halted. Will auto-retry after ${Math.round(this.config.circuitBreakerCooldownMs / 60000)}m or gateway restart.`,
+      );
+    }
+  }
+
+  private recordCompactionSuccess(key: string): void {
+    const state = this.circuitBreakerStates.get(key);
+    if (!state) {
+      return;
+    }
+    if (state.failures > 0 || state.openSince !== null) {
+      console.error(
+        `[lcm] compaction circuit breaker CLOSED: successful compaction for ${key} after ${state.failures} prior failures.`,
+      );
+    }
+    this.resetCircuitBreaker(key);
+  }
+
+  private resetCircuitBreaker(key: string): void {
+    this.circuitBreakerStates.delete(key);
+  }
+
   /** Ensure DB schema is up-to-date. Called lazily on first bootstrap/ingest/assemble/compact. */
   private ensureMigrated(): void {
     if (this.migrated) {
@@ -1152,9 +1375,10 @@ export class LcmContextEngine implements ContextEngine {
   }
 
   /** Prefer stable session keys for queue serialization when available. */
-  private resolveSessionQueueKey(sessionId: string, sessionKey?: string): string {
+  private resolveSessionQueueKey(sessionId?: string, sessionKey?: string): string {
     const normalizedSessionKey = sessionKey?.trim();
-    return normalizedSessionKey || sessionId;
+    const normalizedSessionId = sessionId?.trim();
+    return normalizedSessionKey || normalizedSessionId || "__lcm__";
   }
 
   /** Normalize optional live token estimates supplied by runtime callers. */
@@ -1189,6 +1413,12 @@ export class LcmContextEngine implements ContextEngine {
     return undefined;
   }
 
+  /** Cap a resolved token budget against the configured maxAssemblyTokenBudget. */
+  private applyAssemblyBudgetCap(budget: number): number {
+    const cap = this.config.maxAssemblyTokenBudget;
+    return cap != null && cap > 0 ? Math.min(budget, cap) : budget;
+  }
+
   /** Resolve an LCM conversation id from a session key via the session store. */
   private async resolveConversationIdForSessionKey(
     sessionKey: string,
@@ -1222,22 +1452,36 @@ export class LcmContextEngine implements ContextEngine {
   private async resolveSummarize(params: {
     legacyParams?: Record<string, unknown>;
     customInstructions?: string;
-  }): Promise<{ summarize: (text: string, aggressive?: boolean) => Promise<string>; summaryModel: string }> {
+    breakerScope: string;
+  }): Promise<{
+    summarize: (text: string, aggressive?: boolean) => Promise<string>;
+    summaryModel: string;
+    breakerKey?: string;
+  }> {
     const lp = params.legacyParams ?? {};
     if (typeof lp.summarize === "function") {
       return {
         summarize: lp.summarize as (text: string, aggressive?: boolean) => Promise<string>,
         summaryModel: "unknown",
+        breakerKey: `custom:${params.breakerScope}`,
       };
     }
     try {
+      const customInstructions =
+        params.customInstructions !== undefined
+          ? params.customInstructions
+          : (this.config.customInstructions || undefined);
       const runtimeSummarizer = await createLcmSummarizeFromLegacyParams({
         deps: this.deps,
         legacyParams: lp,
-        customInstructions: params.customInstructions,
+        customInstructions,
       });
       if (runtimeSummarizer) {
-        return { summarize: runtimeSummarizer.fn, summaryModel: runtimeSummarizer.model };
+        return {
+          summarize: runtimeSummarizer.fn,
+          summaryModel: runtimeSummarizer.model,
+          breakerKey: runtimeSummarizer.breakerKey,
+        };
       }
       console.error(`[lcm] resolveSummarize: createLcmSummarizeFromLegacyParams returned undefined`);
     } catch (err) {
@@ -1271,6 +1515,7 @@ export class LcmContextEngine implements ContextEngine {
       const result = await createLcmSummarizeFromLegacyParams({
         deps: this.deps,
         legacyParams: { provider, model },
+        customInstructions: this.config.customInstructions || undefined,
       });
       if (!result) {
         return undefined;
@@ -1508,14 +1753,24 @@ export class LcmContextEngine implements ContextEngine {
 
       const normalizedRawType =
         rawType === "function_call_output" ? "function_call_output" : "tool_result";
-      const compactBlock: Record<string, unknown> = {
-        type: normalizedRawType,
-        output: externalized.reference,
-        externalizedFileId: externalized.fileId,
-        originalByteSize: externalized.byteSize,
-        toolOutputExternalized: true,
-        externalizationReason: "large_tool_result",
-      };
+      const compactBlock: Record<string, unknown> = isPlainTextToolResult
+        ? {
+            type: "text",
+            text: externalized.reference,
+            rawType: normalizedRawType,
+            externalizedFileId: externalized.fileId,
+            originalByteSize: externalized.byteSize,
+            toolOutputExternalized: true,
+            externalizationReason: "large_tool_result",
+          }
+        : {
+            type: normalizedRawType,
+            output: externalized.reference,
+            externalizedFileId: externalized.fileId,
+            originalByteSize: externalized.byteSize,
+            toolOutputExternalized: true,
+            externalizationReason: "large_tool_result",
+          };
       const callId =
         safeString(record.tool_use_id) ??
         safeString(record.toolUseId) ??
@@ -1828,7 +2083,12 @@ export class LcmContextEngine implements ContextEngine {
           // First-time import path: no LCM rows yet, so seed directly from the
           // active leaf context snapshot.
           if (existingCount === 0) {
-            if (historicalMessages.length === 0) {
+            const bootstrapMessages = trimBootstrapMessagesToBudget(
+              historicalMessages,
+              resolveBootstrapMaxTokens(this.config),
+            );
+
+            if (bootstrapMessages.length === 0) {
               await this.conversationStore.markConversationBootstrapped(conversationId);
               await persistBootstrapState(conversationId, historicalMessages);
               return {
@@ -1839,7 +2099,7 @@ export class LcmContextEngine implements ContextEngine {
             }
 
             const nextSeq = (await this.conversationStore.getMaxSeq(conversationId)) + 1;
-            const bulkInput = historicalMessages.map((message, index) => {
+            const bulkInput = bootstrapMessages.map((message, index) => {
               const stored = toStoredMessage(message);
               return {
                 conversationId,
@@ -1945,6 +2205,208 @@ export class LcmContextEngine implements ContextEngine {
     return result;
   }
 
+  /**
+   * Remove messages from the batch that already exist in the DB for this session.
+   * Conservative replay detection: only strip a prefix when the incoming
+   * batch begins with the entire stored transcript for the session.
+   *
+   * Fixes two issues from #246:
+   * 1. Replaced hasMessage() fast-path with aligned-tail check — the old
+   *    approach false-positives on legitimate repeated first messages
+   * 2. Dedup now runs on newMessages only, before autoCompactionSummary
+   *    is prepended — synthetic summaries can no longer interfere with
+   *    replay detection
+   */
+  private async deduplicateAfterTurnBatch(
+    sessionId: string,
+    batch: AgentMessage[],
+  ): Promise<AgentMessage[]> {
+    if (batch.length === 0) return batch;
+
+    const conversation = await this.conversationStore.getConversationBySessionId(sessionId);
+    if (!conversation) return batch;
+
+    const conversationId = conversation.conversationId;
+    const storedMessageCount = await this.conversationStore.getMessageCount(conversationId);
+    if (storedMessageCount === 0 || storedMessageCount > batch.length) {
+      return batch;
+    }
+
+    // Aligned-tail check: DB's last message must match the message at the
+    // exact replay boundary in the incoming batch. This replaces the
+    // hasMessage() check which could false-positive on any repeated content.
+    const lastDbMessage = await this.conversationStore.getLastMessage(conversationId);
+    if (!lastDbMessage) return batch;
+
+    const storedBatch = batch.map((m) => toStoredMessage(m));
+    const batchAtBoundary = storedBatch[storedMessageCount - 1]!;
+    if (
+      messageIdentity(lastDbMessage.role, lastDbMessage.content) !==
+      messageIdentity(batchAtBoundary.role, batchAtBoundary.content)
+    ) {
+      return batch;
+    }
+
+    // Full proof: incoming batch must start with the entire stored transcript
+    // in exact order before we trim anything.
+    const storedMessages = await this.conversationStore.getMessages(conversationId, {
+      limit: storedMessageCount,
+    });
+    if (storedMessages.length !== storedMessageCount) {
+      return batch;
+    }
+    for (let i = 0; i < storedMessageCount; i += 1) {
+      const storedConversationMessage = storedMessages[i]!;
+      const incomingMessage = storedBatch[i]!;
+      if (
+        messageIdentity(storedConversationMessage.role, storedConversationMessage.content) !==
+        messageIdentity(incomingMessage.role, incomingMessage.content)
+      ) {
+        return batch;
+      }
+    }
+
+    return batch.slice(storedMessageCount);
+  }
+  /**
+   * Rebuild a compact tool-result message from stored message parts.
+   *
+   * The first transcript-GC pass only rewrites tool results that were already
+   * externalized into large_files during ingest, so the stored placeholder is
+   * the canonical replacement content.
+   */
+  private async buildTranscriptGcReplacementMessage(
+    messageId: number,
+  ): Promise<AgentMessage | null> {
+    const message = await this.conversationStore.getMessageById(messageId);
+    if (!message) {
+      return null;
+    }
+
+    const parts = await this.conversationStore.getMessageParts(messageId);
+    const toolCallId = pickToolCallId(parts);
+    if (!toolCallId) {
+      return null;
+    }
+
+    const content = contentFromParts(parts, "toolResult", message.content);
+    const toolName = pickToolName(parts) ?? "unknown";
+    const isError = pickToolIsError(parts);
+
+    return {
+      role: "toolResult",
+      toolCallId,
+      toolName,
+      content,
+      ...(isError !== undefined ? { isError } : {}),
+    } as AgentMessage;
+  }
+
+  /**
+   * Run transcript GC for summarized tool-result messages that already have a
+   * large_files-backed placeholder stored in LCM.
+   */
+  async maintain(params: {
+    sessionId: string;
+    sessionFile: string;
+    sessionKey?: string;
+    runtimeContext?: ContextEngineMaintenanceRuntimeContext;
+  }): Promise<ContextEngineMaintenanceResult> {
+    if (this.shouldIgnoreSession({ sessionId: params.sessionId, sessionKey: params.sessionKey })) {
+      return {
+        changed: false,
+        bytesFreed: 0,
+        rewrittenEntries: 0,
+        reason: "session excluded by pattern",
+      };
+    }
+    if (this.isStatelessSession(params.sessionKey)) {
+      return {
+        changed: false,
+        bytesFreed: 0,
+        rewrittenEntries: 0,
+        reason: "stateless session",
+      };
+    }
+    if (typeof params.runtimeContext?.rewriteTranscriptEntries !== "function") {
+      return {
+        changed: false,
+        bytesFreed: 0,
+        rewrittenEntries: 0,
+        reason: "runtime rewrite helper unavailable",
+      };
+    }
+
+    return this.withSessionQueue(
+      this.resolveSessionQueueKey(params.sessionId, params.sessionKey),
+      async () => {
+        const conversation = await this.conversationStore.getConversationForSession({
+          sessionId: params.sessionId,
+          sessionKey: params.sessionKey,
+        });
+        if (!conversation) {
+          return {
+            changed: false,
+            bytesFreed: 0,
+            rewrittenEntries: 0,
+            reason: "conversation not found",
+          };
+        }
+
+        const candidates = await this.summaryStore.listTranscriptGcCandidates(
+          conversation.conversationId,
+          { limit: TRANSCRIPT_GC_BATCH_SIZE },
+        );
+        if (candidates.length === 0) {
+          return {
+            changed: false,
+            bytesFreed: 0,
+            rewrittenEntries: 0,
+            reason: "no transcript GC candidates",
+          };
+        }
+
+        const transcriptEntryIdsByCallId = listTranscriptToolResultEntryIdsByCallId(
+          params.sessionFile,
+        );
+        const replacements: TranscriptRewriteReplacement[] = [];
+        const seenEntryIds = new Set<string>();
+
+        for (const candidate of candidates) {
+          const entryId = transcriptEntryIdsByCallId.get(candidate.toolCallId);
+          if (!entryId || seenEntryIds.has(entryId)) {
+            continue;
+          }
+
+          const replacementMessage = await this.buildTranscriptGcReplacementMessage(
+            candidate.messageId,
+          );
+          if (!replacementMessage) {
+            continue;
+          }
+
+          seenEntryIds.add(entryId);
+          replacements.push({
+            entryId,
+            message: replacementMessage,
+          });
+        }
+
+        if (replacements.length === 0) {
+          return {
+            changed: false,
+            bytesFreed: 0,
+            rewrittenEntries: 0,
+            reason: "no matching transcript entries",
+          };
+        }
+
+        return params.runtimeContext.rewriteTranscriptEntries({
+          replacements,
+        });
+      },
+    );
+  }
   private async ingestSingle(params: {
     sessionId: string;
     sessionKey?: string;
@@ -2096,6 +2558,12 @@ export class LcmContextEngine implements ContextEngine {
     }
     this.ensureMigrated();
 
+    // Dedup guard: prevent duplicate ingestion when gateway restart replays
+    // full history. Run on newMessages BEFORE prepending autoCompactionSummary
+    // so synthetic summaries cannot interfere with replay detection.
+    const newMessages = params.messages.slice(params.prePromptMessageCount);
+    const dedupedNewMessages = await this.deduplicateAfterTurnBatch(params.sessionId, newMessages);
+
     const ingestBatch: AgentMessage[] = [];
     if (params.autoCompactionSummary) {
       ingestBatch.push({
@@ -2104,8 +2572,7 @@ export class LcmContextEngine implements ContextEngine {
       } as AgentMessage);
     }
 
-    const newMessages = params.messages.slice(params.prePromptMessageCount);
-    ingestBatch.push(...newMessages);
+    ingestBatch.push(...dedupedNewMessages);
     if (ingestBatch.length === 0) {
       return;
     }
@@ -2133,7 +2600,7 @@ export class LcmContextEngine implements ContextEngine {
       runtimeContext: params.runtimeContext,
       legacyParams,
     });
-    const tokenBudget = resolvedTokenBudget ?? DEFAULT_AFTER_TURN_TOKEN_BUDGET;
+    const tokenBudget = this.applyAssemblyBudgetCap(resolvedTokenBudget ?? DEFAULT_AFTER_TURN_TOKEN_BUDGET);
     if (resolvedTokenBudget === undefined) {
       console.warn(
         `[lcm] afterTurn: tokenBudget not provided; using default ${DEFAULT_AFTER_TURN_TOKEN_BUDGET}`,
@@ -2180,6 +2647,8 @@ export class LcmContextEngine implements ContextEngine {
     sessionKey?: string;
     messages: AgentMessage[];
     tokenBudget?: number;
+    /** Optional user query for relevance-based eviction (BM25-lite). When absent or unsearchable, falls back to chronological eviction. */
+    prompt?: string;
   }): Promise<AssembleResult> {
     if (this.shouldIgnoreSession({ sessionId: params.sessionId, sessionKey: params.sessionKey })) {
       return {
@@ -2220,17 +2689,19 @@ export class LcmContextEngine implements ContextEngine {
         };
       }
 
-      const tokenBudget =
+      const tokenBudget = this.applyAssemblyBudgetCap(
         typeof params.tokenBudget === "number" &&
         Number.isFinite(params.tokenBudget) &&
         params.tokenBudget > 0
           ? Math.floor(params.tokenBudget)
-          : 128_000;
+          : 128_000,
+      );
 
       const assembled = await this.assembler.assemble({
         conversationId: conversation.conversationId,
         tokenBudget,
         freshTailCount: this.config.freshTailCount,
+        prompt: params.prompt,
       });
 
       // If assembly produced no messages for a non-empty live session,
@@ -2324,11 +2795,14 @@ export class LcmContextEngine implements ContextEngine {
         }
 
         const legacyParams = asRecord(params.runtimeContext) ?? params.legacyParams;
-        const tokenBudget = this.resolveTokenBudget({
+        const resolvedTokenBudget = this.resolveTokenBudget({
           tokenBudget: params.tokenBudget,
           runtimeContext: params.runtimeContext,
           legacyParams,
         });
+        const tokenBudget = resolvedTokenBudget
+          ? this.applyAssemblyBudgetCap(resolvedTokenBudget)
+          : resolvedTokenBudget;
         if (!tokenBudget) {
           return {
             ok: false,
@@ -2346,10 +2820,18 @@ export class LcmContextEngine implements ContextEngine {
               }
             ).currentTokenCount,
         );
-        const { summarize, summaryModel } = await this.resolveSummarize({
+        const { summarize, summaryModel, breakerKey } = await this.resolveSummarize({
           legacyParams,
           customInstructions: params.customInstructions,
+          breakerScope: this.resolveSessionQueueKey(params.sessionId, params.sessionKey),
         });
+        if (breakerKey && this.isCircuitBreakerOpen(breakerKey)) {
+          return {
+            ok: true,
+            compacted: false,
+            reason: "circuit breaker open",
+          };
+        }
 
         const leafResult = await this.compaction.compactLeaf({
           conversationId: conversation.conversationId,
@@ -2359,12 +2841,23 @@ export class LcmContextEngine implements ContextEngine {
           previousSummaryContent: params.previousSummaryContent,
           summaryModel,
         });
+
+        if (leafResult.authFailure && breakerKey) {
+          this.recordCompactionAuthFailure(breakerKey);
+        } else if (leafResult.actionTaken && breakerKey) {
+          this.recordCompactionSuccess(breakerKey);
+        }
+
         const tokensBefore = observedTokens ?? leafResult.tokensBefore;
 
         return {
           ok: true,
           compacted: leafResult.actionTaken,
-          reason: leafResult.actionTaken ? "compacted" : "below threshold",
+          reason: leafResult.authFailure
+            ? "provider auth failure"
+            : leafResult.actionTaken
+              ? "compacted"
+              : "below threshold",
           result: {
             tokensBefore,
             tokensAfter: leafResult.tokensAfter,
@@ -2429,129 +2922,161 @@ export class LcmContextEngine implements ContextEngine {
 
         const conversationId = conversation.conversationId;
 
-      const legacyParams = asRecord(params.runtimeContext) ?? params.legacyParams;
-      const lp = legacyParams ?? {};
-      const manualCompactionRequested =
-        (
-          lp as {
-            manualCompaction?: unknown;
-          }
-        ).manualCompaction === true;
-      const forceCompaction = force || manualCompactionRequested;
-      const tokenBudget = this.resolveTokenBudget({
-        tokenBudget: params.tokenBudget,
-        runtimeContext: params.runtimeContext,
-        legacyParams,
-      });
-      if (!tokenBudget) {
-        return {
-          ok: false,
-          compacted: false,
-          reason: "missing token budget in compact params",
-        };
-      }
-
-      const { summarize, summaryModel } = await this.resolveSummarize({
-        legacyParams,
-        customInstructions: params.customInstructions,
-      });
-
-      // Evaluate whether compaction is needed (unless forced)
-      const observedTokens = this.normalizeObservedTokenCount(
-        params.currentTokenCount ??
+        const legacyParams = asRecord(params.runtimeContext) ?? params.legacyParams;
+        const lp = legacyParams ?? {};
+        const manualCompactionRequested =
           (
             lp as {
-              currentTokenCount?: unknown;
+              manualCompaction?: unknown;
             }
-          ).currentTokenCount,
-      );
-      const decision =
-        observedTokens !== undefined
-          ? await this.compaction.evaluate(conversationId, tokenBudget, observedTokens)
-          : await this.compaction.evaluate(conversationId, tokenBudget);
-      const targetTokens =
-        params.compactionTarget === "threshold" ? decision.threshold : tokenBudget;
-      const liveContextStillExceedsTarget =
-        observedTokens !== undefined && observedTokens >= targetTokens;
-
-      if (!forceCompaction && !decision.shouldCompact) {
-        return {
-          ok: true,
-          compacted: false,
-          reason: "below threshold",
-          result: {
-            tokensBefore: decision.currentTokens,
-          },
-        };
-      }
+          ).manualCompaction === true;
+        const forceCompaction = force || manualCompactionRequested;
+        const resolvedTokenBudget = this.resolveTokenBudget({
+          tokenBudget: params.tokenBudget,
+          runtimeContext: params.runtimeContext,
+          legacyParams,
+        });
+        const tokenBudget = resolvedTokenBudget
+          ? this.applyAssemblyBudgetCap(resolvedTokenBudget)
+          : resolvedTokenBudget;
+        if (!tokenBudget) {
+          return {
+            ok: false,
+            compacted: false,
+            reason: "missing token budget in compact params",
+          };
+        }
+
+        const { summarize, summaryModel, breakerKey } = await this.resolveSummarize({
+          legacyParams,
+          customInstructions: params.customInstructions,
+          breakerScope: this.resolveSessionQueueKey(params.sessionId, params.sessionKey),
+        });
+        if (breakerKey && this.isCircuitBreakerOpen(breakerKey)) {
+          return {
+            ok: true,
+            compacted: false,
+            reason: "circuit breaker open",
+          };
+        }
+
+        // Evaluate whether compaction is needed (unless forced)
+        const observedTokens = this.normalizeObservedTokenCount(
+          params.currentTokenCount ??
+            (
+              lp as {
+                currentTokenCount?: unknown;
+              }
+            ).currentTokenCount,
+        );
+        const decision =
+          observedTokens !== undefined
+            ? await this.compaction.evaluate(conversationId, tokenBudget, observedTokens)
+            : await this.compaction.evaluate(conversationId, tokenBudget);
+        const targetTokens =
+          params.compactionTarget === "threshold" ? decision.threshold : tokenBudget;
+        const liveContextStillExceedsTarget =
+          observedTokens !== undefined && observedTokens >= targetTokens;
+
+        if (!forceCompaction && !decision.shouldCompact) {
+          return {
+            ok: true,
+            compacted: false,
+            reason: "below threshold",
+            result: {
+              tokensBefore: decision.currentTokens,
+            },
+          };
+        }
 
-      const useSweep =
-        manualCompactionRequested || forceCompaction || params.compactionTarget === "threshold";
-      if (useSweep) {
-        const sweepResult = await this.compaction.compactFullSweep({
+        const useSweep =
+          manualCompactionRequested || forceCompaction || params.compactionTarget === "threshold";
+        if (useSweep) {
+          const sweepResult = await this.compaction.compactFullSweep({
+            conversationId,
+            tokenBudget,
+            summarize,
+            force: forceCompaction,
+            hardTrigger: false,
+            summaryModel,
+          });
+
+          if (sweepResult.authFailure && breakerKey) {
+            this.recordCompactionAuthFailure(breakerKey);
+          } else if (sweepResult.actionTaken && breakerKey) {
+            this.recordCompactionSuccess(breakerKey);
+          }
+
+          return {
+            ok: !sweepResult.authFailure && (sweepResult.actionTaken || !liveContextStillExceedsTarget),
+            compacted: sweepResult.actionTaken,
+            reason: sweepResult.authFailure
+              ? (sweepResult.actionTaken
+                  ? "provider auth failure after partial compaction"
+                  : "provider auth failure")
+              : sweepResult.actionTaken
+                ? "compacted"
+                : manualCompactionRequested
+                  ? "nothing to compact"
+                  : liveContextStillExceedsTarget
+                    ? "live context still exceeds target"
+                    : "already under target",
+            result: {
+              tokensBefore: decision.currentTokens,
+              tokensAfter: sweepResult.tokensAfter,
+              details: {
+                rounds: sweepResult.actionTaken ? 1 : 0,
+                targetTokens,
+              },
+            },
+          };
+        }
+
+        // When forced, use the token budget as target
+        const convergenceTargetTokens = forceCompaction
+          ? tokenBudget
+          : params.compactionTarget === "threshold"
+            ? decision.threshold
+            : tokenBudget;
+
+        const compactResult = await this.compaction.compactUntilUnder({
           conversationId,
           tokenBudget,
+          targetTokens: convergenceTargetTokens,
+          ...(observedTokens !== undefined ? { currentTokens: observedTokens } : {}),
           summarize,
-          force: forceCompaction,
-          hardTrigger: false,
           summaryModel,
         });
 
+        if (compactResult.authFailure && breakerKey) {
+          this.recordCompactionAuthFailure(breakerKey);
+        } else if (compactResult.rounds > 0 && breakerKey) {
+          this.recordCompactionSuccess(breakerKey);
+        }
+
+        const didCompact = compactResult.rounds > 0;
+
         return {
-          ok: sweepResult.actionTaken || !liveContextStillExceedsTarget,
-          compacted: sweepResult.actionTaken,
-          reason: sweepResult.actionTaken
-            ? "compacted"
-            : manualCompactionRequested
-              ? "nothing to compact"
-              : liveContextStillExceedsTarget
-                ? "live context still exceeds target"
-                : "already under target",
+          ok: compactResult.success,
+          compacted: didCompact,
+          reason: compactResult.authFailure
+            ? (didCompact
+                ? "provider auth failure after partial compaction"
+                : "provider auth failure")
+            : compactResult.success
+              ? didCompact
+                ? "compacted"
+                : "already under target"
+              : "could not reach target",
           result: {
             tokensBefore: decision.currentTokens,
-            tokensAfter: sweepResult.tokensAfter,
+            tokensAfter: compactResult.finalTokens,
             details: {
-              rounds: sweepResult.actionTaken ? 1 : 0,
-              targetTokens,
+              rounds: compactResult.rounds,
+              targetTokens: convergenceTargetTokens,
             },
           },
         };
-      }
-
-      // When forced, use the token budget as target
-      const convergenceTargetTokens = forceCompaction
-        ? tokenBudget
-        : params.compactionTarget === "threshold"
-          ? decision.threshold
-          : tokenBudget;
-
-      const compactResult = await this.compaction.compactUntilUnder({
-        conversationId,
-        tokenBudget,
-        targetTokens: convergenceTargetTokens,
-        ...(observedTokens !== undefined ? { currentTokens: observedTokens } : {}),
-        summarize,
-        summaryModel,
-      });
-      const didCompact = compactResult.rounds > 0;
-
-      return {
-        ok: compactResult.success,
-        compacted: didCompact,
-        reason: compactResult.success
-          ? didCompact
-            ? "compacted"
-            : "already under target"
-          : "could not reach target",
-        result: {
-          tokensBefore: decision.currentTokens,
-          tokensAfter: compactResult.finalTokens,
-          details: {
-            rounds: compactResult.rounds,
-            targetTokens: convergenceTargetTokens,
-          },
-        },
-      };
       },
     );
   }
@@ -2662,6 +3187,90 @@ export class LcmContextEngine implements ContextEngine {
     // The shared connection is managed for the lifetime of the plugin process.
   }
 
+  /** Apply LCM lifecycle semantics for OpenClaw's /new and /reset commands. */
+  async handleBeforeReset(params: {
+    reason?: string;
+    sessionId?: string;
+    sessionKey?: string;
+  }): Promise<void> {
+    const reason = params.reason?.trim();
+    if (reason !== "new" && reason !== "reset") {
+      return;
+    }
+    if (this.shouldIgnoreSession({ sessionId: params.sessionId, sessionKey: params.sessionKey })) {
+      return;
+    }
+    if (this.isStatelessSession(params.sessionKey)) {
+      return;
+    }
+
+    this.ensureMigrated();
+    await this.withSessionQueue(
+      this.resolveSessionQueueKey(params.sessionId, params.sessionKey),
+      async () =>
+        this.conversationStore.withTransaction(async () => {
+          if (reason === "new") {
+            const conversation = await this.conversationStore.getConversationForSession({
+              sessionId: params.sessionId,
+              sessionKey: params.sessionKey,
+            });
+            if (!conversation) {
+              return;
+            }
+
+            const retainDepth =
+              typeof this.config.newSessionRetainDepth === "number"
+              && Number.isFinite(this.config.newSessionRetainDepth)
+                ? this.config.newSessionRetainDepth
+                : 2;
+            await this.summaryStore.pruneForNewSession(conversation.conversationId, retainDepth);
+            this.deps.log.info(
+              `[lcm] /new pruned conversation ${conversation.conversationId} to retain depth ${retainDepth}`,
+            );
+            return;
+          }
+
+          const current = await this.conversationStore.getConversationForSession({
+            sessionId: params.sessionId,
+            sessionKey: params.sessionKey,
+          });
+          if (current?.active) {
+            const currentMessageCount = await this.conversationStore.getMessageCount(
+              current.conversationId,
+            );
+            const currentContextItems = await this.summaryStore.getContextItems(
+              current.conversationId,
+            );
+            if (
+              currentMessageCount === 0
+              && currentContextItems.length === 0
+              && !current.bootstrappedAt
+            ) {
+              this.deps.log.info(
+                `[lcm] /reset no-op for already fresh conversation ${current.conversationId}`,
+              );
+              return;
+            }
+            await this.conversationStore.archiveConversation(current.conversationId);
+          }
+
+          const nextSessionId = params.sessionId?.trim() || current?.sessionId;
+          if (!nextSessionId) {
+            this.deps.log.warn("[lcm] /reset skipped: no session identity available");
+            return;
+          }
+
+          const freshConversation = await this.conversationStore.createConversation({
+            sessionId: nextSessionId,
+            sessionKey: params.sessionKey?.trim(),
+          });
+          this.deps.log.info(
+            `[lcm] /reset archived prior conversation and created ${freshConversation.conversationId}`,
+          );
+        }),
+    );
+  }
+
   // ── Public accessors for retrieval (used by subagent expansion) ─────────
 
   getRetrieval(): RetrievalEngine {