@hicaru/pi-rlm 0.2.1 → 0.3.0

package/src/commands/rlm.ts

@@ -1,25 +1,8 @@
 /** `/rlm` — toggle persistent Recursive Language Model mode. */
 
-import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { Container, Text, type Component } from "@earendil-works/pi-tui";
-import { createPiInteractiveDeps } from "../bridge/pi-interactive.ts";
-import type { RlmController, RunHandle } from "../mode/rlm-mode.ts";
-import { postRlmGuide } from "../ui/intro.ts";
-import { clearRlmStatus, setRlmModeStatus } from "../ui/status.ts";
-import { listRunIds, readContextSidecar, readHeader, resolveRunId } from "../state/index.ts";
-import { DEFAULT_RUN_DIR } from "../config/defaults.ts";
-import { reconstructRlmState } from "../state/resume.ts";
-import type { ReconstructResult } from "../state/resume.ts";
-import type { RunHeader } from "../state/rows.ts";
-import { buildRlmSystemPrompt } from "../prompts/system.ts";
-import { RlmEmitter } from "../tool/rlm-events.ts";
-import { RlmEventAggregator } from "../tool/rlm-aggregator.ts";
-import type { RlmDetails } from "../tool/rlm-details.ts";
-import { cardHeader, cardStatsLine, renderCollapsedSubcallTree } from "../tool/subcall-render.ts";
-import { errorMessage } from "../util/errors.ts";
-
-/** Run ids offered for `/rlm-resume <TAB>`. */
-const MAX_COMPLETIONS = 20;
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { RlmController } from "../mode/rlm-mode.ts";
+import { setRlmModeStatus } from "../ui/status.ts";
 
 export function registerRlmCommand(pi: ExtensionAPI, controller: RlmController): void {
   pi.registerCommand("rlm", {
@@ -43,69 +26,6 @@ export function registerRlmCommand(pi: ExtensionAPI, controller: RlmController):
     },
   });
 
-  pi.registerCommand("rlm-help", {
-    description: "Show the RLM startup guide and command cheatsheet.",
-    handler: async () => {
-      postRlmGuide(pi, controller);
-    },
-  });
-
-  pi.registerCommand("rlm-resume", {
-    description: "Resume an interrupted RLM run (default @latest).",
-    getArgumentCompletions: async (prefix) => {
-      const dir = controller.config.runLog?.dir ?? DEFAULT_RUN_DIR;
-      const ids = await listRunIds(process.cwd(), dir);
-      const candidates = ["@latest", ...ids];
-      return candidates
-        .filter((value) => value.startsWith(prefix))
-        .slice(0, MAX_COMPLETIONS)
-        .map((value) => ({ value, label: value }));
-    },
-    handler: async (args, ctx) => {
-      if (controller.isBusy()) {
-        ctx.ui.notify("RLM is busy (use /rlm-stop to cancel).", "warning");
-        return;
-      }
-      const ref = args.trim() || "@latest";
-      const dir = controller.config.runLog?.dir ?? DEFAULT_RUN_DIR;
-      const cwd = ctx.cwd ?? process.cwd();
-      const runId = await resolveRunId(cwd, dir, ref);
-      if (!runId) { ctx.ui.notify(`No resumable RLM run for '${ref}'.`, "error"); return; }
-      const header = await readHeader(cwd, dir, runId);
-      if (!header) { ctx.ui.notify(`Run ${runId} has no header.`, "error"); return; }
-      const systemPrompt = buildRlmSystemPrompt(
-        { contextType: header.context.type, contextChars: header.context.chars, rootPrompt: header.rootPrompt },
-        {
-          orchestrator: header.meta.orchestrator,
-          recursion: 1 < header.meta.maxDepth,
-          askUserQuestion: controller.config.askUserQuestion,
-          todo: controller.config.todo,
-        },
-      );
-      let recon: ReconstructResult;
-      try { recon = await reconstructRlmState(cwd, dir, runId, systemPrompt); }
-      catch (e) {
-        ctx.ui.notify(`RLM resume failed: corrupt run state — ${errorMessage(e)}`, "error");
-        return;
-      }
-      if (!recon.ok) { ctx.ui.notify(`Cannot resume ${runId}: ${recon.reason}.`, "error"); return; }
-      if (recon.terminated) { ctx.ui.notify(`Run ${runId} already finished.`, "info"); return; }
-      const context = await readContextSidecar(cwd, dir, runId, header.context.json);
-      if (context === undefined) // R-C2: warn instead of silently resuming on empty context
-        ctx.ui.notify(`Warning: context sidecar missing for ${runId} — resuming without original context.`, "warning");
-      await executeRlmRunWithResume(pi, controller, ctx, recon, header, context ?? "");
-    },
-  });
-
-  pi.registerCommand("rlm-runs", {
-    description: "List recent RLM runs.",
-    handler: async (_args, ctx) => {
-      const dir = controller.config.runLog?.dir ?? DEFAULT_RUN_DIR;
-      const ids = (await listRunIds(ctx.cwd ?? process.cwd(), dir)).slice(0, 20);
-      ctx.ui.notify(ids.length ? ids.join("\n") : "No RLM runs recorded.", "info");
-    },
-  });
-
   pi.registerShortcut?.("ctrl+shift+r", {
     description: "Toggle RLM mode (off also stops a running query)",
     handler: async (ctx) => {
@@ -115,72 +35,3 @@ export function registerRlmCommand(pi: ExtensionAPI, controller: RlmController):
     },
   });
 }
