@hicaru/pi-rlm 0.1.0

package/src/core/types.ts

@@ -0,0 +1,131 @@
+/** Shared configuration + runtime types for the RLM engine. */
+
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import type { AskAnswer, AskQuestion, ProposedDiffEdit, ProposedEdit } from "../sandbox/protocol.ts";
+import type { ReconstructResult } from "../state/resume.ts";
+
+export interface Sampling {
+  readonly maxTokens?: number;
+  readonly temperature?: number;
+  readonly reasoning?: ThinkingLevel;
+}
+
+type MutableSampling = { -readonly [Key in keyof Sampling]?: Sampling[Key] };
+
+export interface TelemetryConfig {
+  /** Default: enabled iff a tracking URI resolves from config or MLFLOW_TRACKING_URI. */
+  readonly enabled?: boolean;
+  readonly trackingUri?: string;
+  readonly experimentId?: string;
+  /** Bearer token is env-only via MLFLOW_TRACKING_TOKEN; never persisted in rlm.json. */
+  readonly maxQueueSize?: number;
+}
+
+export interface RunLogConfig {
+  /** Default: true — always-on, opt-out. */
+  readonly enabled?: boolean;
+  /** Default: ".rlm/runs". Directory under cwd for run artifacts. */
+  readonly dir?: string;
+  /** Default: true — whether to write sandbox.pkl snapshots. */
+  readonly snapshot?: boolean;
+  /** Default: 50 — prune oldest runs beyond this count on each new run. */
+  readonly maxRuns?: number;
+}
+
+export interface RlmConfig {
+  /** Persistent editor-routing mode; when enabled, plain interactive prompts use RLM. */
+  enabled: boolean;
+  /** Max recursion depth. depth >= maxDepth ⇒ rlm_query falls back to a plain llm_query. */
+  maxDepth: number;
+  /** Max turns before the engine must finalize. */
+  maxIterations: number;
+  /** Per-`repl`-block wall-clock timeout inside the worker (seconds). */
+  execTimeoutS: number;
+  /** Parent-side watchdog per sandbox request (ms). */
+  requestTimeoutMs: number;
+  /** Concurrency pool for *_batched sub-calls. */
+  maxConcurrentSubcalls: number;
+  /** Reject sub-LLM prompts larger than this many chars. */
+  maxPromptChars: number;
+  /** Max USD spend across the whole tree before the engine stops (undefined = no cap). */
+  maxBudgetUsd?: number;
+  /** Max wall-clock ms across the whole tree before the engine stops (undefined = no cap). */
+  maxTimeoutMs?: number;
+  /** Max total input+output tokens across the whole tree before the engine stops (undefined = no cap). */
+  maxTokens?: number;
+  /** Max consecutive error turns before the engine stops (undefined = no cap). */
+  maxErrors?: number;
+  /** Append the orchestrator addendum to the system prompt. */
+  orchestrator: boolean;
+  /** 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. */
+  compactionThresholdPct: number;
+  /** Python executable used to launch the sandbox worker. */
+  python: string;
+  /** Worker startup wait before treating sandbox init as failed (ms). */
+  sandboxInitTimeoutMs: number;
+  /** Allow ask_user_question() calls from the root REPL. */
+  askUserQuestion: boolean;
+  /** Allow todo() calls from the REPL. */
+  todo: boolean;
+  /** ThinkingLevel for the root smart model (set via /rlm-config). */
+  smartReasoning?: ThinkingLevel;
+  /** Output token cap + temperature for the root smart model per turn.
+   *  Keeps each turn short so the next turn's input stays manageable.
+   *  `reasoning` is read from `smartReasoning` if omitted here. */
+  rootSampling?: Readonly<Sampling>;
+  /** System prompt injected into every llm_query / llm_query_batched sub-call.
+   *  Instructs the worker model to respond concisely.
+   *  undefined = no system prompt (raw completion). */
+  subSystemPrompt?: string;
+  /** Sampling for sub-LLM (worker) calls. */
+  subSampling: MutableSampling;
+  /** Optional MLflow telemetry export configuration. Omitted by default. */
+  readonly telemetry?: TelemetryConfig;
+  /** Optional run-state persistence configuration. Enabled by default. */
+  readonly runLog?: RunLogConfig;
+}
+
+/** Input to a (headless) RLM run. */
+export interface RlmInput {
+  /** The question for the root model (folded into the metadata prompt). */
+  readonly rootPrompt: string;
+  /** The (possibly huge) context loaded into the sandbox REPL. */
+  readonly context: unknown;
+  /** Recursion depth; 0 = top-level root. */
+  readonly depth: number;
+  /** AgentTree node to attach this run's node under (set when recursing). */
+  readonly parentNodeId?: string;
+  /** "provider/id" — overrides the root model for this run (set by recursive rlm_query). */
+  readonly modelOverride?: string;
+  /** Remaining budget for this subtree (set by parent from its LimitGuard). */
+  readonly remainingBudgetUsd?: number;
+  /** Remaining timeout for this subtree (set by parent from its LimitGuard). */
+  readonly remainingTimeoutMs?: number;
+  /** Depth-0 resume payload — controller rebuilds this from the trail's `reconstructRlmState()`. */
+  readonly resume?: ReconstructResult & { readonly ok: true };
+}
+
+/** Result of a completed RLM run. */
+export interface RlmResult {
+  readonly answer: string;
+  /** Legacy anchor edits retained for compatibility while older run-state rows exist. */
+  readonly edits?: readonly ProposedEdit[];
+  readonly diffs?: readonly ProposedDiffEdit[];
+  readonly iterations: number;
+  readonly costUsd: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly durationMs: number;
+}
+
+/** A function that runs an RLM to completion — used to wire recursion (rlm_query). */
+export interface InteractiveDeps {
+  /** Called when the sandbox issues ask_user_question; undefined = feature disabled. */
+  readonly onAskUserQuestion?: (questions: readonly AskQuestion[]) => Promise<AskAnswer[]>;
+  /** Called when the sandbox issues todo; undefined = feature disabled. */
+  readonly onTodo?: (action: string, params: Record<string, unknown>) => Promise<string>;
+}
+
+export type RunRlm = (input: RlmInput) => Promise<RlmResult>;

