@hicaru/pi-rlm 0.2.2 → 0.3.0

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,7 +15,10 @@ 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 { errorMessage } from "./util/errors.ts";
@@ -57,22 +60,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 +170,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) {
@@ -184,9 +209,10 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     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")
@@ -196,25 +222,24 @@ export default function rlmExtension(pi: ExtensionAPI): void {
 
     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)
@@ -236,7 +261,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     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;
@@ -264,9 +289,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/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

package/src/sandbox/interrupts.ts

@@ -10,21 +10,27 @@ import type { WorkerInterrupt } from "./protocol.ts";
 import { writeContextTempFile } from "./context-file.ts";
 import { errorMessage, formatError } from "../util/errors.ts";
 
-/** Result of a host-side library pack requested by `load_library`. */
-export interface LibraryLoadResult {
-  readonly payload: unknown;     // always ContextFile[] under lib/<id>/
+/** Result of a host-side pack requested by `add_context`. */
+export interface AddContextResult {
+  readonly payload: unknown;     // always ContextFile[] under ctx/<id>/ (or un-prefixed for cwd)
   readonly files?: number;
   readonly chars: number;
   readonly sourceId: string;
   readonly pathPrefix: string;
-  /** Host already has this library — no pack, empty payload. */
+  /** Host already has this source — no pack, empty payload. */
   readonly alreadyLoaded?: boolean;
+  /** Document-type files in the payload (fresh + cache hits). */
+  readonly documents?: number;
+  /** Documents freshly converted this call (cache hits excluded). */
+  readonly converted?: number;
+  /** Paths skipped during packing (model-facing). */
+  readonly skipped?: readonly { readonly path: string; readonly reason: string }[];
 }
 
 /**
  * Per-interrupt routing context for the sub-LLM handlers.
  *
- * Only the four sub-call kinds can be spawned, so only they carry it; load_library is
+ * Only the four sub-call kinds can be spawned, so only they carry it; add_context is
  * always synchronous within one exec.
  */
 export interface SubcallOpts {
@@ -43,7 +49,7 @@ export interface SubLlmHandlers {
   llmQueryBatched(prompts: readonly string[], model: string | null, depth: number, opts: SubcallOpts): Promise<string[]>;
   rlmQuery(prompt: string, model: string | null, depth: number, opts: SubcallOpts): Promise<string>;
   rlmQueryBatched(prompts: readonly string[], model: string | null, depth: number, opts: SubcallOpts): Promise<string[]>;
-  loadLibrary(source: string, depth: number): Promise<LibraryLoadResult>;
+  addContext(source: string, depth: number): Promise<AddContextResult>;
 }
 
 /** Narrow an unknown JSON value to a frozen string array. Non-strings and blanks are dropped. */
@@ -65,7 +71,7 @@ export const REJECT: SubLlmHandlers = {
   llmQueryBatched: async (p) => p.map(() => formatError("sub-LLM bridge not configured")),
   rlmQuery: async () => formatError("sub-LLM bridge not configured"),
   rlmQueryBatched: async (p) => p.map(() => formatError("sub-LLM bridge not configured")),
-  loadLibrary: async () => { throw new Error("load_library not configured"); },
+  addContext: async () => { throw new Error("add_context not configured"); },
 };
 
 /** Body of a reply frame — the union of every handler's payload shape. */
@@ -79,6 +85,9 @@ export interface ReplyBody {
   source_id?: string;
   path_prefix?: string;
   already_loaded?: boolean;
+  documents?: number;
+  converted?: number;
+  skipped?: readonly { readonly path: string; readonly reason: string }[];
   error?: string;
 }
 
@@ -114,8 +123,8 @@ export async function serviceInterrupt(
     } else if (msg.type === "rlm_query_batched") {
       const responses = await h.rlmQueryBatched(msg.prompts ?? [], msg.model ?? null, d, opts);
       reply(msg.rid, { responses });
-    } else if (msg.type === "load_library") {
-      const lib = await h.loadLibrary(msg.source ?? "", d);
+    } else if (msg.type === "add_context") {
+      const lib = await h.addContext(msg.source ?? "", d);
       if (lib.alreadyLoaded) {
         // No temp file — worker short-circuits on already_loaded.
         reply(msg.rid, {
@@ -124,10 +133,13 @@ export async function serviceInterrupt(
           chars: lib.chars,
           source_id: lib.sourceId,
           path_prefix: lib.pathPrefix,
+          documents: lib.documents ?? 0,
+          converted: lib.converted ?? 0,
+          skipped: lib.skipped,
         });
       } else {
         const { path, json: isJson } = await writeContextTempFile(lib.payload);
-        // Worker reads then unlinks (worker._load_library). Host must not unlink here —
+        // Worker reads then unlinks (worker._add_context). Host must not unlink here —
         // if the worker is SIGKILLed before os.remove, the temp file leaks in tmpdir (acceptable).
         reply(msg.rid, {
           path,
@@ -136,6 +148,9 @@ export async function serviceInterrupt(
           chars: lib.chars,
           source_id: lib.sourceId,
           path_prefix: lib.pathPrefix,
+          documents: lib.documents ?? 0,
+          converted: lib.converted ?? 0,
+          skipped: lib.skipped,
         });
       }
     }