-
-/** Above-editor progress card for a `/rlm-resume` run: header + the live sub-call tree. */
-function renderResumeWidget(details: RlmDetails | undefined, theme: Theme): Component {
-  const container = new Container();
-  if (!details) return container;
-  const turns = details.turns;
-  const stats = cardStatsLine(
-    details.totals,
-    theme,
-    turns.max > 0 ? `turn ${turns.current}/${turns.max}` : undefined,
-  );
-  container.addChild(new Text(cardHeader("RLM resume", details.status, stats, theme), 0, 0));
-  if (details.subcalls.length > 0) {
-    container.addChild(new Text(renderCollapsedSubcallTree(details.subcalls, theme), 0, 0));
-  }
-  return container;
-}
-
-async function executeRlmRunWithResume(
-  pi: ExtensionAPI,
-  controller: RlmController,
-  ctx: ExtensionContext,
-  recon: ReconstructResult & { ok: true },
-  header: RunHeader,
-  context: unknown,
-): Promise<void> {
-  let handle: RunHandle | undefined;
-  let emitter: RlmEmitter | undefined;
-  let aggregator: RlmEventAggregator | undefined;
-  try {
-    emitter = new RlmEmitter();
-    // Component factory rather than the string[] form: the array form is hard-capped at 10
-    // lines by pi, which the live sub-call tree exceeds as soon as a run fans out. The factory
-    // also receives the live theme, so the widget follows /theme switches.
-    let latest: RlmDetails | undefined;
-    aggregator = new RlmEventAggregator(emitter, (partial) => {
-      latest = partial.details;
-      if (!latest) return;
-      ctx.ui.setWidget?.("rlm-status", (_tui, theme) => renderResumeWidget(latest, theme), {
-        placement: "aboveEditor",
-      });
-    });
-    emitter.emitRootPrompt(header.rootPrompt);
-    const interactive = createPiInteractiveDeps(ctx);
-    if (controller.config.todo) {
-      for (const row of recon.todoRows) await interactive.onTodo?.(row.action, row.params);
-    }
-    handle = controller.start(ctx, { kind: "resume", resume: recon, context }, emitter, {
-      onAskUserQuestion: controller.config.askUserQuestion ? interactive.onAskUserQuestion : undefined,
-      onTodo: controller.config.todo ? interactive.onTodo : undefined,
-    });
-  } catch (e) {
-    ctx.ui.notify(`RLM resume failed: ${errorMessage(e)}`, "error");
-    return;
-  }
-  pi.sendMessage({ customType: "rlm-question", content: `[resume] ${header.rootPrompt}`, display: true });
-  const { done } = handle;
-  try {
-    const result = await done;
-    pi.sendMessage({ customType: "rlm-answer", content: result.answer, display: true });
-  } catch (e) {
-    ctx.ui.notify(`RLM resume failed: ${errorMessage(e)}`, "error");
-  } finally {
-    clearRlmStatus(ctx.ui);
-    ctx.ui.setWidget?.("rlm-status", undefined);
-    aggregator?.dispose();
-    emitter?.shutdown();
-  }
-}