package/src/index.ts

@@ -0,0 +1,165 @@
+/** pi-rlm — Recursive Language Model for Pi. */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Markdown } from "@earendil-works/pi-tui";
+import { registerRlmCommand } from "./commands/rlm.ts";
+import { registerRlmConfigCommand } from "./commands/rlm-config.ts";
+import { createRlmTool } from "./tool/rlm-tool.ts";
+import { createApplyDiffTool } from "./tool/apply-diff-tool.ts";
+import { createReplTool } from "./tool/repl-tool.ts";
+import { loadSettings, mergeConfig, resolveModelId } from "./config/settings.ts";
+import { RlmController, cheapestModel } from "./mode/rlm-mode.ts";
+import { postRlmGuide } from "./ui/intro.ts";
+import { setRlmModeStatus } from "./ui/status.ts";
+import { SandboxManager } from "./sandbox/sandbox-manager.ts";
+import { packRepository, formatForLLM, serializeForSandbox } from "./context/repomix-context.ts";
+import { buildNativeSystemPrompt } from "./prompts/system.ts";
+import { errorMessage } from "./util/errors.ts";
+
+const BLOCKED_NATIVE_TOOLS = Object.freeze(new Set(["read", "grep", "bash", "write", "edit"]));
+
+export default function rlmExtension(pi: ExtensionAPI): void {
+  void setupRlmExtension(pi).catch((error) => {
+    console.warn(`[rlm] extension setup failed: ${errorMessage(error)}`);
+  });
+}
+
+async function setupRlmExtension(pi: ExtensionAPI): Promise<void> {
+  const persisted = await loadSettings();
+  const config = mergeConfig(persisted.config);
+  const controller = new RlmController(config);
+  controller.savedWorkerRef = persisted.worker;
+
+  // ── SandboxManager — persistent singleton for native-mode repl() ──
+  const sandboxManager = new SandboxManager({
+    execTimeoutS: config.execTimeoutS,
+    requestTimeoutMs: config.requestTimeoutMs,
+    python: config.python,
+    sandboxInitTimeoutMs: config.sandboxInitTimeoutMs,
+  });
+
+  // ── Message renderers ──
+  pi.registerMessageRenderer(
+    "rlm-answer",
+    (message, _options, _theme) => new Markdown(String(message.content ?? ""), 1, 0, getMarkdownTheme()),
+  );
+  pi.registerMessageRenderer("rlm-question", (message, _options, _theme) =>
+    new Markdown(`**RLM question**\n\n${String(message.content ?? "")}`, 1, 0, getMarkdownTheme()),
+  );
+  pi.registerMessageRenderer("rlm-intro", (message, _options, _theme) =>
+    new Markdown(String(message.content ?? ""), 1, 0, getMarkdownTheme()),
+  );
+
+  // ── Commands ──
+  registerRlmCommand(pi, controller);
+  registerRlmConfigCommand(pi, controller);
+
+  // ── Tool registration ──
+  // Existing rlm tool (stays for backward compat with /rlm mode)
+  pi.registerTool(createRlmTool(controller));
+  pi.registerTool(createApplyDiffTool());
+
+  // Native repl tool — re-registered each session to pick up model provider changes
+  let guidePosted = false;
+
+  pi.on("session_start", async (_event, ctx) => {
+    // Restore saved worker ref — retry lazily if registry/auth is not ready yet.
+    // session_start can fire before the provider/auth registry is fully loaded, so a miss
+    // here does NOT mean the ref is stale: RlmController.resolveModels() retries later.
+    if (controller.savedWorkerRef) {
+      const resolved = resolveModelId(ctx.modelRegistry, controller.savedWorkerRef);
+      if (resolved) controller.workerModel = resolved;
+    }
+
+    // Register repl tool with current models (re-registers each session for provider changes)
+    const workerModel = controller.workerModel ?? cheapestModel(ctx.modelRegistry) ?? ctx.model;
+    const model = ctx.model;
+    if (workerModel && model) {
+      try {
+        pi.registerTool(createReplTool({
+          sandboxManager,
+          model,
+          workerModel,
+          getModel: () => controller.resolveModels(ctx)?.model,
+          getWorkerModel: () => controller.resolveModels(ctx)?.worker,
+          registry: ctx.modelRegistry,
+          config,
+        }));
+      } catch { /* re-registration on provider change — ignore if already registered */ }
+    }
+
+    setRlmModeStatus(ctx.ui, controller);
+    if (!guidePosted && controller.enabled) {
+      guidePosted = true;
+      postRlmGuide(pi, controller);
+    }
+  });
+
+  // ── System prompt: native RLM mode addendum (only when enabled) ──
+  pi.on("before_agent_start", async (event) => {
+    if (!controller.enabled) return;
+    return { systemPrompt: event.systemPrompt + "\n\n" + buildNativeSystemPrompt() };
+  });
+
+  // ── Context injection: repo listing for the main agent ──
+  let contextInjected = false;
+  pi.on("context", async (event, ctx) => {
+    const filtered = event.messages.filter(
+      (message) => !(message.role === "custom" && message.customType === "rlm-intro"),
+    );
+
+    // Inject repository context as a compact listing (once per session, only when RLM is enabled)
+    if (controller.enabled && !contextInjected) {
+      contextInjected = true;
+      const cwd = ctx.cwd ?? process.cwd();
+      const result = await packRepository(cwd);
+      if (result.ok) {
+        const contextText = formatForLLM(result.value);
+        const instruction = [
+          "ANALYZE THIS REPOSITORY using repl({code}) — read/grep/bash are DISABLED.",
+          `Total: ${result.value.totalFiles} files, ${result.value.totalChars.toLocaleString()} chars — must use repl().`,
+          "Chunk context via Python, delegate to llm_query. If credits exhausted → report and stop.",
+          "",
+        ].join("\n");
+        const contextMsg = {
+          role: "user" as const,
+          content: instruction + contextText,
+          timestamp: 0,
+        } as (typeof filtered)[number];
+
+        // Store context for sandbox loading on first repl() call
+        sandboxManager.contextPayload = serializeForSandbox(result.value);
+
+        return { messages: [contextMsg, ...filtered] };
+      }
+    }
+
+    return { messages: filtered };
+  });
+
+  // ── Input routing: native mode — agent decides whether to use repl() or other tools ──
+  // The old black-box rlm() routing is removed; the main agent receives messages normally
+  // and chooses natively when to call repl(), read, grep, zebra-mcp, etc.
+  pi.on("input", async (_event, _ctx) => {
+    return { action: "continue" };
+  });
+
+  // ── Tool restriction: block read/grep/bash when RLM is ON ──
+  pi.on("tool_call", async (event) => {
+    if (!controller.enabled) return;
+    if (BLOCKED_NATIVE_TOOLS.has(event.toolName)) {
+      return {
+        block: true,
+        reason: "RLM mode active. Use repl({code}) to read files and apply_diff({diff}) to modify them. All files are pre-loaded in the REPL. If sub-LLM credits are exhausted, report to the user.",
+      };
+    }
+  });
+
+  // ── Session shutdown: cleanup ──
+  pi.on("session_shutdown", async () => {
+    controller.abort();
+    await sandboxManager.dispose();
+    contextInjected = false;
+  });
+}

