@martian-engineering/lossless-claw 0.6.2 → 0.7.0

package/src/store/conversation-store.ts

@@ -4,6 +4,7 @@ import { withDatabaseTransaction } from "../transaction-mutex.js";
 import { sanitizeFts5Query } from "./fts5-sanitize.js";
 import { buildLikeSearchPlan, containsCjk, createFallbackSnippet } from "./full-text-fallback.js";
 import { parseUtcTimestamp, parseUtcTimestampOrNull } from "./parse-utc-timestamp.js";
+import { buildFtsOrderBy, type SearchSort } from "./full-text-sort.js";
 
 export type ConversationId = number;
 export type MessageId = number;
@@ -94,6 +95,7 @@ export type MessageSearchInput = {
   since?: Date;
   before?: Date;
   limit?: number;
+  sort?: SearchSort;
 };
 
 export type MessageSearchResult = {
@@ -714,6 +716,7 @@ export class ConversationStore {
             input.conversationId,
             input.since,
             input.before,
+            input.sort,
           );
         } catch {
           return this.searchLike(
@@ -764,6 +767,7 @@ export class ConversationStore {
     conversationId?: ConversationId,
     since?: Date,
     before?: Date,
+    sort?: SearchSort,
   ): MessageSearchResult[] {
     const where: string[] = ["messages_fts MATCH ?"];
     const args: Array<string | number> = [sanitizeFts5Query(query)];
@@ -780,6 +784,7 @@ export class ConversationStore {
       args.push(before.toISOString());
     }
     args.push(limit);
+    const orderBy = buildFtsOrderBy(sort, "m.created_at");
 
     const sql = `SELECT
          m.message_id,
@@ -791,7 +796,7 @@ export class ConversationStore {
        FROM messages_fts
        JOIN messages m ON m.message_id = messages_fts.rowid
        WHERE ${where.join(" AND ")}
-       ORDER BY m.created_at DESC
+       ORDER BY ${orderBy}
        LIMIT ?`;
     const rows = this.db.prepare(sql).all(...args) as unknown as MessageSearchRow[];
     return rows.map(toSearchResult);

package/src/store/fts5-sanitize.ts

@@ -21,9 +21,30 @@
  *   'hello "world"'       →  '"hello" "world"'
  */
 export function sanitizeFts5Query(raw: string): string {
-  const tokens = raw.split(/\s+/).filter(Boolean);
-  if (tokens.length === 0) {
-    return '""';
+  // Preserve user-quoted phrases: extract "..." groups first, then tokenize the rest.
+  const parts: string[] = [];
+  const phraseRegex = /"([^"]+)"/g;
+  let match: RegExpExecArray | null;
+  let lastIndex = 0;
+
+  while ((match = phraseRegex.exec(raw)) !== null) {
+    // Process unquoted text before this phrase
+    const before = raw.slice(lastIndex, match.index);
+    for (const t of before.split(/\s+/).filter(Boolean)) {
+      parts.push(`"${t.replace(/"/g, "")}"`);
+    }
+    // Preserve the phrase as-is (strip internal quotes for safety)
+    const phrase = match[1].replace(/"/g, "").trim();
+    if (phrase) {
+      parts.push(`"${phrase}"`);
+    }
+    lastIndex = match.index + match[0].length;
   }
-  return tokens.map((t) => `"${t.replace(/"/g, "")}"`).join(" ");
+
+  // Process unquoted text after last phrase
+  for (const t of raw.slice(lastIndex).split(/\s+/).filter(Boolean)) {
+    parts.push(`"${t.replace(/"/g, "")}"`);
+  }
+
+  return parts.length > 0 ? parts.join(" ") : '""';
 }

package/src/store/full-text-sort.ts

@@ -0,0 +1,21 @@
+export type SearchSort = "recency" | "relevance" | "hybrid";
+
+export const AGE_DECAY_RATE = 0.001;
+
+/**
+ * Build the ORDER BY clause for FTS5-backed searches.
+ *
+ * `rank` is FTS5's BM25 score where lower (more negative) is better.
+ * `hybrid` keeps that relevance signal but applies a mild age penalty before
+ * LIMIT is enforced so older strong matches can still surface.
+ */
+export function buildFtsOrderBy(sort: SearchSort | undefined, createdAtExpr: string): string {
+  switch (sort ?? "recency") {
+    case "relevance":
+      return `rank ASC, ${createdAtExpr} DESC`;
+    case "hybrid":
+      return `(rank / (1 + ((julianday('now') - julianday(${createdAtExpr})) * 24 * ${AGE_DECAY_RATE}))) ASC, ${createdAtExpr} DESC`;
+    default:
+      return `${createdAtExpr} DESC`;
+  }
+}

package/src/store/index.ts

@@ -29,3 +29,11 @@ export type {
   UpsertConversationBootstrapStateInput,
   ConversationBootstrapStateRecord,
 } from "./summary-store.js";
+
+export { CompactionTelemetryStore } from "./compaction-telemetry-store.js";
+export type {
+  CacheState,
+  ActivityBand,
+  ConversationCompactionTelemetryRecord,
+  UpsertConversationCompactionTelemetryInput,
+} from "./compaction-telemetry-store.js";

package/src/store/summary-store.ts

@@ -3,6 +3,7 @@ import { withDatabaseTransaction } from "../transaction-mutex.js";
 import { sanitizeFts5Query } from "./fts5-sanitize.js";
 import { buildLikeSearchPlan, containsCjk, createFallbackSnippet } from "./full-text-fallback.js";
 import { parseUtcTimestamp, parseUtcTimestampOrNull } from "./parse-utc-timestamp.js";
+import { buildFtsOrderBy, type SearchSort } from "./full-text-sort.js";
 
 export type SummaryKind = "leaf" | "condensed";
 export type ContextItemType = "message" | "summary";
@@ -68,6 +69,7 @@ export type SummarySearchInput = {
   since?: Date;
   before?: Date;
   limit?: number;
+  sort?: SearchSort;
 };
 
 export type SummarySearchResult = {
@@ -958,7 +960,10 @@ export class SummaryStore {
       .run(conversationId, startOrdinal, summaryId);
 
     // 3. Resequence all ordinals to maintain contiguity (no gaps).
-    //    Fetch current items, then update ordinals in order.
+    //    Pre-compute ranks from a SELECT (safe snapshot), then apply
+    //    via 2-pass UPDATE loop using negative temps to avoid UNIQUE
+    //    constraint violations. The SELECT reads post-delete/insert
+    //    state and provides a consistent snapshot for resequencing.
     const items = this.db
       .prepare(
         `SELECT ordinal FROM context_items
@@ -967,18 +972,17 @@ export class SummaryStore {
       )
       .all(conversationId) as unknown as { ordinal: number }[];
 
-    const updateStmt = this.db.prepare(
-      `UPDATE context_items
-       SET ordinal = ?
-       WHERE conversation_id = ? AND ordinal = ?`,
-    );
-
-    // Use negative temp ordinals first to avoid unique constraint conflicts.
-    for (let i = 0; i < items.length; i++) {
-      updateStmt.run(-(i + 1), conversationId, items[i].ordinal);
-    }
-    for (let i = 0; i < items.length; i++) {
-      updateStmt.run(i, conversationId, -(i + 1));
+    if (items.length > 0 && items.some((item, i) => item.ordinal !== i)) {
+      const updateStmt = this.db.prepare(
+        `UPDATE context_items SET ordinal = ?
+         WHERE conversation_id = ? AND ordinal = ?`,
+      );
+      for (let i = 0; i < items.length; i++) {
+        updateStmt.run(-(i + 1), conversationId, items[i].ordinal);
+      }
+      for (let i = 0; i < items.length; i++) {
+        updateStmt.run(i, conversationId, -(i + 1));
+      }
     }
   }
 
@@ -1051,6 +1055,7 @@ export class SummaryStore {
             input.conversationId,
             input.since,
             input.before,
+            input.sort,
           );
         } catch {
           return this.searchLike(
@@ -1073,6 +1078,7 @@ export class SummaryStore {
     conversationId?: number,
     since?: Date,
     before?: Date,
+    sort?: SearchSort,
   ): SummarySearchResult[] {
     const where: string[] = ["summaries_fts MATCH ?"];
     const args: Array<string | number> = [sanitizeFts5Query(query)];
@@ -1089,6 +1095,7 @@ export class SummaryStore {
       args.push(before.toISOString());
     }
     args.push(limit);
+    const orderBy = buildFtsOrderBy(sort, "s.created_at");
 
     const sql = `SELECT
          summaries_fts.summary_id,
@@ -1100,7 +1107,7 @@ export class SummaryStore {
        FROM summaries_fts
        JOIN summaries s ON s.summary_id = summaries_fts.summary_id
        WHERE ${where.join(" AND ")}
-       ORDER BY s.created_at DESC
+       ORDER BY ${orderBy}
        LIMIT ?`;
     const rows = this.db.prepare(sql).all(...args) as unknown as SummarySearchRow[];
     return rows.map(toSearchResult);

package/src/summarize.ts

@@ -1,3 +1,4 @@
+import { describeLogError } from "./lcm-log.js";
 import type { LcmDependencies } from "./types.js";
 
 export type LcmSummarizeOptions = {
@@ -1068,6 +1069,17 @@ function resolveSummaryCandidates(params: {
     },
   ];
 
+  // Append explicit fallback providers from config.
+  for (const fb of params.deps.config.fallbackProviders ?? []) {
+    resolutionCandidates.push({
+      levelName: `explicit fallback (${fb.provider}/${fb.model})`,
+      modelRef: `${fb.provider}/${fb.model}`,
+      providerHint: fb.provider,
+      hasExplicitProvider: true,
+      useLegacyAuthProfile: false,
+    });
+  }
+
   const resolvedCandidates: ResolvedSummaryCandidate[] = [];
   for (const candidate of resolutionCandidates) {
     if (!candidate.modelRef) {
@@ -1088,9 +1100,8 @@ function resolveSummaryCandidates(params: {
         });
       }
     } catch (err) {
-      console.error(
-        `[lcm] createLcmSummarize: resolveModel FAILED at ${candidate.levelName}:`,
-        err instanceof Error ? err.message : err,
+      params.deps.log.error(
+        `[lcm] createLcmSummarize: resolveModel FAILED at ${candidate.levelName}: ${describeLogError(err)}`,
       );
     }
   }
@@ -1111,7 +1122,7 @@ export async function createLcmSummarizeFromLegacyParams(params: {
 }): Promise<{ fn: LcmSummarizeFn; model: string; breakerKey: string } | undefined> {
   const resolvedCandidates = resolveSummaryCandidates(params);
   if (resolvedCandidates.length === 0) {
-    console.error("[lcm] createLcmSummarize: no summary model candidates resolved");
+    params.deps.log.error("[lcm] createLcmSummarize: no summary model candidates resolved");
     return undefined;
   }
 
@@ -1197,6 +1208,7 @@ export async function createLcmSummarizeFromLegacyParams(params: {
         requestApiKey: string | undefined,
         label: string,
         reasoning?: string,
+        options?: { skipModelAuth?: boolean },
       ) =>
         withTimeout(params.deps.complete({
           provider,
@@ -1215,6 +1227,7 @@ export async function createLcmSummarizeFromLegacyParams(params: {
           ],
           maxTokens: targetTokens,
           ...(reasoning ? { reasoning } : {}),
+          ...(options?.skipModelAuth === true ? { skipModelAuth: true } : {}),
         }), summarizerTimeoutMs, label);
 
       const retryWithoutModelAuth = async (
@@ -1226,8 +1239,8 @@ export async function createLcmSummarizeFromLegacyParams(params: {
         if (runtimeManagedAuth) {
           throw initialAuthError;
         }
-        console.warn(initialAuthError.message);
-        console.warn(
+        params.deps.log.warn(initialAuthError.message);
+        params.deps.log.warn(
           `[lcm] summarizer auth retry: retrying ${provider}/${model} without runtime.modelAuth credentials.`,
         );
 
@@ -1236,14 +1249,16 @@ export async function createLcmSummarizeFromLegacyParams(params: {
           skipModelAuth: true,
         });
         if (!directApiKey) {
-          console.warn(
+          params.deps.log.warn(
             `[lcm] summarizer auth retry unavailable: no direct credentials found for ${provider}/${model}.`,
           );
           throw initialAuthError;
         }
 
         try {
-          const directResult = await runSummarizerCall(directApiKey, "auth-retry", reasoning);
+          const directResult = await runSummarizerCall(directApiKey, "auth-retry", reasoning, {
+            skipModelAuth: true,
+          });
           // Use requireStructuralSignal on the retry success path too — the
           // summary text may legitimately contain auth-error phrases.
           const directFailure = extractProviderAuthFailure(directResult, {
@@ -1255,10 +1270,10 @@ export async function createLcmSummarizeFromLegacyParams(params: {
               model,
               failure: directFailure,
             });
-            console.warn(retryAuthError.message);
+            params.deps.log.warn(retryAuthError.message);
             throw retryAuthError;
           }
-          console.warn(
+          params.deps.log.info(
             `[lcm] summarizer auth retry succeeded; provider=${provider}; model=${model}; source=direct-credentials`,
           );
           return directResult;
@@ -1277,7 +1292,7 @@ export async function createLcmSummarizeFromLegacyParams(params: {
               model,
               failure: directFailure,
             });
-            console.warn(retryAuthError.message);
+            params.deps.log.warn(retryAuthError.message);
             throw retryAuthError;
           }
           throw directErr;
@@ -1317,31 +1332,35 @@ export async function createLcmSummarizeFromLegacyParams(params: {
         if (err instanceof LcmProviderAuthError) {
           lastAuthError = err;
           if (nextCandidate) {
-            console.warn(
-              `[lcm] summarizer auth fallback: retrying with ${nextCandidate.provider}/${nextCandidate.model} after ${provider}/${model} failed auth.`,
+            params.deps.log.warn(
+              `[lcm] PROVIDER FALLBACK: ${provider}/${model} auth failed → trying ${nextCandidate.provider}/${nextCandidate.model}`,
             );
+            const backoffMs = Math.min(500 * Math.pow(2, index), 8000);
+            await new Promise((r) => setTimeout(r, backoffMs));
             continue;
           }
           throw lastAuthError;
         }
         const errMsg = err instanceof Error ? err.message : String(err);
         const isTimeout = errMsg.includes("summarizer timeout");
-        console.warn(
+        params.deps.log.warn(
           `[lcm] summarizer ${isTimeout ? "timed out" : "failed"}; provider=${provider}; model=${model}; timeout=${summarizerTimeoutMs}ms; error=${errMsg}`,
         );
         if (nextCandidate) {
-          console.warn(
-            `[lcm] summarizer candidate fallback: retrying with ${nextCandidate.provider}/${nextCandidate.model} after ${provider}/${model} ${isTimeout ? "timed out" : "failed"}.`,
+          params.deps.log.warn(
+            `[lcm] PROVIDER FALLBACK: ${provider}/${model} ${isTimeout ? "timed out" : "failed"} → trying ${nextCandidate.provider}/${nextCandidate.model}`,
           );
+          const backoffMs = Math.min(500 * Math.pow(2, index), 8000);
+          await new Promise((r) => setTimeout(r, backoffMs));
           continue;
         }
         if (err instanceof SummarizerTimeoutError) {
-          console.error(
+          params.deps.log.warn(
             `[lcm] summarizer timed out; provider=${provider}; model=${model}; source=fallback`,
           );
           return buildDeterministicFallbackSummary(text, targetTokens);
         }
-        return "";
+        break;
       }
 
       const normalized = normalizeCompletionSummary(result.content);
@@ -1358,7 +1377,7 @@ export async function createLcmSummarizeFromLegacyParams(params: {
         if (envelopeNormalized.summary) {
           summary = envelopeNormalized.summary;
           summarySource = "envelope";
-          console.error(
+          params.deps.log.info(
             `[lcm] recovered summary from response envelope; provider=${provider}; model=${model}; ` +
               `block_types=${formatBlockTypes(envelopeNormalized.blockTypes)}; source=envelope`,
           );
@@ -1386,7 +1405,7 @@ export async function createLcmSummarizeFromLegacyParams(params: {
         if (responseDiag) {
           diagParts.push(responseDiag);
         }
-        console.error(`${diagParts.join("; ")}; retrying with conservative settings`);
+        params.deps.log.warn(`${diagParts.join("; ")}; retrying with conservative settings`);
 
         // Single retry with conservative parameters: low temperature and low
         // reasoning budget to coax a textual response from providers that
@@ -1401,7 +1420,7 @@ export async function createLcmSummarizeFromLegacyParams(params: {
 
           if (summary) {
             summarySource = "retry";
-            console.error(
+            params.deps.log.info(
               `[lcm] retry succeeded; provider=${provider}; model=${model}; ` +
                 `block_types=${formatBlockTypes(retryEnvelopeNormalized.blockTypes)}; source=retry`,
             );
@@ -1418,21 +1437,23 @@ export async function createLcmSummarizeFromLegacyParams(params: {
               retryParts.push(retryDiag);
             }
             if (nextCandidate) {
-              console.warn(
+              params.deps.log.warn(
                 `${retryParts.join("; ")}; retrying with ${nextCandidate.provider}/${nextCandidate.model}`,
               );
               continue;
             }
-            console.error(`${retryParts.join("; ")}; falling back to truncation`);
+            params.deps.log.warn(`${retryParts.join("; ")}; falling back to truncation`);
             summary = initialSummary;
           }
         } catch (retryErr) {
           if (retryErr instanceof LcmProviderAuthError) {
             lastAuthError = retryErr;
             if (nextCandidate) {
-              console.warn(
-                `[lcm] summarizer auth fallback: retrying with ${nextCandidate.provider}/${nextCandidate.model} after ${provider}/${model} failed auth.`,
+              params.deps.log.warn(
+                `[lcm] PROVIDER FALLBACK: ${provider}/${model} auth failed on retry → trying ${nextCandidate.provider}/${nextCandidate.model}`,
               );
+              const backoffMs = Math.min(500 * Math.pow(2, index), 8000);
+              await new Promise((r) => setTimeout(r, backoffMs));
               continue;
             }
             throw lastAuthError;
@@ -1441,12 +1462,12 @@ export async function createLcmSummarizeFromLegacyParams(params: {
           const retryErrMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
           const isRetryTimeout = retryErrMsg.includes("summarizer timeout");
           if (nextCandidate) {
-            console.warn(
+            params.deps.log.warn(
               `[lcm] retry ${isRetryTimeout ? "timed out" : "failed"}; provider=${provider}; model=${model}; timeout=${summarizerTimeoutMs}ms; error=${retryErrMsg}; retrying with ${nextCandidate.provider}/${nextCandidate.model}`,
             );
             continue;
           }
-          console.warn(
+          params.deps.log.warn(
             `[lcm] retry ${isRetryTimeout ? "timed out" : "failed"}; provider=${provider}; model=${model}; timeout=${summarizerTimeoutMs}ms; error=${retryErrMsg}; falling back to truncation`,
           );
           summary = initialSummary;
@@ -1455,14 +1476,14 @@ export async function createLcmSummarizeFromLegacyParams(params: {
 
       if (!summary) {
         summarySource = "fallback";
-        console.error(
+        params.deps.log.error(
           `[lcm] all extraction attempts exhausted; provider=${provider}; model=${model}; source=fallback`,
         );
         return buildDeterministicFallbackSummary(text, targetTokens);
       }
 
       if (summarySource !== "content") {
-        console.error(
+        params.deps.log.info(
           `[lcm] summary resolved via non-content path; provider=${provider}; model=${model}; source=${summarySource}`,
         );
       }
@@ -1470,10 +1491,13 @@ export async function createLcmSummarizeFromLegacyParams(params: {
       return summary;
     }
 
+    params.deps.log.error(
+      `[lcm] ALL PROVIDERS EXHAUSTED: ${resolvedCandidates.length} candidate(s) tried, none succeeded. Compaction falling back to deterministic truncation. Check provider keys and quotas.`,
+    );
     if (lastAuthError) {
       throw lastAuthError;
     }
-    return "";
+    return buildDeterministicFallbackSummary(text, targetTokens);
   };
 
   return {

package/src/tools/lcm-describe-tool.ts

@@ -57,7 +57,8 @@ function normalizeRequestedTokenCap(value: unknown): number | undefined {
 
 export function createLcmDescribeTool(input: {
   deps: LcmDependencies;
-  lcm: LcmContextEngine;
+  lcm?: LcmContextEngine;
+  getLcm?: () => Promise<LcmContextEngine>;
   sessionId?: string;
   sessionKey?: string;
 }): AnyAgentTool {
@@ -71,12 +72,16 @@ export function createLcmDescribeTool(input: {
       "token counts, and file exploration results.",
     parameters: LcmDescribeSchema,
     async execute(_toolCallId, params) {
-      const retrieval = input.lcm.getRetrieval();
-      const timezone = input.lcm.timezone;
+      const lcm = input.lcm ?? (await input.getLcm?.());
+      if (!lcm) {
+        throw new Error("LCM engine is unavailable.");
+      }
+      const retrieval = lcm.getRetrieval();
+      const timezone = lcm.timezone;
       const p = params as Record<string, unknown>;
       const id = (p.id as string).trim();
       const conversationScope = await resolveLcmConversationScope({
-        lcm: input.lcm,
+        lcm,
         deps: input.deps,
         sessionId: input.sessionId,
         sessionKey: input.sessionKey,

package/src/tools/lcm-expand-query-tool.ts

@@ -195,7 +195,7 @@ function buildDelegatedExpandQueryTask(params: {
     "",
     "Strategy:",
     "1. Start with `lcm_describe` on seed summaries to inspect subtree manifests and branch costs.",
-    "2. If additional candidates are needed, use `lcm_grep` scoped to summaries.",
+    "2. If additional candidates are needed, use `lcm_grep` scoped to summaries. Prefer `mode: \"full_text\"`, quote exact multi-word phrases, use `sort: \"relevance\"` for older-topic recall, and `sort: \"hybrid\"` when recency should still matter.",
     "3. Select branches that fit remaining budget; prefer high-signal paths first.",
     "4. Call `lcm_expand` selectively (do not expand everything blindly).",
     "5. Keep includeMessages=false by default; use includeMessages=true for the message-backed seed summaries above and any other specific leaf evidence.",
@@ -444,7 +444,8 @@ async function resolveSummaryCandidates(params: {
 
 export function createLcmExpandQueryTool(input: {
   deps: LcmDependencies;
-  lcm: LcmContextEngine;
+  lcm?: LcmContextEngine;
+  getLcm?: () => Promise<LcmContextEngine>;
   /** Session id used for LCM conversation scoping. */
   sessionId?: string;
   /** Requester agent session key used for delegated child session/auth scoping. */
@@ -462,9 +463,13 @@ export function createLcmExpandQueryTool(input: {
     description:
       "Answer a focused question using delegated LCM expansion. " +
       "Find candidate summaries (by IDs or query), expand them in a delegated sub-agent, " +
-      "and return a compact prompt-focused answer with cited summary IDs.",
+      "and return a compact prompt-focused answer. Tool output includes cited summary IDs for follow-up.",
     parameters: LcmExpandQuerySchema,
     async execute(_toolCallId, params) {
+      const lcm = input.lcm ?? (await input.getLcm?.());
+      if (!lcm) {
+        throw new Error("LCM engine is unavailable.");
+      }
       const p = params as Record<string, unknown>;
       const explicitSummaryIds = normalizeSummaryIds(p.summaryIds as string[] | undefined);
       const query = typeof p.query === "string" ? p.query.trim() : "";
@@ -537,7 +542,7 @@ export function createLcmExpandQueryTool(input: {
 
       try {
         const conversationScope = await resolveLcmConversationScope({
-          lcm: input.lcm,
+          lcm,
           deps: input.deps,
           sessionId: input.sessionId,
           sessionKey: input.sessionKey,
@@ -552,7 +557,7 @@ export function createLcmExpandQueryTool(input: {
           scopedConversationId = await resolveRequesterConversationScopeId({
             deps: input.deps,
             requesterSessionKey: callerSessionKey,
-            lcm: input.lcm,
+            lcm,
           });
         }
 
@@ -564,7 +569,7 @@ export function createLcmExpandQueryTool(input: {
         }
 
         const candidates = await resolveSummaryCandidates({
-          lcm: input.lcm,
+          lcm,
           explicitSummaryIds,
           query: query || undefined,
           conversationId: scopedConversationId,

package/src/tools/lcm-expand-tool.ts

@@ -122,7 +122,8 @@ function buildOrchestrationObservability(input: {
  */
 export function createLcmExpandTool(input: {
   deps: LcmDependencies;
-  lcm: LcmContextEngine;
+  lcm?: LcmContextEngine;
+  getLcm?: () => Promise<LcmContextEngine>;
   /** Runtime session key (used for delegated expansion auth scoping). */
   sessionId?: string;
   sessionKey?: string;
@@ -136,10 +137,14 @@ export function createLcmExpandTool(input: {
       "Use this to drill into previously-compacted context when you need detail " +
       "that was summarised away. Provide either summaryIds (direct expansion) or " +
       "query (grep-first, then expand top matches). Returns a compact text payload " +
-      "with cited IDs for follow-up.",
+      "plus cited IDs in tool output for follow-up.",
     parameters: LcmExpandSchema,
     async execute(_toolCallId, params) {
-      const retrieval = input.lcm.getRetrieval();
+      const lcm = input.lcm ?? (await input.getLcm?.());
+      if (!lcm) {
+        throw new Error("LCM engine is unavailable.");
+      }
+      const retrieval = lcm.getRetrieval();
       const orchestrator = new ExpansionOrchestrator(retrieval);
       const runtimeAuthManager = getRuntimeExpansionAuthManager();
 
@@ -178,7 +183,7 @@ export function createLcmExpandTool(input: {
       }
 
       const conversationScope = await resolveLcmConversationScope({
-        lcm: input.lcm,
+        lcm,
         deps: input.deps,
         sessionId: input.sessionId,
         sessionKey: input.sessionKey,