package/src/config/defaults.ts

@@ -1,8 +1,4 @@
 import type { RlmConfig } from "../core/types.ts";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-export const DEFAULT_RUN_DIR = join(tmpdir(), "rlm-runs");
 
 /** Frozen default sub-LLM system prompt — avoids re-allocation on every llm_query call. */
 const DEFAULT_SUB_SYSTEM_PROMPT =
@@ -17,28 +13,22 @@ export const DEFAULT_CONFIG: Readonly<RlmConfig> = Object.freeze({
   execTimeoutS: 120,
   requestTimeoutMs: 10 * 60_000,
   // Session-wide, not per-batch: spawn() puts many requests on the wire at once, so this is
-  // the only thing bounding fan-out. Worst case is maxDepth × this many child engines (each
-  // owning a Python subprocess) plus this many leaf completions — keep it modest.
-  maxConcurrentSubcalls: 6,
+  // the only thing bounding leaf fan-out.
+  maxConcurrentSubcalls: 16,
+  // Children are bounded separately and lower: each is a Python subprocess holding its own copy
+  // of the context it inherited, where a leaf is one HTTP request. Worst case is
+  // (maxDepth - 1) × this many concurrent child engines.
+  maxConcurrentChildren: 6,
   maxPromptChars: 400_000,
   maxErrors: 5,
   orchestrator: true,
-  pipeline: false,
-  maxBackwardJumps: 2,
   compaction: true,
   compactionThresholdPct: 0.65,
   python: "python3",
   sandboxInitTimeoutMs: 30_000,
-  askUserQuestion: true,
-  todo: true,
-  libraryLoader: true,
+  contextLoader: true,
+  autoSeedCwd: true,
   rootSampling: Object.freeze({ maxTokens: 16_384 }),
   subSystemPrompt: DEFAULT_SUB_SYSTEM_PROMPT,
   subSampling: Object.freeze({ maxTokens: 8192 }),
-  runLog: Object.freeze({
-    enabled: true,
-    dir: DEFAULT_RUN_DIR,
-    snapshot: true,
-    maxRuns: 50,
-  }),
 });

package/src/config/settings.ts

@@ -1,15 +1,16 @@
-/** Persist RLM settings (tunable config + chosen worker model id). */
+/** Persist RLM settings (tunable config + pinned sub-LLM model id). */
 
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { getAgentDir, type ModelRegistry } from "@earendil-works/pi-coding-agent";
 import type { Api, Model, ThinkingLevel } from "@earendil-works/pi-ai";
-import type { RlmConfig, RunLogConfig } from "../core/types.ts";
+import type { RlmConfig } from "../core/types.ts";
 import { DEFAULT_CONFIG } from "./defaults.ts";
 
 export interface PersistedSettings {
   readonly config: Partial<RlmConfig>;
-  readonly worker?: string;
+  /** "provider/id" of the pinned sub-LLM, or undefined for "cheapest (auto)". */
+  readonly llm?: string;
 }
 
 type MutablePartialRlmConfig = { -readonly [K in keyof RlmConfig]?: RlmConfig[K] };
@@ -43,21 +44,6 @@ function validateThinkingLevel(v: unknown): ThinkingLevel | undefined {
   return typeof v === "string" && Object.hasOwn(THINKING_LEVELS, v) ? (v as ThinkingLevel) : undefined;
 }
 