package/src/mode/input-router.ts

@@ -0,0 +1,23 @@
+import type { InputSource } from "@earendil-works/pi-coding-agent";
+
+export interface InputRouteState {
+  readonly enabled: boolean;
+  readonly busy: boolean;
+}
+
+export interface InputRouteEvent {
+  readonly source: InputSource;
+  readonly text: string;
+}
+
+export type InputRouteDecision = "continue" | "route" | "busy";
+
+export function decideRlmInputRoute(event: InputRouteEvent, state: InputRouteState): InputRouteDecision {
+  const eligible = state.enabled && event.source === "interactive" && !event.text.trimStart().startsWith("/");
+  if (!eligible) return "continue";
+  return state.busy ? "busy" : "route";
+}
+
+export function shouldRouteRlmInput(event: InputRouteEvent, state: InputRouteState): boolean {
+  return decideRlmInputRoute(event, state) === "route";
+}

package/src/mode/rlm-mode.ts

@@ -0,0 +1,149 @@
+/**
+ * RlmController — holds RLM config + chosen models.
+ *
+ * The engine drives the root model turn-by-turn over ```repl``` blocks with full budget/token/
+ * timeout/error guards, compaction, and a finalize fallback. `start()` returns a RunHandle with
+ * the completion promise.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_RUN_DIR } from "../config/defaults.ts";
+import { modelRef, resolveModelId, saveSettings } from "../config/settings.ts";
+import { createEngine } from "../core/engine.ts";
+import type { InteractiveDeps, RlmConfig, RlmInput, RlmResult } from "../core/types.ts";
+import type { ReconstructResult } from "../state/resume.ts";
+import { packRepository, serializeForSandbox } from "../context/repomix-context.ts";
+import { RlmEmitter } from "../tool/rlm-events.ts";
+import { formatError } from "../util/errors.ts";
+
+export function cheapestModel(registry: ModelRegistry): Model<Api> | undefined {
+  const models = registry.getAvailable();
+  if (models.length === 0) return undefined;
+  return [...models].sort((a, b) => a.cost.input + a.cost.output - (b.cost.input + b.cost.output))[0];
+}
+
+export interface RunHandle {
+  readonly abort: () => void;
+  readonly done: Promise<RlmResult>;
+}
+
+/** B5+SA: discriminated union removes non-null `!` assertions and the `context: ""` hack. */
+export type StartInput =
+  | { readonly kind: "fresh"; readonly rootPrompt: string; readonly context: unknown }
+  | { readonly kind: "resume"; readonly resume: ReconstructResult & { ok: true }; readonly context: unknown };
+
+export class RlmController {
+  workerModel: Model<Api> | undefined;
+  savedWorkerRef: string | undefined;
+  private active: AbortController | null = null;
+
+  constructor(public config: RlmConfig) {}
+
+  get enabled(): boolean {
+    return this.config.enabled;
+  }
+
+  setEnabled(enabled: boolean): void {
+    this.config.enabled = enabled;
+    void this.persist();
+  }
+
+  toggle(): boolean {
+    const next = !this.enabled;
+    this.setEnabled(next);
+    if (!next) this.abort();   // turning the mode OFF also stops an in-flight run
+    return next;
+  }
+
+  hasSavedModels(): boolean {
+    return Boolean(this.savedWorkerRef || this.workerModel);
+  }
+
+  async persist(): Promise<boolean> {
+    return await saveSettings({
+      config: this.config,
+      worker: modelRef(this.workerModel) ?? this.savedWorkerRef,
+    });
+  }
+
+  isBusy(): boolean {
+    return this.active !== null;
+  }
+
+  abort(): void {
+    this.active?.abort();
+  }
+
+  resolveModels(ctx: ExtensionContext): { model: Model<Api>; worker: Model<Api> } | undefined {
+    if (!this.workerModel && this.savedWorkerRef) this.workerModel = resolveModelId(ctx.modelRegistry, this.savedWorkerRef);
+    const model = ctx.model ?? cheapestModel(ctx.modelRegistry);
+    if (!model) return undefined;
+    const worker = this.workerModel ?? cheapestModel(ctx.modelRegistry) ?? model;
+    return { model, worker };
+  }
+
+  start(ctx: ExtensionContext, input: StartInput, emitter?: RlmEmitter, interactive?: InteractiveDeps): RunHandle {
+    const models = this.resolveModels(ctx);
+    if (!models) throw new Error("no model with configured auth is available");
+    if (this.active) throw new Error("RLM run already in progress"); // QC: mutual-exclusion guard
+
+    const abortController = new AbortController();
+    this.active = abortController;
+
+    const runState = this.config.runLog?.enabled !== false
+      ? { cwd: ctx.cwd ?? process.cwd(), dir: this.config.runLog?.dir ?? DEFAULT_RUN_DIR, snapshot: this.config.runLog?.snapshot !== false }
+      : undefined;
+
+    const done = (async () => {
+      let engineInput: RlmInput;
+      if (input.kind === "fresh") {
+        // Auto-pack empty/undefined context via repomix; pass explicit context through.
+        let contextValue: unknown = input.context;
+        if (contextValue === undefined || contextValue === "" || (typeof contextValue === "string" && contextValue.trim() === "")) {
+          const cwd = ctx.cwd ?? process.cwd();
+          const result = await packRepository(cwd, abortController.signal);
+          if (result.ok) {
+            contextValue = serializeForSandbox(result.value);
+          } else {
+            contextValue = formatError(`failed to pack repository — ${result.error}`);
+          }
+        }
+        engineInput = {
+          rootPrompt: input.rootPrompt,
+          context: contextValue,
+          depth: 0,
+        };
+      } else {
+        engineInput = {
+          rootPrompt: input.resume.header.rootPrompt,
+          context: input.context, // B5: load the actual context from the sidecar, not ""
+          depth: 0,
+          resume: input.resume,
+        };
+      }
+      const engine = createEngine({
+        model: models.model,
+        workerModel: models.worker,
+        registry: ctx.modelRegistry,
+        config: this.config,
+        signal: abortController.signal,
+        emitter: emitter ?? new RlmEmitter(),
+        runState,
+        onAskUserQuestion: interactive?.onAskUserQuestion,
+        onTodo: interactive?.onTodo,
+        limits: {
+          maxBudgetUsd: this.config.maxBudgetUsd,
+          maxTimeoutMs: this.config.maxTimeoutMs,
+          maxTokens: this.config.maxTokens,
+          maxErrors: this.config.maxErrors,
+        },
+      });
+      return await engine(engineInput);
+    })().finally(() => {
+      if (this.active === abortController) this.active = null;
+    });
+
+    return { abort: () => abortController.abort(), done };
+  }
+}

