@hicaru/pi-rlm 0.2.2 → 0.3.1

package/src/core/engine.ts

@@ -9,8 +9,8 @@
 
 import type { Api, Model, Usage } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { buildLibraryHandler } from "../bridge/library.ts";
-import { mergeLibraryIntoContext } from "../context/library-context.ts";
+import { buildAddContextHandler } from "../bridge/add-context.ts";
+import { mergeIntoContext } from "../context/merge.ts";
 import {
   createSubcallHandlers,
   type Invocation,
@@ -30,7 +30,6 @@ import { appendUserMessage } from "./history.ts";
 import { runTurn } from "./iteration.ts";
 import { type Limits, LimitError, LimitGuard } from "./limits.ts";
 import type { RlmConfig, RlmInput, RlmResult, RunRlm, Sampling } from "./types.ts";
-import { serializeForSandbox, type ContextBundle } from "../context/repomix-context.ts";
 import { formatError } from "../util/errors.ts";
 import { createSubcallGates, type SubcallGates } from "../util/concurrency.ts";
 
@@ -128,7 +127,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
       getConfig: () => deps.config,
       signal: deps.signal,
       runChild: run,
-      // Read lazily: a library loaded on turn 3 must reach a child spawned on turn 4. Safe
+      // Read lazily: a source added on turn 3 must reach a child spawned on turn 4. Safe
       // despite being wired before liveContext is assigned — children can only spawn from an
       // interrupt during runTurn, which is strictly after loadContext below.
       getChildContext: () => liveContext,
@@ -153,19 +152,19 @@ export function createEngine(deps: EngineDeps): RunRlm {
     };
     let sandbox: PythonSandbox | undefined;
     /**
-     * This run's live context: the repo pack plus every library loaded so far. Children inherit
-     * it, so it must grow when load_library appends (see the library handler's onLoaded below).
+     * This run's live context: whatever was seeded plus every source added so far. Children
+     * inherit it, so it must grow when add_context appends (see the handler's onLoaded below).
      *
      * Run-scoped on purpose — recursion means N of these are live at once, and a module-level
      * "current context" would hand a depth-3 child its cousin's world.
      */
-    let liveContext: unknown = null;
+    let liveContext: unknown = [];
     /**
      * This run's hold on the serialized context file. Kept for the whole run so every child that
      * inherits the same payload reuses one file instead of re-serializing the repository.
      */
     let contextPin: PinnedContext | undefined;
-    /** Re-pin after the payload changes identity (mergeLibraryIntoContext returns a new array). */
+    /** Re-pin after the payload changes identity (mergeIntoContext returns a new array). */
     const repinLiveContext = async (): Promise<void> => {
       const previous = contextPin;
       contextPin = await pinContext(liveContext);
@@ -188,12 +187,12 @@ export function createEngine(deps: EngineDeps): RunRlm {
         orchestrator: deps.config.orchestrator,
         recursion: input.depth + 1 < deps.config.maxDepth,
         maxPromptChars: deps.config.maxPromptChars,
-        libraryLoader: deps.config.libraryLoader,
+        contextLoader: deps.config.contextLoader,
         child: input.depth > 0,
       });
 
-      const libraryHandlers = deps.config.libraryLoader
-        ? buildLibraryHandler({
+      const contextHandlers = deps.config.contextLoader
+        ? buildAddContextHandler({
             cwd: runCwd,
             emitter,
             parentId: selfReportId,
@@ -201,8 +200,8 @@ export function createEngine(deps: EngineDeps): RunRlm {
             getContext: () => liveContext,
             onLoaded: async (payload) => {
               // The accumulator is what children inherit, which is what makes inheritance
-              // transitive — grandchildren see the library too.
-              liveContext = mergeLibraryIntoContext(liveContext, payload);
+              // transitive — grandchildren see the source too.
+              liveContext = mergeIntoContext(liveContext, payload);
               await repinLiveContext();
             },
           }).handlers
@@ -217,17 +216,14 @@ export function createEngine(deps: EngineDeps): RunRlm {
         initTimeoutMs: deps.config.sandboxInitTimeoutMs,
         maxPromptChars: deps.config.maxPromptChars,
         awaitTimeoutS: Math.round(deps.config.requestTimeoutMs / 1000),
-        handlers: { ...subcalls, ...libraryHandlers },
+        handlers: { ...subcalls, ...contextHandlers },
       });
 
       let history: ChatMsg[] = [{ role: "system", content: system }];
       let pendingReplOutputs: string | undefined;
 
-      // Context: serialize ContextBundle to sandbox-ready JSON array, pass raw strings through.
-      liveContext =
-        typeof input.context === "object" && input.context !== null && "files" in input.context
-          ? serializeForSandbox(input.context as ContextBundle)
-          : input.context;
+      // Context is already a sandbox-ready list (or a raw string for text children).
+      liveContext = input.context ?? [];
       contextPin = await pinContext(liveContext);
       await sandbox.loadContextPinned(contextPin);
       for (let i = 0; i < deps.config.maxIterations; i++) {

package/src/core/types.ts

@@ -42,8 +42,13 @@ export interface RlmConfig {
   readonly python: string;
   /** Worker startup wait before treating sandbox init as failed (ms). */
   readonly sandboxInitTimeoutMs: number;
-  /** Enable the load_library() REPL scaffold (external dirs/files/git repos as extra context slots). */
-  readonly libraryLoader: boolean;
+  /** Enable the add_context() REPL scaffold (external dirs/files/git repos/documents into context). */
+  readonly contextLoader: boolean;
+  /**
+   * When true, the first repl() call seeds `context` with the working directory
+   * (un-prefixed paths). When false, context stays empty until add_context is called.
+   */
+  readonly autoSeedCwd: boolean;
   /** ThinkingLevel for the root smart model (set via /rlm-config). */
   readonly smartReasoning?: ThinkingLevel;
   /** Output token cap + temperature for the root smart model per turn.

package/src/index.ts

@@ -15,10 +15,27 @@ import { markdownTheme } from "./ui/theme-adapter.ts";
 import { SandboxManager } from "./sandbox/sandbox-manager.ts";
 import { createSubcallGates } from "./util/concurrency.ts";
 import { BackgroundTasks } from "./tool/background-tasks.ts";
-import { packRepository, formatForLLM, serializeForSandbox } from "./context/repomix-context.ts";
+import { resolve } from "node:path";
+import { resolveSource } from "./context/resolve.ts";
+import { formatContextListing } from "./context/listing.ts";
+import type { AddContextHandlerBundle } from "./bridge/add-context.ts";
 import { buildNativeSystemPrompt, NATIVE_TURN_REMINDER } from "./prompts/native.ts";
 import { bashCommandFromInput, isFileReadingCommand, capToolResultText, BASH_BLOCK_REASON } from "./mode/native-guards.ts";
+import {
+  isSubagentChildBypass,
+  commitSubagentForceActivation,
+  shouldEnforceNativeReaderBlock,
+  processRlmDepth,
+} from "./mode/subagent.ts";
 import { errorMessage } from "./util/errors.ts";
+import { trace, traceEnabled } from "./util/trace.ts";
+
+export {
+  isSubagentChildBypass,
+  commitSubagentForceActivation,
+  shouldEnforceNativeReaderBlock,
+  processRlmDepth,
+} from "./mode/subagent.ts";
 
 const BLOCKED_NATIVE_TOOLS = Object.freeze(new Set(["read", "grep"]));
 /** How often to keep the parent sandbox's request watchdog alive during detached work. */
@@ -26,6 +43,23 @@ const WATCHDOG_HEARTBEAT_MS = 30_000;
 const CAPPED_RESULT_TOOLS = Object.freeze(new Set(["bash", "find", "ls"]));
 
 export default function rlmExtension(pi: ExtensionAPI): void {
+  // Subagent children run a native tool flow; RLM's contract is the opposite
+  // (block read/grep, route through repl). Env fast path: full bypass when
+  // PI_SUBAGENT_CHILD=1 (unless force-in under the depth cap). See mode/subagent.ts.
+  if (isSubagentChildBypass()) {
+    if (traceEnabled) {
+      trace("subagent.bypass", {
+        reason: process.env.PI_RLM_FORCE_IN_SUBAGENT === "1" ? "force_depth_cap" : "child",
+        depth: processRlmDepth(),
+      });
+    }
+    return;
+  }
+  commitSubagentForceActivation();
+  if (traceEnabled && process.env.PI_SUBAGENT_CHILD === "1") {
+    trace("subagent.force", { depth: processRlmDepth() });
+  }
+
   // Init synchronously with defaults — ensures commands/tools/handlers register before session_start
   const config = mergeConfig({});
   const controller = new RlmController(config);
@@ -57,22 +91,37 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   }, WATCHDOG_HEARTBEAT_MS);
   watchdogHeartbeat.unref();
 
-  let packedContextText: string | undefined;
-  let contextPackPromise: Promise<string | undefined> | undefined;
-  const ensureRepositoryContext = async (cwd: string): Promise<string | undefined> => {
-    if (packedContextText !== undefined && sandboxManager.contextPayload !== null) return packedContextText;
-    contextPackPromise ??= packRepository(cwd)
+  /** Memoised cwd seed — one resolveSource(pathPrefix:"") per session. */
+  let seedPromise: Promise<void> | undefined;
+  let cwdSeeded = false;
+  /** Live add_context bundle — seed plants the "" sentinel here so add_context(".") is a no-op. */
+  let contextBundleRef: AddContextHandlerBundle | undefined;
+  /**
+   * Payload identity last injected into the context hook. Re-inject only when the payload
+   * reference changes (seed, add_context, reset) — not every turn. Keeps the root window small.
+   */
+  let listingPayloadRef: unknown = undefined;
+  let listingInjected = false;
+  const seedContext = async (cwd: string): Promise<void> => {
+    if (cwdSeeded) return;
+    if (!controller.config.autoSeedCwd) {
+      cwdSeeded = true;
+      return;
+    }
+    seedPromise ??= resolveSource(cwd, { cwd, pathPrefix: "" })
       .then((result) => {
+        // Sticky either way: a failed seed must not re-walk the whole repo on every repl().
+        cwdSeeded = true;
         if (!result.ok) {
-          console.warn(`[rlm] repository context pack failed: ${result.error}`);
-          return undefined;
+          console.warn(`[rlm] context seed failed: ${result.error}`);
+          return;
         }
-        sandboxManager.contextPayload = serializeForSandbox(result.value);
-        packedContextText = formatForLLM(result.value);
-        return packedContextText;
+        sandboxManager.contextPayload = result.value.payload;
+        // Register the cwd seed with the bridge so add_context(".") cannot double the tree.
+        contextBundleRef?.markSeededCwd(resolve(cwd));
       })
-      .finally(() => { contextPackPromise = undefined; });
-    return contextPackPromise;
+      .finally(() => { seedPromise = undefined; });
+    await seedPromise;
   };
 
   // Load persisted settings async — applied before session_start handler reads controller state
@@ -152,9 +201,16 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           gates,
           background,
           registerDiscardHook: (reset) => { onSandboxDiscardExtra = reset; },
+          registerContextBundle: (bundle) => {
+            contextBundleRef = bundle;
+            // Tool re-registers each session; re-plant sentinel if seed already landed.
+            if (cwdSeeded && Array.isArray(sandboxManager.contextPayload)
+              && sandboxManager.contextPayload.length > 0) {
+              bundle.markSeededCwd(resolve(ctx.cwd ?? process.cwd()));
+            }
+          },
           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");
+            await seedContext(ctx.cwd ?? process.cwd());
           },
         }));
       } catch (err) {
@@ -178,43 +234,50 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     setRlmModeStatus(ctx.ui, controller, ctx.getContextUsage());
   });
 