-function validateRunLog(raw: unknown): Partial<RunLogConfig> | undefined {
-  if (typeof raw !== "object" || raw === null) return undefined;
-  const r = raw as Record<string, unknown>;
-  const out: { enabled?: boolean; dir?: string; snapshot?: boolean; maxRuns?: number } = {};
-  const enabled = validateBoolean(r.enabled);
-  if (enabled !== undefined) out.enabled = enabled;
-  const dir = validateString(r.dir);
-  if (dir !== undefined) out.dir = dir;
-  const snapshot = validateBoolean(r.snapshot);
-  if (snapshot !== undefined) out.snapshot = snapshot;
-  const maxRuns = validateNumber(r.maxRuns, 1);
-  if (maxRuns !== undefined) out.maxRuns = maxRuns;
-  return Object.keys(out).length > 0 ? Object.freeze(out) : undefined;
-}
-
 function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (typeof raw !== "object" || raw === null) return {};
   const r = raw as Record<string, unknown>;
@@ -74,10 +60,10 @@ function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (requestTimeoutMs !== undefined) out.requestTimeoutMs = requestTimeoutMs;
   const maxConcurrentSubcalls = validateNumber(r.maxConcurrentSubcalls, 1);
   if (maxConcurrentSubcalls !== undefined) out.maxConcurrentSubcalls = maxConcurrentSubcalls;
+  const maxConcurrentChildren = validateNumber(r.maxConcurrentChildren, 1);
+  if (maxConcurrentChildren !== undefined) out.maxConcurrentChildren = maxConcurrentChildren;
   const maxPromptChars = validateNumber(r.maxPromptChars, 1000);
   if (maxPromptChars !== undefined) out.maxPromptChars = maxPromptChars;
-  const maxBudgetUsd = validateNumber(r.maxBudgetUsd, 0.01);
-  if (maxBudgetUsd !== undefined) out.maxBudgetUsd = maxBudgetUsd;
   const maxTimeoutMs = validateNumber(r.maxTimeoutMs, 1000);
   if (maxTimeoutMs !== undefined) out.maxTimeoutMs = maxTimeoutMs;
   const maxTokens = validateNumber(r.maxTokens, 1);
@@ -86,10 +72,6 @@ function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (maxErrors !== undefined) out.maxErrors = maxErrors;
   const orchestrator = validateBoolean(r.orchestrator);
   if (orchestrator !== undefined) out.orchestrator = orchestrator;
-  const pipeline = validateBoolean(r.pipeline);
-  if (pipeline !== undefined) out.pipeline = pipeline;
-  const maxBackwardJumps = validateNumber(r.maxBackwardJumps, 0);
-  if (maxBackwardJumps !== undefined) out.maxBackwardJumps = maxBackwardJumps;
   const compaction = validateBoolean(r.compaction);
   if (compaction !== undefined) out.compaction = compaction;
   const compactionThresholdPct = validateNumber(r.compactionThresholdPct, 0);
@@ -100,16 +82,13 @@ function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (smartReasoning !== undefined) out.smartReasoning = smartReasoning;
   const subSystemPrompt = validateString(r.subSystemPrompt);
   if (subSystemPrompt !== undefined) out.subSystemPrompt = subSystemPrompt;
-  const runLog = validateRunLog(r.runLog);
-  if (runLog) out.runLog = runLog;
   const sandboxInitTimeoutMs = validateNumber(r.sandboxInitTimeoutMs, 100);
   if (sandboxInitTimeoutMs !== undefined) out.sandboxInitTimeoutMs = sandboxInitTimeoutMs;