package/src/patch/apply.ts

@@ -0,0 +1,148 @@
+/**
+ * Applies RLM-proposed edits to disk.
+ *
+ * Two edit kinds from the sandbox protocol:
+ *   ProposedEdit      — oldText / newText anchor replacement
+ *   ProposedDiffEdit  — unified diff string (applied via `diff.applyPatch`)
+ *
+ * Returns a Result. Caller decides whether to show errors in UI.
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import * as Diff from "diff";
+import type { ProposedDiffEdit, ProposedEdit } from "../sandbox/protocol.ts";
+import { err, ok, type Result } from "../util/errors.ts";
+
+// ── Shared private helpers ─────────────────────────────────────────────────
+
+/** Normalise to LF so string-replace is CRLF-safe. */
+function toLF(s: string): string {
+  return s.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+/** Restore original line endings after replacement. */
+function restoreEndings(s: string, crlf: boolean): string {
+  return crlf ? s.replace(/\n/g, "\r\n") : s;
+}
+
+function hasCRLF(s: string): boolean {
+  return s.includes("\r\n");
+}
+
+// ── ApplyResult ─────────────────────────────────────────────────────────────
+
+export interface ApplySuccess {
+  readonly applied: number;
+}
+
+export interface ApplyFailure {
+  readonly failures: ReadonlyArray<{ readonly path: string; readonly reason: string }>;
+}
+
+export type ApplyResult = Result<ApplySuccess, ApplyFailure>;
+
+// ── Generic accumulator (shared by anchor + diff apply) ─────────────────────
+
+/**
+ * Runs `applyOne` for every item, tallying successes and collecting failures.
+ * The only thing that differs between anchor and diff apply is the per-item
+ * helper and the failure-path key — both passed in, so the loop is written once.
+ */
+async function applyAll<T>(
+  items: readonly T[],
+  applyOne: (item: T, cwd: string) => Promise<Result<void, string>>,
+  getKey: (item: T) => string,
+  cwd: string,
+): Promise<ApplyResult> {
+  const failures: Array<{ readonly path: string; readonly reason: string }> = [];
+  let applied = 0;
+  for (const item of items) {
+    const r = await applyOne(item, cwd);
+    if (r.ok) {
+      applied++;
+    } else {
+      failures.push({ path: getKey(item), reason: r.error });
+    }
+  }
+  return failures.length === 0 ? ok({ applied }) : err({ failures });
+}
+
+// ── ProposedEdit (oldText / newText) ────────────────────────────────────────
+
+async function applySingleAnchor(
+  edit: ProposedEdit,
+  cwd: string,
+): Promise<Result<void, string>> {
+  const abs = resolve(cwd, edit.path);
+  let raw: string;
+  try {
+    raw = await readFile(abs, "utf8");
+  } catch (e) {
+    return err(`read error: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const crlf = hasCRLF(raw);
+  const content = toLF(raw);
+  const needle = toLF(edit.oldText);
+  if (!content.includes(needle)) {
+    return err(`oldText not found in ${edit.path}`);
+  }
+  const replaced = content.replace(needle, toLF(edit.newText));
+  try {
+    await writeFile(abs, restoreEndings(replaced, crlf), "utf8");
+    return ok(undefined);
+  } catch (e) {
+    return err(`write error: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+export function applyAnchorEdits(
+  edits: readonly ProposedEdit[],
+  cwd: string,
+): Promise<ApplyResult> {
+  return applyAll(edits, applySingleAnchor, (e) => e.path, cwd);
+}
+
+// ── ProposedDiffEdit (unified diff string) ──────────────────────────────────
+
+async function applySingleDiff(
+  diffEdit: ProposedDiffEdit,
+  cwd: string,
+): Promise<Result<void, string>> {
+  // Extract file path from diff header: "--- a/path" or "--- path"
+  const match = /^--- (?:a\/)?(.+)$/m.exec(diffEdit.diff);
+  const relPath = match?.[1]?.trim();
+  if (relPath === undefined) {
+    return err("diff has no '---' header; cannot determine target file");
+  }
+  const abs = resolve(cwd, relPath);
+  let raw: string;
+  try {
+    raw = await readFile(abs, "utf8");
+  } catch (e) {
+    return err(`read error: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const crlf = hasCRLF(raw);
+  let patched: string | false;
+  try {
+    patched = Diff.applyPatch(toLF(raw), diffEdit.diff);
+  } catch (e) {
+    return err(`invalid diff — ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (patched === false) {
+    return err(`patch does not apply cleanly to ${relPath}`);
+  }
+  try {
+    await writeFile(abs, restoreEndings(patched, crlf), "utf8");
+    return ok(undefined);
+  } catch (e) {
+    return err(`write error: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+export function applyDiffEdits(
+  diffs: readonly ProposedDiffEdit[],
+  cwd: string,
+): Promise<ApplyResult> {
+  return applyAll(diffs, applySingleDiff, (d) => d.diff.slice(0, 40), cwd);
+}

package/src/patch/index.ts

@@ -0,0 +1,37 @@
+/**
+ * applyEdits — THE single call site for applying proposed edits/diffs.
+ *
+ * Both rlm-tool.ts and rlm.ts must call this and nothing else.
+ * No duplication allowed.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ProposedDiffEdit, ProposedEdit } from "../sandbox/protocol.ts";
+import { applyAnchorEdits, applyDiffEdits, type ApplyResult } from "./apply.ts";
+
+/** Surface an apply outcome through a single notify — used for both edit kinds. */
+function notifyApplyResult(r: ApplyResult, label: string, ctx: ExtensionContext): void {
+  if (!r.ok) {
+    const lines = r.error.failures.map((f) => `• ${f.path}: ${f.reason}`);
+    ctx.ui.notify(`Some ${label}s failed:\n${lines.join("\n")}`, "error");
+  } else {
+    ctx.ui.notify(`Applied ${r.value.applied} ${label}${r.value.applied !== 1 ? "s" : ""}.`, "info");
+  }
+}
+
+export async function applyEdits(
+  edits: readonly ProposedEdit[],
+  diffs: readonly ProposedDiffEdit[],
+  ctx: ExtensionContext,
+): Promise<void> {
+  const hasEdits = edits.length > 0 || diffs.length > 0;
+  if (!hasEdits) return;
+  const cwd = ctx.cwd ?? process.cwd();
+
+  if (edits.length > 0) {
+    notifyApplyResult(await applyAnchorEdits(edits, cwd), "edit", ctx);
+  }
+  if (diffs.length > 0) {
+    notifyApplyResult(await applyDiffEdits(diffs, cwd), "diff", ctx);
+  }
+}