@hicaru/pi-rlm 0.1.7 → 0.1.8

package/src/core/gates.ts

@@ -0,0 +1,272 @@
+/**
+ * Deterministic gate floors for the RLM pipeline: the engine measures artifacts
+ * instead of trusting the model's claim that a phase is complete.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import type { Result } from "../util/errors.ts";
+
+/** Gate outcome — same shape as Result; alias keeps call sites domain-clear. */
+export type GateResult<T> = Result<T, string>;
+
+export const MAX_PHASES = 32;
+
+/** One parsed entry of a plan's `phases:` frontmatter array. */
+export interface PhaseRecord {
+  readonly n: number;
+  readonly title: string;
+  readonly index: number;
+  readonly total: number;
+}
+
+export interface PlanGateData {
+  readonly phases: readonly PhaseRecord[];
+}
+
+export interface ValidationGateData {
+  readonly blockersCount: number;
+  readonly verdict: "pass" | "fail";
+}
+
+export interface ClarificationGateData {
+  readonly decisionsCount: number;
+  readonly openQuestionsCount: number;
+}
+
+const PLAN_PHASE_RE = /^## Phase (\d+):/;
+const STATUS_READY = "ready";
+const BULLET_RE = /^-\s+\S/;
+
+/**
+ * Walk content lines, invoking `visit` only for lines outside fenced code blocks.
+ * Shared by heading and bullet counters (DRY — single fence scan).
+ */
+export function forEachLineOutsideFences(
+  content: string,
+  visit: (line: string) => void,
+): void {
+  let inFence = false;
+  let fenceLen = 0;
+  for (const line of content.split("\n")) {
+    const fence = /^\s*(`{3,}|~{3,})/.exec(line);
+    if (fence) {
+      const len = (fence[1] ?? "").length;
+      if (!inFence) {
+        inFence = true;
+        fenceLen = len;
+      } else if (len >= fenceLen && line.trim().length === len) {
+        inFence = false;
+        fenceLen = 0;
+      }
+      continue;
+    }
+    if (!inFence) visit(line);
+  }
+}
+
+/**
+ * Count lines matching `re` OUTSIDE fenced code blocks — a `## Phase N:` inside
+ * a ``` fence is example text, not a structural heading.
+ */
+export function countHeadingsOutsideFences(content: string, re: RegExp): number {
+  const lineRe = new RegExp(re.source);
+  let count = 0;
+  forEachLineOutsideFences(content, (line) => {
+    if (lineRe.test(line)) count++;
+  });
+  return count;
+}
+
+/**
+ * Fence-aware count of top-level (column-0) `- ` bullets under a `## <heading>` section.
+ * Nested/indented sub-bullets are ignored. The next `## ` heading ends the section.
+ * Missing heading ⇒ 0.
+ */
+export function countBulletsUnderHeading(content: string, heading: string): number {
+  const headingRe = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`);
+  let inSection = false;
+  let count = 0;
+  forEachLineOutsideFences(content, (line) => {
+    if (/^##\s+/.test(line)) {
+      inSection = headingRe.test(line);
+      return;
+    }
+    // Column-0 only: do not trimStart — indented sub-bullets must not inflate the count.
+    if (inSection && BULLET_RE.test(line)) count++;
+  });
+  return count;
+}
+
+/**
+ * True when `## <heading>` exists and has non-whitespace body before the next `## `.
+ * Only the first matching heading is considered (later duplicates are ignored).
+ */
+export function sectionHasNonEmptyBody(content: string, heading: string): boolean {
+  const headingRe = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`);
+  let inSection = false;
+  let seen = false; // first match wins — do not re-enter on a later duplicate heading
+  let body = "";
+  forEachLineOutsideFences(content, (line) => {
+    if (/^##\s+/.test(line)) {
+      if (inSection) {
+        inSection = false;
+        return;
+      }
+      if (!seen && headingRe.test(line)) {
+        inSection = true;
+        seen = true;
+      }
+      return;
+    }
+    if (inSection) body += `${line}\n`;
+  });
+  return body.trim().length > 0;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Frontmatter as a plain record (parseFrontmatter returns unknown-shaped data). */
+function frontmatterOf(content: string): Record<string, unknown> {
+  const { frontmatter } = parseFrontmatter(content);
+  return typeof frontmatter === "object" && frontmatter !== null
+    ? (frontmatter as Record<string, unknown>)
+    : {};
+}
+
+/** `status: ready` floor — shared by every produces-stage gate. */
+export function checkStatusReady(content: string, path: string): GateResult<undefined> {
+  const status = frontmatterOf(content).status;
+  return status === STATUS_READY
+    ? { ok: true, value: undefined }
+    : { ok: false, error: `artifact ${path} has status '${String(status)}' — set frontmatter status: ready before advancing` };
+}
+
+/**
+ * Plan-structure floor:
+ * `phases:` array ≡ fence-aware `## Phase N:` heading count, `phase_count` ≡
+ * array length, count within [1, MAX_PHASES]. Stale array ⇒ reject, so the
+ * fanout never dispatches a wrong unit list.
+ */
+export function planPhaseRecords(content: string, path: string): GateResult<PlanGateData> {
+  const fm = frontmatterOf(content);
+  const raw = fm.phases;
+  const phases = Array.isArray(raw) ? raw : [];
+  const headingCount = countHeadingsOutsideFences(content, PLAN_PHASE_RE);
+  if (phases.length !== headingCount) {
+    return { ok: false, error: `plan ${path}: frontmatter phases (${phases.length}) ≠ '## Phase N:' headings (${headingCount}) — rebuild the phases: array from the body headings` };
+  }
+  if (fm.phase_count !== phases.length) {
+    return { ok: false, error: `plan ${path}: phase_count (${String(fm.phase_count)}) ≠ phases length (${phases.length}) — rebuild phase_count` };
+  }
+  if (phases.length === 0) {
+    return { ok: false, error: `plan ${path}: declares no '## Phase N:' sections — a plan needs at least one phase` };
+  }
+  if (phases.length > MAX_PHASES) {
+    return { ok: false, error: `plan ${path}: ${phases.length} phases exceeds MAX_PHASES (${MAX_PHASES}) — split the plan` };
+  }
+  const records = new Array<PhaseRecord>(phases.length);
+  for (let index = 0; index < phases.length; index++) {
+    const entry = phases[index];
+    const e = typeof entry === "object" && entry !== null ? (entry as Record<string, unknown>) : {};
+    records[index] = {
+      n: typeof e.n === "number" ? e.n : index + 1,
+      title: typeof e.title === "string" ? e.title : "",
+      index,
+      total: phases.length,
+    };
+  }
+  return { ok: true, value: { phases: records } };
+}
+
+/**
+ * Citation floor (direct path resolution only): every `path/file.ext:NN[-MM]`
+ * in the artifact body must name a real file with at least NN lines. Unbacked
+ * citations are fabricated precision — reject before they mislead implement.
+ */
+const FILE_LINE_CITATION_RE =
+  /((?:(?<![\w.])\.)?(?<!\w)[\w][\w./-]*\.[a-zA-Z][a-zA-Z0-9]{0,4}):(\d+)(?:-(\d+))?/g;
+
+export function verifyCitations(body: string, cwd: string): GateResult<undefined> {
+  const errors: string[] = [];
+  const seen = new Set<string>();
+  for (const m of body.matchAll(FILE_LINE_CITATION_RE)) {
+    const path = m[1];
+    const startStr = m[2];
+    const endStr = m[3];
+    if (path === undefined || startStr === undefined) continue;
+    const key = `${path}:${startStr}${endStr !== undefined ? `-${endStr}` : ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const abs = isAbsolute(path) ? path : join(cwd, path);
+    if (!existsSync(abs) || !statSync(abs).isFile()) {
+      errors.push(`unbacked citation ${key} — file does not exist (use a repo-root-relative path or drop the line numbers)`);
+      continue;
+    }
+    let lineCount: number;
+    try {
+      lineCount = readFileSync(abs, "utf-8").split("\n").length;
+    } catch {
+      errors.push(`unbacked citation ${key} — file could not be read`);
+      continue;
+    }
+    const high = Math.max(Number(startStr), endStr !== undefined ? Number(endStr) : 0);
+    if (high > lineCount) {
+      errors.push(`unbacked citation ${key} — file has ${lineCount} lines; correct the range or drop the line numbers`);
+    }
+  }
+  return errors.length === 0
+    ? { ok: true, value: undefined }
+    : { ok: false, error: errors.slice(0, 10).join("\n") };
+}
+
+/**
+ * Validation-contract floor: the validate artifact must carry the numeric gate
+ * field (`blockers_count`) so routing is measured, never inferred from prose.
+ */
+export function validationRecord(content: string, path: string): GateResult<ValidationGateData> {
+  const fm = frontmatterOf(content);
+  const blockers = fm.blockers_count;
+  const verdict = fm.verdict;
+  if (typeof blockers !== "number" || !Number.isInteger(blockers) || blockers < 0) {
+    return { ok: false, error: `validation ${path}: frontmatter blockers_count must be an integer ≥ 0 (got ${String(blockers)})` };
+  }
+  if (verdict !== "pass" && verdict !== "fail") {
+    return { ok: false, error: `validation ${path}: frontmatter verdict must be 'pass' or 'fail' (got ${String(verdict)})` };
+  }
+  if (verdict === "pass" && blockers > 0) {
+    return { ok: false, error: `validation ${path}: verdict 'pass' contradicts blockers_count ${blockers}` };
+  }
+  return { ok: true, value: { blockersCount: blockers, verdict } };
+}
+
+/**
+ * Clarification-contract floor: interview outcome document.
+ * `decisions_count` / `open_questions_count` must match fence-aware bullet counts;
+ * `## Problem & Intent` must be present and non-empty (user's words).
+ */
+export function clarificationRecord(content: string, path: string): GateResult<ClarificationGateData> {
+  const fm = frontmatterOf(content);
+  const decisions = fm.decisions_count;
+  const openQs = fm.open_questions_count;
+  if (typeof decisions !== "number" || !Number.isInteger(decisions) || decisions < 0) {
+    return { ok: false, error: `clarification ${path}: frontmatter decisions_count must be an integer ≥ 0 (got ${String(decisions)})` };
+  }
+  if (typeof openQs !== "number" || !Number.isInteger(openQs) || openQs < 0) {
+    return { ok: false, error: `clarification ${path}: frontmatter open_questions_count must be an integer ≥ 0 (got ${String(openQs)})` };
+  }
+  if (!sectionHasNonEmptyBody(content, "Problem & Intent")) {
+    return { ok: false, error: `clarification ${path}: '## Problem & Intent' section is missing or empty — record the user's words verbatim` };
+  }
+  const decisionBullets = countBulletsUnderHeading(content, "Decisions");
+  if (decisions !== decisionBullets) {
+    return { ok: false, error: `clarification ${path}: decisions_count (${decisions}) ≠ '- ' bullets under '## Decisions' (${decisionBullets}) — rebuild the count from the body` };
+  }
+  const openBullets = countBulletsUnderHeading(content, "Open Questions");
+  if (openQs !== openBullets) {
+    return { ok: false, error: `clarification ${path}: open_questions_count (${openQs}) ≠ '- ' bullets under '## Open Questions' (${openBullets}) — rebuild the count from the body` };
+  }
+  return { ok: true, value: { decisionsCount: decisions, openQuestionsCount: openQs } };
+}

package/src/core/iteration.ts

@@ -6,7 +6,7 @@
 
 import type { Api, Model, Usage } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { type ChatMsg, modelComplete } from "../bridge/model.ts";
+import { type ChatMsg, type CompleteOptions, type CompleteResult, modelComplete } from "../bridge/model.ts";
 import type { ReplResult } from "../sandbox/protocol.ts";
 import type { PythonSandbox } from "../sandbox/sandbox.ts";
 import { findReplBlocks } from "../text/parsing.ts";
@@ -21,15 +21,20 @@ export interface Turn {
   readonly skippedBlocks: number;
 }
 
+export type CompleteFn = (messages: readonly ChatMsg[], opts: CompleteOptions) => Promise<CompleteResult>;
+
 export interface TurnDeps {
   readonly model: Model<Api>;
   readonly registry: ModelRegistry;
   readonly sampling?: Sampling;
   readonly signal?: AbortSignal;
+  /** Test-only override for model completion (scripted responses). */
+  readonly complete?: CompleteFn;
 }
 
 export async function runTurn(history: readonly ChatMsg[], sandbox: PythonSandbox, deps: TurnDeps): Promise<Turn> {
-  const { text, usage } = await modelComplete(history, {
+  const complete = deps.complete ?? modelComplete;
+  const { text, usage } = await complete(history, {
     model: deps.model,
     registry: deps.registry,
     maxTokens: deps.sampling?.maxTokens,

package/src/core/pipeline.ts

@@ -1,25 +1,165 @@
 /**
- * RLM pipeline phase state machine.
+ * RLM pipeline stage graph — data-driven transitions with deterministic gates.
  *
- * Hard-gated phases: research → blueprint → implement → validate.
- * The root RLM calls advance_phase() to move forward; the engine enforces
- * forward-only progression, persists phase rows, and re-prompts when a
- * phase stalls for too many turns.
+ * Stages: clarify → research → blueprint → implement → validate
+ * (clarify skipped when askUserQuestion is off).
+ * The root RLM writes artifacts via save_artifact(); advance_phase() is gated by
+ * TypeScript floors (never LLM judgment). Validate routes on measured
+ * blockers_count with a bounded corrective loop back to blueprint.
  */
+import {
+  checkStatusReady,
+  clarificationRecord,
+  type ClarificationGateData,
+  type GateResult,
+  planPhaseRecords,
+  type PlanGateData,
+  type ValidationGateData,
+  validationRecord,
+  verifyCitations,
+} from "./gates.ts";
 
-export type Phase = "research" | "blueprint" | "implement" | "validate";
+export type Phase = "clarify" | "research" | "blueprint" | "implement" | "validate";
 
 export const PHASES = Object.freeze([
+  "clarify",
   "research",
   "blueprint",
   "implement",
   "validate",
 ] as const satisfies readonly Phase[]);
 
+/** Kind string the model passes to save_artifact(kind, content). */
+export type ArtifactKind = "clarification" | "research" | "plan" | "validation";
+
+/** Structured data a stage gate extracts from its artifact (what edges route on). */
+export type StageGateData =
+  | { readonly kind: "clarification"; readonly clarification: ClarificationGateData }
+  | { readonly kind: "research" }
+  | { readonly kind: "plan"; readonly plan: PlanGateData }
+  | { readonly kind: "validation"; readonly validation: ValidationGateData }
+  | { readonly kind: "side-effect" };
+
+export interface StageDef {
+  readonly phase: Phase;
+  /** Subdir under .rlm/artifacts/ ("" = side-effect stage, no artifact). */
+  readonly artifactDir: string;
+  /** save_artifact kind, or "" when the stage produces no artifact. */
+  readonly artifactKind: ArtifactKind | "";
+  /** Deterministic floor run on the artifact BEFORE leaving this stage. */
+  readonly gate: (content: string, path: string, cwd: string) => GateResult<StageGateData>;
+}
+
+const clarifyGate: StageDef["gate"] = (content, path) => {
+  const status = checkStatusReady(content, path);
+  if (!status.ok) return status;
+  const rec = clarificationRecord(content, path);
+  if (!rec.ok) return rec;
+  return { ok: true, value: { kind: "clarification", clarification: rec.value } };
+};
+
+/** Compose floors: status: ready → citations → stage-specific contract. */
+const researchGate: StageDef["gate"] = (content, path, cwd) => {
+  const status = checkStatusReady(content, path);
+  if (!status.ok) return status;
+  const cites = verifyCitations(content, cwd);
+  if (!cites.ok) return cites;
+  return { ok: true, value: { kind: "research" } };
+};
+
+const blueprintGate: StageDef["gate"] = (content, path, cwd) => {
+  const status = checkStatusReady(content, path);
+  if (!status.ok) return status;
+  const cites = verifyCitations(content, cwd);
+  if (!cites.ok) return cites;
+  const plan = planPhaseRecords(content, path);
+  if (!plan.ok) return plan;
+  return { ok: true, value: { kind: "plan", plan: plan.value } };
+};
+
+const validateGate: StageDef["gate"] = (content, path) => {
+  const status = checkStatusReady(content, path);
+  if (!status.ok) return status;
+  const rec = validationRecord(content, path);
+  if (!rec.ok) return rec;
+  return { ok: true, value: { kind: "validation", validation: rec.value } };
+};
+
+/** Single source of truth for gates, artifact dirs/kinds, and routing. */
+export const STAGES: Readonly<Record<Phase, StageDef>> = Object.freeze({
+  clarify: { phase: "clarify", artifactDir: "clarifications", artifactKind: "clarification", gate: clarifyGate },
+  research: { phase: "research", artifactDir: "research", artifactKind: "research", gate: researchGate },
+  blueprint: { phase: "blueprint", artifactDir: "plans", artifactKind: "plan", gate: blueprintGate },
+  // implement is a side-effect stage; exit is engine-driven (serial fanout).
+  implement: {
+    phase: "implement",
+    artifactDir: "",
+    artifactKind: "",
+    gate: (): GateResult<StageGateData> => ({ ok: true, value: { kind: "side-effect" } }),
+  },
+  validate: { phase: "validate", artifactDir: "validations", artifactKind: "validation", gate: validateGate },
+});
+
+/** Lookup stage by save_artifact kind — single map derived from STAGES (DRY). */
+const STAGE_BY_KIND: Readonly<Partial<Record<ArtifactKind, StageDef>>> = Object.freeze(
+  (Object.values(STAGES) as readonly StageDef[]).reduce<Partial<Record<ArtifactKind, StageDef>>>((acc, stage) => {
+    if (stage.artifactKind !== "") acc[stage.artifactKind] = stage;
+    return acc;
+  }, {}),
+);
+
+export function stageForArtifactKind(kind: string): StageDef | undefined {
+  if (kind === "clarification" || kind === "research" || kind === "plan" || kind === "validation") {
+    return STAGE_BY_KIND[kind];
+  }
+  return undefined;
+}
+
 export interface PhaseState {
   readonly current: Phase;
-  readonly advancedAt: number; // turn number when this phase was entered (0-based)
+  readonly advancedAt: number;
   readonly summary?: string;
+  /** Artifact each completed stage produced — the named channels. */
+  readonly artifacts: Readonly<Partial<Record<Phase, string>>>;
+  /** Corrective validate→blueprint re-entries taken so far. */
+  readonly backwardJumps: number;
+}
+
+/**
+ * @param start — first phase of the run (`clarify` when interviews are on, else `research`).
+ */
+export function initialPhaseState(advancedAt = 0, start: Phase = "clarify"): PhaseState {
+  return { current: start, advancedAt, artifacts: Object.freeze({}), backwardJumps: 0 };
+}
+
+export type RouteDecision =
+  | { readonly kind: "done" }
+  | { readonly kind: "loop-back"; readonly next: "blueprint" }
+  | { readonly kind: "halt"; readonly reason: string };
+
+/**
+ * Route out of `validate` on MEASURED gate data: blockers_count === 0 → done;
+ * blockers_count > 0 → loop back to blueprint, bounded by maxBackwardJumps.
+ */
+export function routeAfterValidate(
+  data: ValidationGateData,
+  backwardJumps: number,
+  maxBackwardJumps: number,
+): RouteDecision {
+  if (data.blockersCount === 0) return { kind: "done" };
+  if (backwardJumps >= maxBackwardJumps) {
+    return {
+      kind: "halt",
+      reason: `validation reports ${data.blockersCount} blocker(s) after ${backwardJumps} corrective pass(es) — backward-jump limit (${maxBackwardJumps}) reached; surfacing the validation report as the final answer`,
+    };
+  }
+  return { kind: "loop-back", next: "blueprint" };
+}
+
+/** Forward transitions only; corrective loop-back is ENGINE-initiated via routeAfterValidate. */
+export function nextForward(current: Phase): Phase | undefined {
+  const idx = PHASES.indexOf(current);
+  return idx >= 0 && idx < PHASES.length - 1 ? PHASES[idx + 1] : undefined;
 }
 
 export interface AdvancePhaseResult {
@@ -35,10 +175,10 @@ export interface AdvancePhaseFailure {
 
 export type AdvancePhaseOutcome = AdvancePhaseResult | AdvancePhaseFailure;
 
-/** PHASE_GATE_TURNS: if the model stays in one phase for this many turns, the engine re-prompts. */
-export const PHASE_GATE_TURNS = 4;
-
-/** Validate a phase transition. Only forward progression is allowed. */
+/**
+ * Pure order check: only the immediate next phase is allowed.
+ * Artifact gates are applied by the engine after this returns ok.
+ */
 export function advancePhase(
   current: Phase | undefined,
   target: string,
@@ -47,25 +187,31 @@ export function advancePhase(
     return {
       ok: false,
       error: `unknown phase '${target}'; valid phases: ${PHASES.join(", ")}`,
-      phase: current ?? "research",
+      phase: current ?? PHASES[0],
     };
   }
-  const from = current ?? "research";
-  const currentIdx = PHASES.indexOf(from);
-  const targetIdx = PHASES.indexOf(target as Phase);
-  if (targetIdx <= currentIdx) {
+  const from = current ?? PHASES[0];
+  const expected = nextForward(from);
+  if (expected === undefined) {
     return {
       ok: false,
-      error: `cannot move backward from '${from}' to '${target}'`,
+      error: `'${from}' is the terminal phase; finalize via answer["ready"] = True after saving the validation artifact`,
+      phase: from,
+    };
+  }
+  if (target !== expected) {
+    return {
+      ok: false,
+      error: `cannot advance from '${from}' to '${target}' — the next phase is '${expected}'`,
       phase: from,
     };
   }
   return { ok: true, phase: target as Phase };
 }
 
-/** Return the current phase (defaults to "research" if undefined). */
+/** Return the current phase (defaults to first phase if undefined). */
 export function currentPhase(state: PhaseState | undefined): Phase {
-  return state?.current ?? "research";
+  return state?.current ?? PHASES[0];
 }
 
 /** Return the number of turns spent in the current phase. */
@@ -73,6 +219,9 @@ export function turnsInPhase(state: PhaseState | undefined, completedTurns: numb
   return state ? completedTurns - state.advancedAt : completedTurns;
 }
 
+/** PHASE_GATE_TURNS: if the model stays in one phase for this many turns, the engine re-prompts. */
+export const PHASE_GATE_TURNS = 4;
+
 /** Produce a re-prompt message when the model stalls in a phase for too long. */
 export function phaseGatePrompt(
   state: PhaseState | undefined,
@@ -81,9 +230,9 @@ export function phaseGatePrompt(
   const turns = turnsInPhase(state, completedTurns);
   const phase = currentPhase(state);
   if (turns >= PHASE_GATE_TURNS && turns % PHASE_GATE_TURNS === 0) {
-    const next = nextPhase(phase);
+    const next = nextForward(phase);
     const hint = next
-      ? ` Consider calling advance_phase("${next}") if your ${phase} work is complete.`
+      ? ` Consider calling advance_phase("${next}") if your ${phase} work is complete (after save_artifact when required).`
       : "";
     return [
       `You have spent ${turns} turns in the '${phase}' phase.`,
@@ -92,9 +241,3 @@ export function phaseGatePrompt(
   }
   return undefined;
 }
-
-/** Return the next phase, or undefined if at the terminal phase. */
-export function nextPhase(current: Phase): Phase | undefined {
-  const idx = PHASES.indexOf(current);
-  return idx >= 0 && idx < PHASES.length - 1 ? PHASES[idx + 1] : undefined;
-}

package/src/core/types.ts

@@ -50,6 +50,8 @@ export interface RlmConfig {
   orchestrator: boolean;
   /** Enable the phase pipeline (advance_phase + stall nags) at depth 0. */
   pipeline: boolean;
+  /** Max validate→blueprint corrective re-entries when validation reports blockers (default 2). */
+  maxBackwardJumps: number;
   /** Summarize the trajectory when it grows past the threshold (keeps the root window small). */
   compaction: boolean;
   /** Compact when estimated history tokens reach this fraction of the model's context window. */
@@ -62,6 +64,8 @@ export interface RlmConfig {
   askUserQuestion: boolean;
   /** Allow todo() calls from the REPL. */
   todo: boolean;
+  /** Enable the load_library() REPL scaffold (external dirs/files/git repos as extra context slots). */
+  libraryLoader: boolean;
   /** ThinkingLevel for the root smart model (set via /rlm-config). */
   smartReasoning?: ThinkingLevel;
   /** Output token cap + temperature for the root smart model per turn.

package/src/index.ts

@@ -27,13 +27,17 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   const config = mergeConfig({});
   const controller = new RlmController(config);
   const editRegistry = new EditRegistry();
+  let onSandboxDiscardExtra: (() => void) | undefined;
   const sandboxManager = new SandboxManager({
     execTimeoutS: config.execTimeoutS,
     requestTimeoutMs: config.requestTimeoutMs,
     python: config.python,
     sandboxInitTimeoutMs: config.sandboxInitTimeoutMs,
     maxPromptChars: config.maxPromptChars,
-    onSandboxDiscarded: () => { editRegistry.clear(); },
+    onSandboxDiscarded: () => {
+      editRegistry.clear();
+      onSandboxDiscardExtra?.();
+    },
   });
   let packedContextText: string | undefined;
   let contextPackPromise: Promise<string | undefined> | undefined;
@@ -107,6 +111,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           registry: ctx.modelRegistry,
           editRegistry,
           config: controller.config,
+          registerDiscardHook: (reset) => { onSandboxDiscardExtra = reset; },
           ensureContext: async () => {
             const contextText = await ensureRepositoryContext(ctx.cwd ?? process.cwd());
             if (contextText === undefined) throw new Error("repository context could not be loaded into RLM sandbox");