-  const askUserQuestion = validateBoolean(r.askUserQuestion);
-  if (askUserQuestion !== undefined) out.askUserQuestion = askUserQuestion;
-  const todo = validateBoolean(r.todo);
-  if (todo !== undefined) out.todo = todo;
-  const libraryLoader = validateBoolean(r.libraryLoader);
-  if (libraryLoader !== undefined) out.libraryLoader = libraryLoader;
+  // `libraryLoader` is the pre-rename key — still read so an existing rlm.json survives the upgrade.
+  const contextLoader = validateBoolean(r.contextLoader) ?? validateBoolean(r.libraryLoader);
+  if (contextLoader !== undefined) out.contextLoader = contextLoader;
+  const autoSeedCwd = validateBoolean(r.autoSeedCwd);
+  if (autoSeedCwd !== undefined) out.autoSeedCwd = autoSeedCwd;
   if (typeof r.subSampling === "object" && r.subSampling !== null) {
     const ss = r.subSampling as Record<string, unknown>;
     const sampling: { maxTokens?: number; temperature?: number; reasoning?: ThinkingLevel } = {};
@@ -142,7 +121,8 @@ export async function loadSettings(): Promise<PersistedSettings> {
     const r = raw as Record<string, unknown>;
     return {
       config: validateConfig(r.config),
-      worker: typeof r.worker === "string" ? r.worker : undefined,
+      // `worker` is the pre-rename key — still read so an existing pin survives the upgrade.
+      llm: validateString(r.llm) ?? validateString(r.worker),
     };
   } catch {
     return { config: {} };
@@ -167,7 +147,6 @@ export function mergeConfig(partial: Partial<RlmConfig>): RlmConfig {
     ...partial,
     subSampling: { ...DEFAULT_CONFIG.subSampling, ...partial.subSampling },
     rootSampling: Object.freeze({ ...DEFAULT_CONFIG.rootSampling, ...partial.rootSampling }),
-    ...(partial.runLog ? { runLog: Object.freeze({ ...DEFAULT_CONFIG.runLog, ...partial.runLog }) } : {}),
   };
 }
 

package/src/context/anydoc.ts

@@ -0,0 +1,67 @@
+/**
+ * Lazy NAPI handle for @firecrawl/anydoc.
+ *
+ * anydoc is a native addon with per-platform optionalDependencies (darwin x64/arm64,
+ * linux x64/arm64 gnu+musl, win32 x64 — NO win32-arm64). A static `import` on an uncovered
+ * platform is a plugin-load crash. So: import() once, memoised, catch → null. Absence is a
+ * value; documents degrade to skipped: "no-converter".
+ */
+
+/** Minimal surface we consume — never re-export the full anydoc package. */
+export interface AnydocHandle {
+  /** Detect document format from a path's extension; null for plain text / unknown. */
+  readonly formatFromPath: (path: string) => string | null;
+  /** Convert a document file to Markdown. Rejects with Error.code = ConvertErrorCode. */
+  readonly toMarkdown: (path: string) => Promise<string>;
+}
+
+/**
+ * Document container extensions anydoc knows about, including Office macro/variants.
+ * Used when the native addon is absent so we still route these to "no-converter"
+ * instead of reading them as broken binary text.
+ */
+const DOCUMENT_EXTENSIONS: ReadonlySet<string> = Object.freeze(new Set([
+  "doc", "docx", "docm", "odt", "rtf", "epub", "pdf",
+  "ppt", "pptx", "pptm", "ppsx", "odp",
+  "xls", "xlsx", "xlsm", "xlsb", "ods", "csv",
+]));
+
+/**
+ * Detect a document container from a path when the anydoc handle is unavailable.
+ * Returns a non-null token for known extensions so the router can skip as "no-converter".
+ */
+export function documentExtFromPath(path: string): string | null {
+  const base = path.includes("/") ? path.slice(path.lastIndexOf("/") + 1) : path;
+  const dot = base.lastIndexOf(".");
+  if (dot < 0) return null;
+  const ext = base.slice(dot + 1).toLowerCase();
+  return DOCUMENT_EXTENSIONS.has(ext) ? ext : null;
+}
+
+let cached: Promise<AnydocHandle | null> | undefined;
+
+/**
+ * Resolve the anydoc handle once per process. Returns null when the native addon is
+ * missing or fails to load — callers treat documents as skipped: "no-converter".
+ */
+export function getAnydoc(): Promise<AnydocHandle | null> {
+  cached ??= import("@firecrawl/anydoc")
+    .then((mod): AnydocHandle => Object.freeze({
+      formatFromPath: (p: string) => mod.formatFromPath(p),
+      toMarkdown: (p: string) => mod.toMarkdown(p),
+    }))
+    .catch(() => null);
+  return cached;
+}
+
+/**
+ * Test seam: force the next getAnydoc() call to return a fixed handle (or null).
+ * Pass `undefined` to restore the real lazy loader.
+ */
+export function setAnydocForTest(handle: AnydocHandle | null | undefined): void {
+  if (handle === undefined) {
+    cached = undefined;
+    return;
+  }
+  cached = Promise.resolve(handle);
+}

package/src/context/listing.ts

@@ -0,0 +1,70 @@
+/**
+ * Compact human-readable listing of currently loaded context files for the parent LLM.
+ * Shows paths and token estimates — NOT full file contents.
+ */
+
+import type { ContextFile } from "./types.ts";
+import { isContextFile } from "./namespace.ts";
+
+/** Maximum files shown in the compact LLM listing before truncation. */
+const MAX_LLM_LISTING_FILES = 200;
+
+/**
+ * Format a context payload (ContextFile[] or empty) for injection into the parent agent's
+ * message stream. Empty state points at autoSeedCwd / external add_context — never
+ * `add_context(".")`, which would re-pack the already-seeded cwd under a ctx/ prefix.
+ */
+export function formatContextListing(context: unknown): string {
+  const files = toFileList(context);
+  if (files.length === 0) {
+    return [
+      "RLM `context` is EMPTY — no files loaded yet.",
+      "The working directory seeds automatically on the first `repl()` call (autoSeedCwd).",
+      'Use `add_context("/path/to/dir")` / `add_context("docs.pdf")` / `add_context("https://…")` for external sources.',
+      "Documents (PDF, DOCX, XLSX, PPTX, CSV, …) are converted to Markdown on the way in.",
+      "",
+      "Use repl({code}) and delegate semantic reading to llm_query / llm_query_batched / llm_query_chunked.",
+    ].join("\n");
+  }
+
+  let totalTokens = 0;
+  let totalChars = 0;
+  for (let i = 0; i < files.length; i++) {
+    totalTokens += files[i].tokens;
+    totalChars += files[i].content.length;
+  }
+
+  const shown = files.slice(0, MAX_LLM_LISTING_FILES);
+  const truncated = files.length > MAX_LLM_LISTING_FILES
+    ? `... and ${files.length - MAX_LLM_LISTING_FILES} more files (truncated)`
+    : "";
+
+  const listingParts = new Array<string>(shown.length);
+  for (let i = 0; i < shown.length; i++) {
+    const f = shown[i];
+    listingParts[i] =
+      `${f.path} (${f.tokens.toLocaleString()} tok, ${f.content.length.toLocaleString()} chars)`;
+  }
+
+  return [
+    `Context: ${files.length.toLocaleString()} files, ${totalTokens.toLocaleString()} estimated tokens, ${totalChars.toLocaleString()} total characters.`,
+    "",
+    listingParts.join("\n"),
+    truncated,
+    "",
+    "File contents are loaded in the REPL `context` variable — file-reading tools are disabled.",
+    "Use repl({code}) and delegate semantic reading to llm_query / llm_query_batched / llm_query_chunked.",
+  ].join("\n");
+}
+
+function toFileList(context: unknown): readonly ContextFile[] {
+  if (!Array.isArray(context)) return Object.freeze([]);
+  const out = new Array<ContextFile>(context.length);
+  let n = 0;
+  for (let i = 0; i < context.length; i++) {
+    const entry: unknown = context[i];
+    if (isContextFile(entry)) out[n++] = entry;
+  }
+  out.length = n;
+  return out;
+}

package/src/context/md-cache.ts

@@ -0,0 +1,112 @@
+/**
+ * On-disk Markdown cache for anydoc conversions, keyed by (size, mtimeMs).
+ *
+ * Cache dir: $XDG_CACHE_HOME/pi-rlm/anydoc (else ~/.cache/…).
+ * Per source: <name>-<sha8(absPath)>.md + .json stamp {source, size, mtimeMs}.
+ *
+ * The stamp is ALWAYS the pre-conversion (size, mtimeMs). Capturing after toMarkdown races
+ * with mid-conversion edits and would stamp the new mtime against the old body — every future
+ * read would be a permanent stale hit. writeMdCache also refuses to write when a post-conversion
+ * stat disagrees with the captured stamp.
+ *
+ * Write ordering is load-bearing: Markdown body first, stamp second. A crash between them
+ * leaves stale-body-no-stamp, which reads as a miss. All cache failures are swallowed —
+ * the cache is an optimisation, never a dependency.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { homedir } from "node:os";
+
+export interface FileStamp {
+  readonly size: number;
+  readonly mtimeMs: number;
+}
+
+interface CacheStamp {
+  readonly source: string;
+  readonly size: number;
+  readonly mtimeMs: number;
+}
+
+function cacheRoot(): string {
+  const xdg = process.env.XDG_CACHE_HOME;
+  if (typeof xdg === "string" && xdg.trim() !== "") return join(xdg, "pi-rlm", "anydoc");
+  return join(homedir(), ".cache", "pi-rlm", "anydoc");
+}
+
+function entryBase(absPath: string): string {
+  const name = basename(absPath).replace(/[^\w.-]+/g, "-").slice(0, 80) || "doc";
+  const sha8 = createHash("sha256").update(absPath).digest("hex").slice(0, 8);
+  return `${name}-${sha8}`;
+}
+
+function isStamp(value: unknown): value is CacheStamp {
+  if (value === null || typeof value !== "object") return false;
+  const r = value as Record<string, unknown>;
+  return typeof r.source === "string"
+    && typeof r.size === "number"
+    && typeof r.mtimeMs === "number";
+}
+
+/** Capture (size, mtimeMs) for a source file. Returns undefined on I/O failure. */
+export async function captureStamp(absPath: string): Promise<FileStamp | undefined> {
+  try {
+    const s = await stat(absPath);
+    return Object.freeze({ size: s.size, mtimeMs: s.mtimeMs });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read a cached Markdown body if the stamp still matches a fresh stat of `absPath`.
+ * Returns undefined on any miss or I/O failure.
+ */
+export async function readMdCache(absPath: string): Promise<string | undefined> {
+  try {
+    const base = join(cacheRoot(), entryBase(absPath));
+    const stampRaw = await readFile(`${base}.json`, "utf-8");
+    const stamp: unknown = JSON.parse(stampRaw);
+    if (!isStamp(stamp)) return undefined;
+    const s = await stat(absPath);
+    if (s.size !== stamp.size || s.mtimeMs !== stamp.mtimeMs) return undefined;
+    return await readFile(`${base}.md`, "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Write Markdown body then the PRE-CAPTURED stamp. Failures are swallowed.
+ *
+ * If a post-conversion stat disagrees with `stamp`, the write is skipped (file changed
+ * mid-conversion — stamping the new mtime against the old body would freeze stale content).
+ * Body-before-stamp is load-bearing (see module docstring).
+ */
+export async function writeMdCache(
+  absPath: string,
+  markdown: string,
+  stamp: FileStamp,
+): Promise<void> {
+  try {
+    // Refuse to cache if the source moved under us during conversion.
+    const s = await stat(absPath);
+    if (s.size !== stamp.size || s.mtimeMs !== stamp.mtimeMs) return;
+
+    const root = cacheRoot();
+    await mkdir(root, { recursive: true });
+    const base = join(root, entryBase(absPath));
+    // Body first, stamp second — crash between leaves a miss, never a wrong hit.
+    await writeFile(`${base}.md`, markdown, "utf-8");
+    const out: CacheStamp = Object.freeze({
+      source: absPath,
+      size: stamp.size,
+      mtimeMs: stamp.mtimeMs,
+    });
+    await writeFile(`${base}.json`, `${JSON.stringify(out)}\n`, "utf-8");
+  } catch {
+    // optimisation only
+  }
+}

package/src/context/merge.ts

@@ -0,0 +1,97 @@
+/**
+ * Merge / filter helpers for the live context list.
+ *
+ * Lifted from the old library-context module with `lib/` → `ctx/` and the empty-prefix
+ * short-circuit for cwd sources.
+ */
+
+import { estimateTokens } from "../text/tokens.ts";
+import {
+  contextEntryPath,
+  isContextFile,
+  namespaceContextFiles,
+  payloadPrefix,
+} from "./namespace.ts";
+import type { ContextFile } from "./types.ts";
+
+export interface FilteredContext {
+  readonly files: readonly ContextFile[];
+  /** Prefixes that selected zero files — the caller decides whether that is fatal. */
+  readonly unmatched: readonly string[];
+}
+
+/**
+ * Narrow a context payload to entries under any of `prefixes` (plain prefix match, no globs).
+ *
+ * Backs `rlm_query(prompt, paths=[…])`. Prefix-only is deliberate: the sandbox's own filters use
+ * Python `fnmatch`, which has no host-side equivalent here, and a subtree prefix is what callers
+ * actually want — the child can still `search()` inside the slice.
+ */
+export function filterContextByPaths(context: unknown, prefixes: readonly string[]): FilteredContext {
+  if (!Array.isArray(context) || prefixes.length === 0) {
+    return Object.freeze({ files: Object.freeze([]), unmatched: Object.freeze(Array.from(prefixes)) });
+  }
+  const hit = new Array<boolean>(prefixes.length).fill(false);
+  const out = new Array<ContextFile>(context.length); // pre-allocated, trimmed once below
+  let n = 0;
+  for (let i = 0; i < context.length; i++) {
+    const entry: unknown = context[i];
+    if (!isContextFile(entry)) continue;
+    for (let p = 0; p < prefixes.length; p++) {
+      if (!entry.path.startsWith(prefixes[p])) continue;
+      hit[p] = true;
+      out[n++] = entry;
+      break;
+    }
+  }
+  out.length = n;
+  const unmatched = new Array<string>(prefixes.length); // pre-allocated, no .push()
+  let u = 0;
+  for (let p = 0; p < prefixes.length; p++) {
+    if (!hit[p]) unmatched[u++] = prefixes[p];
+  }
+  unmatched.length = u;
+  return Object.freeze({ files: Object.freeze(out), unmatched: Object.freeze(unmatched) });
+}
+
+/**
+ * Append a source payload into an existing list context.
+ * Skips a payload whose `ctx/<id>/` prefix is already present, so a repeat load is a no-op.
+ *
+ * Cwd-seeded (un-prefixed) files never carry a `ctx/<id>/` prefix, so `payloadPrefix` returns
+ * undefined for them and this path-scan does not fire. Idempotency for the cwd seed is owned
+ * by the host `loaded` set (sentinel `""`) and the seeded-cwd absolute-path short-circuit in
+ * bridge/add-context.ts — not by this merge.
+ */
+export function mergeIntoContext(base: unknown, sourcePayload: unknown): unknown {
+  if (!Array.isArray(base)) return base;
+  if (Array.isArray(sourcePayload)) {
+    if (sourcePayload.length === 0) return base;
+    const prefix = payloadPrefix(sourcePayload);
+    // Only `ctx/<id>/` prefixes participate in path-scan dedup (payloadPrefix never returns "").
+    if (prefix !== undefined) {
+      for (let i = 0; i < base.length; i++) {
+        const path = contextEntryPath(base[i]);
+        if (path !== undefined && path.startsWith(prefix)) return base; // already present
+      }
+    }
+    const merged = new Array<unknown>(base.length + sourcePayload.length);
+    for (let i = 0; i < base.length; i++) merged[i] = base[i];
+    for (let i = 0; i < sourcePayload.length; i++) merged[base.length + i] = sourcePayload[i];
+    return merged;
+  }
+  if (typeof sourcePayload === "string") {
+    // Raw string payload: wrap once under the unknown prefix.
+    return mergeIntoContext(base, namespaceContextFiles(sourcePayload, "unknown"));
+  }
+  return base;
+}
+
+/** Build a frozen ContextFile from path + content (shared by every source-* producer). */
+export function makeContextFile(path: string, content: string): ContextFile {
+  return Object.freeze({
+    path,
+    content,
+    tokens: Math.max(1, estimateTokens(content.length)),
+  });
+}