-  // ── System prompt: native RLM mode addendum (only when enabled) ──
+  /** True when the native-mode trade holds: enabled AND repl is in the active tool set. */
+  const nativeTradeHolds = (): boolean =>
+    shouldEnforceNativeReaderBlock({
+      enabled: controller.enabled,
+      activeToolNames: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : undefined,
+    });
+
+  // ── System prompt: native RLM mode addendum (only when the trade holds) ──
   pi.on("before_agent_start", async (event) => {
-    if (!controller.enabled) return;
+    if (!nativeTradeHolds()) 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) => {
+  // ── Context injection: listing of whatever is currently loaded ──
+  // Re-inject only when the payload identity changes (seed / add_context), not every turn —
+  // the listing can be up to 200 file lines and the plugin exists to shrink the root window.
+  pi.on("context", async (event) => {
     const filtered = event.messages.filter(
       (message) =>
         !(message.role === "custom" && message.customType === "rlm-intro")
         && !(message.role === "user" && typeof message.content === "string" && message.content === NATIVE_TURN_REMINDER),
     );
-    if (!controller.enabled) return { messages: filtered };
+    if (!nativeTradeHolds()) return { messages: filtered };
 
     type PiMessage = (typeof filtered)[number];
 
-    // Inject repository context as a compact listing (once per session)
-    if (!contextInjected) {
-      const cwd = ctx.cwd ?? process.cwd();
-      const contextText = await ensureRepositoryContext(cwd);
-      if (contextText !== undefined) {
-        contextInjected = true;
-        const instruction = [
-          "ANALYZE THIS REPOSITORY using repl({code}) — read/grep are DISABLED.",
-          "Repository contents are pre-loaded in the Python REPL `context` variable.",
-          "Locate with search()/grep_context()/outline() (free), then delegate bulk reading to",
-          "map_files()/llm_query_batched(). If credits exhausted → report and stop.",
-          "",
-        ].join("\n");
-        filtered.unshift({
-          role: "user" as const,
-          content: instruction + contextText,
-          timestamp: 0,
-        } as PiMessage);
-      }
+    const payload = sandboxManager.contextPayload;
+    if (!listingInjected || payload !== listingPayloadRef) {
+      listingInjected = true;
+      listingPayloadRef = payload;
+      const listing = formatContextListing(payload);
+      const instruction = [
+        "ANALYZE with repl({code}) — read/grep are DISABLED.",
+        "Files you have loaded live in the Python REPL `context` variable (starts empty; cwd seeds on first repl()).",
+        "Locate with search()/grep_context()/outline() (free), then delegate bulk reading to",
+        "map_files()/llm_query_batched(). Use add_context(path) for external dirs/files/docs/git URLs.",
+        "If credits exhausted → report and stop.",
+        "",
+      ].join("\n");
+      filtered.unshift({
+        role: "user" as const,
+        content: instruction + listing,
+        timestamp: 0,
+      } as PiMessage);
     }
 
     // Per-turn last-position reminder (not persisted — context hook rebuilds every request)
@@ -231,12 +294,19 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   // `edit`/`write` stay unblocked so the agent modifies files through Pi's native
   // tool flow (visible to all plugins, +/- diff preview). File reading/searching
   // belongs in the REPL, and bash output is capped as a backstop.
+  // Fail-open when repl is not active (e.g. --tools allowlist without repl): never
+  // confiscate readers without a working substitute (RLM paper §2 trade).
   pi.on("tool_call", async (event) => {
-    if (!controller.enabled) return;
+    if (!nativeTradeHolds()) {
+      if (traceEnabled && controller.enabled) {
+        trace("native.block_skip", { toolName: event.toolName, reason: "no_active_repl" });
+      }
+      return;
+    }
     if (BLOCKED_NATIVE_TOOLS.has(event.toolName)) {
       return {
         block: true,
-        reason: "RLM mode active. Use repl({code}) to read files and search the repository — all files are pre-loaded in the REPL `context` variable. Use `edit`/`write` for file changes. If sub-LLM credits are exhausted, report to the user.",
+        reason: "RLM mode active. Use repl({code}) to read files and search the repository — loaded files live in the REPL `context` variable (cwd seeds on first call). Use `edit`/`write` for file changes. If sub-LLM credits are exhausted, report to the user.",
       };
     }
     const bashCommand = event.toolName === "bash" ? bashCommandFromInput(event.input) : undefined;
@@ -246,7 +316,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   });
 
   pi.on("tool_result", async (event) => {
-    if (!controller.enabled || !CAPPED_RESULT_TOOLS.has(event.toolName)) return;
+    if (!nativeTradeHolds() || !CAPPED_RESULT_TOOLS.has(event.toolName)) return;
     let changed = false;
     const content = event.content.map((c) => {
       if (c.type !== "text") return c;
@@ -264,9 +334,11 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     clearInterval(watchdogHeartbeat);
     background.dispose();
     await sandboxManager.dispose();
-    contextInjected = false;
-    packedContextText = undefined;
-    contextPackPromise = undefined;
-    sandboxManager.contextPayload = null;
+    cwdSeeded = false;
+    seedPromise = undefined;
+    contextBundleRef = undefined;
+    listingPayloadRef = undefined;
+    listingInjected = false;
+    sandboxManager.contextPayload = [];
   });
 }

package/src/mode/rlm-mode.ts

@@ -12,7 +12,7 @@ import { modelRef, resolveModelId, saveSettings } from "../config/settings.ts";
 import { createEngine } from "../core/engine.ts";
 import { limitsFromConfig } from "../core/limits.ts";
 import type { RlmConfig, RlmResult } from "../core/types.ts";
-import { packRepository, serializeForSandbox } from "../context/repomix-context.ts";
+import { resolveSource } from "../context/resolve.ts";
 import { RlmEmitter } from "../tool/rlm-events.ts";
 import { formatError } from "../util/errors.ts";
 import { cheapestModel } from "./llm-model.ts";
@@ -87,13 +87,14 @@ export class RlmController {
     this.active = abortController;
 
     const done = (async () => {
-      // Auto-pack empty/undefined context via repomix; pass explicit context through.
+      // Auto-seed empty/undefined context from cwd (same resolveSource path as native mode);
+      // pass explicit context through.
       let contextValue: unknown = input.context;
       if (contextValue === undefined || (typeof contextValue === "string" && contextValue.trim() === "")) {
         const cwd = ctx.cwd ?? process.cwd();
-        const result = await packRepository(cwd, abortController.signal);
+        const result = await resolveSource(cwd, { cwd, pathPrefix: "", signal: abortController.signal });
         contextValue = result.ok
-          ? serializeForSandbox(result.value)
+          ? result.value.payload
           : formatError(`failed to pack repository — ${result.error}`);
       }
       const engine = createEngine({

package/src/mode/subagent.ts

@@ -0,0 +1,68 @@
+/**
+ * Subagent / process-boundary isolation for RLM.
+ *
+ * Two layers:
+ *   1. Env fast path — packages that set PI_SUBAGENT_CHILD=1 fully bypass RLM.
+ *   2. Capability gate — never confiscate native readers unless `repl` is in the
+ *      active tool set (paper trade: scaffold only if the REPL substitute exists).
+ *
+ * In-process rlm_query depth is handled by subcall-handlers.childRun; this module
+ * only covers OS-process children (pi subagents), which restart at depth 0.
+ */
+import { DEFAULT_CONFIG } from "../config/defaults.ts";
+
+export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
+export const RLM_FORCE_IN_SUBAGENT_ENV = "PI_RLM_FORCE_IN_SUBAGENT";
+export const RLM_DEPTH_ENV = "PI_RLM_DEPTH";
+
+/** Cross-process depth from env. Missing / invalid → 0. */
+export function processRlmDepth(): number {
+  const raw = process.env[RLM_DEPTH_ENV];
+  if (raw === undefined || raw === "") return 0;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return n;
+}
+
+/**
+ * True when this process should not activate RLM at all (no tools / hooks / flags).
+ *
+ * - Parent (no PI_SUBAGENT_CHILD=1) → false.
+ * - Child without force → true.
+ * - Child with force but depth >= maxDepth → true (refuse force; paper §7 cost bound).
+ * - Child with force and depth < maxDepth → false (experimental opt-in).
+ */
+export function isSubagentChildBypass(maxDepth: number = DEFAULT_CONFIG.maxDepth): boolean {
+  if (process.env[SUBAGENT_CHILD_ENV] !== "1") return false;
+  if (process.env[RLM_FORCE_IN_SUBAGENT_ENV] !== "1") return true;
+  return processRlmDepth() >= maxDepth;
+}
+
+/**
+ * Call only when RLM will activate. Scrubs force so grandchildren that inherit env
+ * do not re-open unbounded force; bumps PI_RLM_DEPTH for any re-set force path.
+ * No-op when not a forced child under the depth cap.
+ */
+export function commitSubagentForceActivation(maxDepth: number = DEFAULT_CONFIG.maxDepth): void {
+  if (process.env[SUBAGENT_CHILD_ENV] !== "1") return;
+  if (process.env[RLM_FORCE_IN_SUBAGENT_ENV] !== "1") return;
+  if (processRlmDepth() >= maxDepth) return;
+  const next = processRlmDepth() + 1;
+  delete process.env[RLM_FORCE_IN_SUBAGENT_ENV];
+  process.env[RLM_DEPTH_ENV] = String(next);
+}
+
+/**
+ * RLM's native-mode trade: confiscate read/grep (and bash readers) only when the
+ * substitute is actually callable. Fail-open when the active tool list is unknown
+ * or does not include `repl` (official pi subagent uses --tools without repl).
+ */
+export function shouldEnforceNativeReaderBlock(opts: {
+  readonly enabled: boolean;
+  readonly activeToolNames: readonly string[] | undefined;
+}): boolean {
+  if (!opts.enabled) return false;
+  const names = opts.activeToolNames;
+  if (names === undefined) return false;
+  return names.includes("repl");
+}

package/src/prompts/glossary.ts

@@ -82,13 +82,13 @@ export const SPAWN_GLOSSARY_LINES: readonly string[] = Object.freeze([
  */
 export const RECURSION_CONTEXT_LINES: readonly string[] = Object.freeze([
   "",
-  "  **What a child sees:** it inherits YOUR `context` — the repository plus every library you",
-  "  loaded (`lib/<id>/…`) — and runs `search` / `grep_context` / `outline` / `map_files` over the",
-  "  same paths. So send instructions, never file bodies: pasting content you already share costs",
-  "  your tokens twice and buys nothing. Your prompt becomes the child's question.",
-  "  Narrow its world with `rlm_query(prompt, paths=['src/auth/', 'lib/x-9f3a/'])` — path PREFIXES,",
+  "  **What a child sees:** it inherits YOUR `context` — every file you have loaded, including",
+  "  sources under `ctx/<id>/…` — and runs `search` / `grep_context` / `outline` / `map_files`",
+  "  over the same paths. So send instructions, never file bodies: pasting content you already",
+  "  share costs your tokens twice and buys nothing. Your prompt becomes the child's question.",
+  "  Narrow its world with `rlm_query(prompt, paths=['src/auth/', 'ctx/x-9f3a/'])` — path PREFIXES,",
   "  not globs. Omit `paths` to hand over everything.",
-  "  Inheritance is one-way: libraries the child loads, and its whole REPL, die with it — only its",
+  "  Inheritance is one-way: sources the child loads, and its whole REPL, die with it — only its",
   "  final answer string returns.",
   "  At the depth cap `rlm_query` degrades to a plain sub-LLM call with NO context, which is why",
   "  this section disappears at the last recursive depth.",
@@ -99,14 +99,17 @@ export const RECURSION_CONTEXT_LINES: readonly string[] = Object.freeze([
  * than a repository the run packed for itself.
  */
 export const CHILD_CONTEXT_LINES: readonly string[] = Object.freeze([
-  "  You are a sub-RLM. This `context` is your parent's world — the repository plus every library",
-  "  it loaded (paths under `lib/<id>/…`). Answer only the question above; your REPL and anything",
-  "  you load die with you, and only your final answer string returns to the parent.",
+  "  You are a sub-RLM. This `context` is your parent's world — every file it has loaded (cwd",
+  "  paths un-prefixed; external sources under `ctx/<id>/…`). Answer only the question above;",
+  "  your REPL and anything you load die with you, and only your final answer string returns.",
 ]);
 
 /** Why a file the user mentioned may be missing from `context`. */
-export const CONTEXT_EXCLUSION_NOTE =
-  "  NOTE: files larger than 1MB and gitignored files are NOT in `context` — they exist only on disk.";
+export const CONTEXT_EXCLUSION_NOTE = [
+  "  NOTE: `context` holds only the files you have loaded (starts empty; cwd seeds on first use).",
+  "  Gitignored files and files larger than 1MB of plain text are skipped. Binary documents",
+  "  (PDF, DOCX, XLSX, PPTX, CSV, …) ARE included — converted to Markdown on the way in.",
+].join("\n");
 
 /** The large-on-disk-file protocol (headless + native). */
 export const LARGE_FILE_RULE_LINES: readonly string[] = Object.freeze([
@@ -200,7 +203,7 @@ export function howToRunCode(): string {
 export function replGlossary(
   kind: ContextKind,
   recursion: boolean,
-  libraryLoader: boolean,
+  contextLoader: boolean,
   child: boolean,
 ): string {
   const lines = ["Available in the REPL:"];
@@ -212,10 +215,10 @@ export function replGlossary(
     );
   } else {
     lines.push(
-      "- `context`: list[dict] — a pre-packed JSON array of every file in the repository. Each dict has",
-      "  keys: `path` (relative file path, str), `content` (file text, str), `tokens` (estimated count, int).",
-      "  For large repos, chunk `context` into batches and delegate to sub-LLMs — never dump raw file",
-      "  bodies into your own output.",
+      "- `context`: list[dict] — the files you have loaded (starts empty; cwd seeds on first use).",
+      "  Each dict has keys: `path` (str), `content` (str), `tokens` (int).",
+      "  Cwd paths are un-prefixed (real paths for edit/write); external sources land under",
+      "  `ctx/<source_id>/…`. For large sets, chunk and delegate — never dump raw file bodies.",
       CONTEXT_EXCLUSION_NOTE,
     );
     if (child) lines.push(...CHILD_CONTEXT_LINES);
@@ -240,22 +243,22 @@ export function replGlossary(
     ...SPAWN_GLOSSARY_LINES,
     ...DELEGATION_GLOSSARY_LINES,
   );
-  if (libraryLoader) {
+  if (contextLoader) {
     lines.push(
-      "- `load_library(source: str) -> dict`: load an EXTERNAL library, source tree, or document and",
-      "  **APPEND its files into the existing `context` list** (same shape: path/content/tokens).",
-      "  `source` may be a local directory (repomix-packed), a single file path, or an https/git@ URL",
-      "  (shallow-cloned, then packed). Paths are namespaced under `lib/<source_id>/…` so you can filter",
-      "  by prefix. Returns metadata only:",
-      "  {\"source\", \"source_id\", \"path_prefix\", \"files\", \"chars\", \"context_len\", \"already_loaded\"}",
-      "  or an \"Error: ...\" string. **Never treat the return value as the file list** — always search",
-      "  and chunk the single variable `context`. Do not invent `context_1` / aliases; do not call",
-      "  globals()/locals(). Idempotent: re-loading the same source is a no-op.",
+      "- `add_context(source: str) -> dict`: load a dir, file, document, or git URL and **APPEND its",
+      "  files into `context`** (same shape: path/content/tokens). Documents (PDF, DOCX, XLSX, PPTX,",
+      "  CSV, …) are converted to Markdown automatically and cached until the source file changes.",
+      "  Paths are namespaced under `ctx/<source_id>/…` so you can filter by prefix. Returns metadata:",
+      "  {\"source\", \"source_id\", \"path_prefix\", \"files\", \"chars\", \"context_len\", \"already_loaded\",",
+      "  \"documents\", \"converted\", \"skipped\"} or an \"Error: ...\" string. `documents` is how many",
+      "  document-type files landed (incl. cache hits); `converted` is how many were freshly converted",
+      "  this call. **Never treat the return value as the file list** — always search and chunk the",
+      "  single variable `context`. Idempotent: re-loading the same source is a no-op.",
       "",
       "  ```python",
-      "  info = load_library(\"/path/to/other-project\")",
+      '  info = add_context("/path/to/other-project")',
       "  # info is metadata; files are already in context under info[\"path_prefix\"]",
-      "  lib_files = [f for f in context if f[\"path\"].startswith(info[\"path_prefix\"])]",
+      '  lib_files = [f for f in context if f["path"].startswith(info["path_prefix"])]',
       "  ```",
     );
   }

package/src/prompts/native.ts

@@ -17,7 +17,7 @@ function nativeReplGlossary(): string {
     "State persists; only `print()` output is returned, so wrap inspections in `print(...)`.",
     "",
     "### REPL Environment",
-    "- `context`: list[dict] — every file in the repository. Each dict: `path` (str), `content` (str), `tokens` (int).",
+    "- `context`: list[dict] — the files you have loaded (starts empty; cwd seeds on first repl()). Each dict: `path` (str), `content` (str), `tokens` (int).",
     "",
     "Retrieval — free (no sub-LLM call, no tokens). **Start here, before guessing filenames:**",
     "- `search(query, k=10, path_glob=None) -> [{path, line, score, snippet}]` — BM25 over `context`. Returns pointers, not bodies.",
@@ -30,13 +30,13 @@ function nativeReplGlossary(): string {
     "- `llm_query(prompt, model=None) -> str` — one-shot sub-LLM. Use for extraction, summarization, Q&A over a chunk.",
     "- `llm_query_batched(prompts, model=None) -> list[str]` — concurrent sub-LLM calls; output order matches input order.",
     CHUNKED_GLOSSARY_LINE_NATIVE,
-    "- `rlm_query(prompt, model=None, paths=None) -> str` — recursive RLM with its own REPL for complex sub-tasks needing iterative reasoning. Prefer llm_query — rlm_query is slower and costlier. The child inherits your `context` (repo + loaded libraries) and takes your prompt as its question, so describe the task; never paste file text. `paths=['src/auth/']` narrows its context by prefix.",
+    "- `rlm_query(prompt, model=None, paths=None) -> str` — recursive RLM with its own REPL for complex sub-tasks needing iterative reasoning. Prefer llm_query — rlm_query is slower and costlier. The child inherits your `context` (loaded files + ctx/ sources) and takes your prompt as its question, so describe the task; never paste file text. `paths=['src/auth/']` narrows its context by prefix.",
     "- `rlm_query_batched(prompts, model=None) -> list[str]` — concurrent recursive RLM calls.",
     "- `spawn(fn, *args) -> Task` / `rlm_await(t)` / `rlm_await_all(ts)` — start `llm_query`, `llm_query_batched`, `llm_query_chunked`, `map_files`, `rlm_query` or `rlm_query_batched` without waiting (NOT `llm_map_reduce`); collect later, order preserved. Tasks outlive the repl() call, so spawn slow work early and await when you need it.",
     "",
     "",
     "- `answers` / `plan` — dicts persisted across every repl() call. Your memo.",
-    "- `load_library(source) -> dict`: append external dir/file/git tree into `context` under `lib/<id>/…`. Return is metadata only — always use `context`.",
+    "- `add_context(source) -> dict`: append dir/file/document/git URL into `context` under `ctx/<id>/…`. Documents converted to Markdown. Return is metadata only — always use `context`.",
     "- `SHOW_VARS() -> str` — list all variables currently in the REPL.",
     "- `answer`: dict `{\"content\": \"\", \"ready\": False}`. Setting `answer[\"ready\"] = True` delivers it to the user; do not restate it.",
     "",
@@ -90,7 +90,7 @@ export function buildNativeSystemPrompt(): string {
     "call (rlm_query for iterative sub-tasks). Deterministic Python over `context` is free and",
     "preferred for lookups. Semantic reading is always delegated.",
     "",
-    "All file content is pre-loaded in the REPL `context` variable. Use ONLY `repl({code})`.",
+    "Loaded file content lives in the REPL `context` variable (cwd seeds on first call). Use ONLY `repl({code})`.",
     "If sub-LLM credits are exhausted → report the error to the user and stop.",
     "",
     "AUTHORING RULE: sub-LLMs (`llm_query` family) READ — they extract, locate, and summarize.",

package/src/prompts/system.ts

@@ -28,7 +28,7 @@ export interface SystemPromptOptions {
   readonly orchestrator?: boolean;
   readonly recursion?: boolean;
   readonly maxPromptChars?: number;
-  readonly libraryLoader?: boolean;
+  readonly contextLoader?: boolean;
   /** depth > 0 — this run is an rlm_query child and its `context` is the parent's world. */
   readonly child?: boolean;
 }
@@ -70,7 +70,7 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
     howToRunCode(),
     "",
     replGlossary(
-      kind, recursion, opts.libraryLoader ?? false, opts.child ?? false,
+      kind, recursion, opts.contextLoader ?? false, opts.child ?? false,
     ),
     "",
     "REPL stdout over ~800 characters is truncated to a short excerpt — large results stay in your",

package/src/sandbox/context-file.ts

@@ -2,12 +2,12 @@
  * Temp-file transport for sandbox context payloads, with refcounted sharing.
  *
  * Two callers, two ownership models, one writer:
- *  - `writeContextTempFile` — non-owning. `load_library` uses it because the WORKER unlinks
- *    that file after reading it (see sandbox.ts serviceInterrupt / worker.py `_load_library`).
+ *  - `writeContextTempFile` — non-owning. `add_context` uses it because the WORKER unlinks
+ *    that file after reading it (see sandbox.ts serviceInterrupt / worker.py `_add_context`).
  *  - `pinContext` — refcounted. Every child RLM of one node inherits the SAME payload, so an
  *    18-way fan-out would otherwise cost 18 serializations and 18 files. Pins are keyed by
- *    payload identity, which is a free version key: `mergeLibraryIntoContext` always returns a
- *    NEW array, so loading a library mints a new key and old holders keep their own file.
+ *    payload identity, which is a free version key: `mergeIntoContext` always returns a
+ *    NEW array, so adding a source mints a new key and old holders keep their own file.
  *
  * Serialization is chunked with an await between chunks so the event loop is never blocked for
  * more than ~SERIALIZE_CHUNK entries. A Worker Thread was considered and rejected: posting the