@hicaru/pi-rlm 0.2.2 → 0.3.0

package/src/sandbox/protocol.ts

@@ -18,15 +18,21 @@ export interface LlmReply {
   readonly rid: string;
   readonly response?: string;
   readonly responses?: readonly string[];
-  /** load_library reply: temp file with the packed payload (+ namespace metadata). */
+  /** add_context reply: temp file with the packed payload (+ namespace metadata). */
   readonly path?: string;
   readonly json?: boolean;
   readonly files?: number;
   readonly chars?: number;
   readonly source_id?: string;
   readonly path_prefix?: string;
-  /** Host-side idempotency: library already loaded — no path payload. */
+  /** Host-side idempotency: source already loaded — no path payload. */
   readonly already_loaded?: 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 (binary, no-converter, …). */
+  readonly skipped?: readonly { readonly path: string; readonly reason: string }[];
   readonly error?: string;
 }
 
@@ -56,7 +62,7 @@ export type InterruptKind =
   | "llm_query_batched"
   | "rlm_query"
   | "rlm_query_batched"
-  | "load_library";
+  | "add_context";
 
 interface InterruptBase {
   readonly rid: string;
@@ -88,8 +94,8 @@ interface BatchedPromptInterrupt extends InterruptBase {
   readonly paths?: readonly string[];
 }
 
-export interface LoadLibraryInterrupt extends InterruptBase {
-  readonly type: "load_library";
+export interface AddContextInterrupt extends InterruptBase {
+  readonly type: "add_context";
   readonly source?: string;
 }
 
@@ -97,7 +103,7 @@ export interface LoadLibraryInterrupt extends InterruptBase {
 export type WorkerInterrupt =
   | PromptInterrupt
   | BatchedPromptInterrupt
-  | LoadLibraryInterrupt;
+  | AddContextInterrupt;
 
 export type WorkerMessage = WorkerResponse | WorkerInterrupt;
 
@@ -106,7 +112,7 @@ export const INTERRUPT_KINDS = Object.freeze(new Set<InterruptKind>([
   "llm_query_batched",
   "rlm_query",
   "rlm_query_batched",
-  "load_library",
+  "add_context",
 ]));
 
 function isRecord(value: unknown): value is Record<string, unknown> {

package/src/sandbox/py/guards.py

@@ -86,7 +86,7 @@ RESERVED = frozenset(
         "spawn", "rlm_await", "rlm_await_all",
         "map_files", "llm_map_reduce",
         "search", "grep_context", "outline",
-        "load_library",
+        "add_context",
         "SHOW_VARS", "answer", "context",
     }
 )

package/src/sandbox/py/retrieval.py

@@ -46,7 +46,7 @@ def _chunk_text(text: str, chunk_chars: int) -> list[str]:
 
 
 _INDEX_WINDOW_LINES = 40       # a window is the retrieval unit: big enough to carry meaning
-_INDEX_MAX_WINDOWS = 20_000    # ceiling so a huge load_library() cannot exhaust worker memory
+_INDEX_MAX_WINDOWS = 20_000    # ceiling so a huge add_context() cannot exhaust worker memory
 _SNIPPET_CHARS = 400
 _GREP_HARD_CAP = 200           # absolute ceiling on returned grep hits, whatever k asks for
 _BM25_K1 = 1.2

package/src/sandbox/py/tasks.py

@@ -41,14 +41,27 @@ def _reduce_batch(n: int):
     return reduce
 
 
-def _reduce_chunked(sizes: list[int]):
-    """Concatenate several llm_query_batched replies back into one flat chunk list."""
+def _reduce_chunked(sizes: list[int], drop_empty: bool = True):
+    """Concatenate several llm_query_batched replies back into one flat chunk list.
+
+    drop_empty=True (llm_query_chunked): filter "" replies so results never degrade
+    to blank entries; the flattened list may then be shorter than the chunk count,
+    so callers must consume answers in order and never index-match a chunk to a slot.
+    drop_empty=False (map_files): keep "" placeholders because _reduce_map_files
+    regroups by position — dropping an empty reply there would shift every later
+    slice and merge file contents into the wrong paths.
+    """
     per = [_reduce_batch(n) for n in sizes]
 
     def reduce(replies: list[dict[str, Any]]) -> list[str]:
+        if len(replies) != len(per):
+            return [f"Error: chunk reply count mismatch ({len(replies)} != {len(per)})"] * sum(sizes)
         out: list[str] = []
         for red, rep in zip(per, replies):
-            out.extend(red([rep]))
+            if drop_empty:
+                out.extend(x for x in red([rep]) if x)
+            else:
+                out.extend(red([rep]))
         return out
     return reduce
 
@@ -59,7 +72,7 @@ def _reduce_map_files(sizes: list[int], spans: list[tuple[str, int]]):
     A file larger than the per-prompt budget contributed several requests; its answers rejoin
     in order, which is what makes map_files a {path: answer} dict rather than a flat list.
     """
-    flatten = _reduce_chunked(sizes)
+    flatten = _reduce_chunked(sizes, drop_empty=False)
 
     def reduce(replies: list[dict[str, Any]]) -> dict[str, str]:
         responses = flatten(replies)

package/src/sandbox/py/worker.py

@@ -7,9 +7,9 @@ This is NOT a security sandbox: __import__ and open are available, so code can i
 Protocol (parent -> worker):  {"id","type":"exec"|"load_context"|"shutdown", ...}
 Protocol (worker -> parent):  {"id","ok",...result}            # response to a request
                               {"type":"llm_query"|"llm_query_batched"|"rlm_query"|
-                               "rlm_query_batched"|"load_library","rid",...}
+                               "rlm_query_batched"|"add_context","rid",...}
                                                                 # mid-exec helper request
-When sandbox code calls llm_query/rlm_query/load_library, the worker writes a
+When sandbox code calls llm_query/rlm_query/add_context, the worker writes a
 request line and BLOCKS reading stdin until the matching {"type":"llm_reply","rid",...} arrives.
 The parent services the request in-process (it holds API keys).
 
@@ -113,7 +113,7 @@ class Worker:
         builtins = _SAFE_BUILTINS.copy()
         builtins["open"] = open
         self.ns = {"__builtins__": builtins, "__name__": "__main__"}
-        self._context_payload: Any | None = None  # pristine restore for the single `context` var
+        self._context_payload: Any = []  # empty list — the only starting value that needs no bootstrap branch
         self._nudged: set[str] = set()
         self._index: _Bm25Index | None = None
         self._index_stamp: tuple[int, int] | None = None  # (id(context), len(context))
@@ -144,7 +144,7 @@ class Worker:
             ns["answers"] = {}
         if not isinstance(ns.get("plan"), dict):
             ns["plan"] = {}
-        ns["load_library"] = self._load_library
+        ns["add_context"] = self._add_context
         ns["SHOW_VARS"] = self._show_vars
         if not isinstance(ns.get("answer"), _AnswerDict):
             cur = ns.get("answer")
@@ -157,9 +157,8 @@ class Worker:
             ns["answer"] = ans
         # Single context variable (RLM paper: the context lives in the environment and
         # the model may transform it in place). Re-inject only if the model deleted the
-        # name entirely; mutations and re-binds persist within the run.
-        if self._context_payload is not None:
-            ns.setdefault("context", self._context_payload)
+        # name entirely; mutations and re-binds persist within the run. Always a list.
+        ns.setdefault("context", self._context_payload)
         # Scrub any legacy context_N names so the model never sees multi-slot APIs.
         for k in list(ns.keys()):
             if k != "context" and _CONTEXT_NAME.match(k):
@@ -412,7 +411,7 @@ class Worker:
         """Build the BM25 index on first use; rebuild when `context` was replaced or resized.
 
         Identity+length is a cheap stamp that catches the two ways context actually changes:
-        load_library() extending the list, and the model re-binding the name. In-place edits
+        add_context() extending the list, and the model re-binding the name. In-place edits
         that preserve length are not detected — documented, and rare in practice.
         """
         ctx = self.ns.get("context")
@@ -556,23 +555,24 @@ class Worker:
     def _rlm_query(self, prompt: str, model: str | None = None, paths=None) -> str:
         return self._await_task(self._start_rlm_query(prompt, model, paths))
 
-    def _load_library(self, source: str) -> dict[str, Any] | str:
+    def _add_context(self, source: str) -> dict[str, Any] | str:
         """Pack an external dir/file/git-URL on the host and append it into `context`.
 
-        Paths are namespaced under lib/<source_id>/ (host). Content is always in the
+        Paths are namespaced under ctx/<source_id>/ (host). Content is always in the
         single `context` list — never a new context_N variable.
         Host-side idempotency may return already_loaded without a payload path.
+        Documents (PDF/DOCX/…) are converted to Markdown on the host.
         """
-        r = self._rpc("load_library", {"source": str(source)})
+        r = self._rpc("add_context", {"source": str(source)})
         if r.get("error"):
             return f"Error: {r['error']}"
         if r.get("already_loaded"):
-            source_id = r.get("source_id") if isinstance(r.get("source_id"), str) else "lib"
-            path_prefix = r.get("path_prefix") if isinstance(r.get("path_prefix"), str) else f"lib/{source_id}/"
+            source_id = r.get("source_id") if isinstance(r.get("source_id"), str) else "ctx"
+            path_prefix = r.get("path_prefix") if isinstance(r.get("path_prefix"), str) else f"ctx/{source_id}/"
             ctx = self.ns.get("context")
             ctx_len = len(ctx) if isinstance(ctx, list) else 0
             print(
-                f"[rlm] load_library: already loaded {source_id} "
+                f"[rlm] add_context: already loaded {source_id} "
                 f"(paths under {path_prefix}, context len={ctx_len})"
             )
             return {
@@ -583,10 +583,13 @@ class Worker:
                 "chars": r.get("chars"),
                 "context_len": ctx_len,
                 "already_loaded": True,
+                "documents": 0,
+                "converted": 0,
+                "skipped": [],
             }
         path = r.get("path")
         if not isinstance(path, str):
-            return "Error: malformed load_library reply (no path)"
+            return "Error: malformed add_context reply (no path)"
         try:
             with io.open(path, "r") as f:
                 payload = json.load(f) if r.get("json") else f.read()
@@ -595,57 +598,71 @@ class Worker:
                 os.remove(path)  # worker owns temp-file cleanup (host does NOT unlink)
             except OSError:
                 pass
-        return self._append_library(str(source), payload, r)
+        return self._append_context(str(source), payload, r)
 
-    def _append_library(self, source: str, payload: Any, meta: dict[str, Any]) -> dict[str, Any] | str:
-        """Append host-packed library files into `context` (idempotent by path prefix).
+    def _append_context(self, source: str, payload: Any, meta: dict[str, Any]) -> dict[str, Any] | str:
+        """Append host-packed files into `context` (idempotent by path prefix).
 
         The two refusals below are pre-flighted host-side by LIST_CONTEXT_REQUIRED /
-        NO_FILES_PRODUCED in src/bridge/library.ts, so the host never commits a
+        NO_FILES_PRODUCED in src/bridge/add-context.ts, so the host never commits a
         loaded-prefix for an append that fails here. Reaching either one means host and worker
         disagree about `context`; keep the wording identical to its twin.
         """
         ctx = self.ns.get("context")
         if not isinstance(ctx, list):
             kind = type(ctx).__name__ if ctx is not None else "None"
-            return f"Error: load_library requires list context (file bundle); got {kind}"
+            return f"Error: add_context requires list context (file bundle); got {kind}"
 
         source_id = meta.get("source_id")
         if not isinstance(source_id, str) or not source_id:
-            source_id = "lib"
+            source_id = "ctx"
         path_prefix = meta.get("path_prefix")
-        if not isinstance(path_prefix, str) or not path_prefix:
-            path_prefix = f"lib/{source_id}/"
-
-        # Idempotent: already present if any path uses this library prefix.
-        for item in ctx:
-            if isinstance(item, dict) and str(item.get("path", "")).startswith(path_prefix):
-                print(
-                    f"[rlm] load_library: already loaded {source_id} "
-                    f"(paths under {path_prefix}, context len={len(ctx)})"
-                )
-                return {
-                    "source": source,
-                    "source_id": source_id,
-                    "path_prefix": path_prefix,
-                    "files": 0,
-                    "chars": meta.get("chars"),
-                    "context_len": len(ctx),
-                    "already_loaded": True,
-                }
-
-        files = self._library_file_entries(payload, path_prefix)
+        if not isinstance(path_prefix, str):
+            path_prefix = f"ctx/{source_id}/"
+        # Empty path_prefix is valid (cwd seed) but add_context always sends a non-empty ctx/ prefix.
+        # Guard startsWith on empty prefix: "anything".startswith("") is always True.
+        check_prefix = path_prefix if path_prefix != "" else None
+
+        # Idempotent: already present if any path uses this prefix.
+        if check_prefix is not None:
+            for item in ctx:
+                if isinstance(item, dict) and str(item.get("path", "")).startswith(check_prefix):
+                    print(
+                        f"[rlm] add_context: already loaded {source_id} "
+                        f"(paths under {path_prefix}, context len={len(ctx)})"
+                    )
+                    return {
+                        "source": source,
+                        "source_id": source_id,
+                        "path_prefix": path_prefix,
+                        "files": 0,
+                        "chars": meta.get("chars"),
+                        "context_len": len(ctx),
+                        "already_loaded": True,
+                        "documents": 0,
+                        "converted": 0,
+                        "skipped": [],
+                    }
+
+        files = self._context_file_entries(payload, path_prefix)
         if not files:
-            return "Error: load_library produced no files"
+            return "Error: add_context produced no files"
 
         ctx.extend(files)
         # Keep restore payload in sync with the live list.
         self._context_payload = ctx
         self.ns["context"] = ctx
 
+        documents = meta.get("documents") if isinstance(meta.get("documents"), int) else 0
+        converted = meta.get("converted") if isinstance(meta.get("converted"), int) else 0
+        skipped = meta.get("skipped") if isinstance(meta.get("skipped"), list) else []
+        skip_n = len(skipped)
+        extra = ""
+        if documents or converted or skip_n:
+            extra = f"; documents={documents}, converted={converted}, skipped={skip_n}"
         print(
-            f"[rlm] load_library: +{len(files)} files into context "
-            f"(len={len(ctx)}); paths under {path_prefix}"
+            f"[rlm] add_context: +{len(files)} files into context "
+            f"(len={len(ctx)}); paths under {path_prefix}{extra}"
         )
         return {
             "source": source,
@@ -655,14 +672,17 @@ class Worker:
             "chars": meta.get("chars"),
             "context_len": len(ctx),
             "already_loaded": False,
+            "documents": documents,
+            "converted": converted,
+            "skipped": skipped,
         }
 
     @staticmethod
-    def _library_file_entries(payload: Any, path_prefix: str) -> list[dict[str, Any]]:
+    def _context_file_entries(payload: Any, path_prefix: str) -> list[dict[str, Any]]:
         """Normalize host payload to list[dict]. Host already namespaces; string is fallback."""
         if isinstance(payload, str):
             return [{
-                "path": f"{path_prefix}content",
+                "path": f"{path_prefix}content" if path_prefix else "content",
                 "content": payload,
                 "tokens": max(1, (len(payload) + 3) // 4),
             }]
@@ -684,7 +704,7 @@ class Worker:
         """Load the packed world into the single REPL variable `context`.
 
         `index` is accepted for protocol compatibility but ignored — there is only
-        one context slot. Libraries are merged on the host (or via load_library).
+        one context slot. Sources are merged on the host (or via add_context).
         """
         with open(path, "r") as f:
             payload = json.load(f) if is_json else f.read()

package/src/sandbox/sandbox-manager.ts

@@ -6,7 +6,7 @@
 
 import { PythonSandbox, type SubLlmHandlers } from "./sandbox.ts";
 import type { ReplResult } from "./protocol.ts";
-import { mergeLibraryIntoContext } from "../context/library-context.ts";
+import { mergeIntoContext } from "../context/merge.ts";
 
 /** Static configuration for sandbox creation — set once, reused across getOrCreate calls. */
 export interface SandboxManagerConfig {
@@ -28,23 +28,26 @@ export class SandboxManager {
   /** Serialized execution queue — concurrent repl() calls wait for predecessor. */
   private execQueue: Promise<void> = Promise.resolve();
   private pendingExecCount = 0;
-  /** Context payload to load on first sandbox creation. Set externally before getOrCreate. */
-  contextPayload: unknown = null;
+  /**
+   * Context payload to load on first sandbox creation. Starts as an empty list — context is
+   * empty by default; the first repl() seeds the cwd when autoSeedCwd is on.
+   */
+  contextPayload: unknown = [];
   /** True once contextPayload has been loaded into the sandbox (prevents reload + race fix). */
   private contextLoaded = false;
 
   constructor(private readonly config: SandboxManagerConfig) {}
 
   /**
-   * Append a library payload to the context this manager replays on death-recreate.
+   * Append a source payload to the context this manager replays on death-recreate.
    *
-   * The live worker has ALREADY appended it in-process (worker.py `_append_library`), so this
+   * The live worker has ALREADY appended it in-process (worker.py `_append_context`), so this
    * deliberately does not reload — it only keeps the host's replay copy truthful. Without it a
-   * recreate silently rolls the sandbox back to a repo-only context, and any child inheriting
-   * this payload would never see the library. Dedups by `lib/<id>/` prefix.
+   * recreate silently rolls the sandbox back to a pre-append context, and any child inheriting
+   * this payload would never see the source. Dedups by `ctx/<id>/` prefix.
    */
-  appendLibrary(payload: unknown): void {
-    this.contextPayload = mergeLibraryIntoContext(this.contextPayload, payload);
+  appendContext(payload: unknown): void {
+    this.contextPayload = mergeIntoContext(this.contextPayload, payload);
   }
 
   /**
@@ -52,15 +55,14 @@ export class SandboxManager {
    * given handlers. Subsequent calls return the existing sandbox immediately.
    * Deduplicates concurrent calls via initPromise.
    *
-   * If contextPayload is set, it is loaded before the sandbox is returned.
+   * If contextPayload is defined, it is loaded before the sandbox is returned.
    */
   async getOrCreate(handlers: Partial<SubLlmHandlers>): Promise<PythonSandbox> {
     if (this.disposed) throw new Error("SandboxManager disposed");
     if (this.sandbox) {
-      // RACE FIX: contextPayload may arrive after the sandbox was created (the
-      // "context" event's async packRepository resolves after the first repl() call).
-      // Load it into the live sandbox now if still pending.
-      if (this.contextPayload !== null && !this.contextLoaded) {
+      // RACE FIX: contextPayload may arrive after the sandbox was created (lazy seed
+      // resolves after the first getOrCreate). Load it into the live sandbox now if pending.
+      if (this.contextPayload !== undefined && !this.contextLoaded) {
         await this.sandbox.loadContext(this.contextPayload);
         this.contextLoaded = true;
       }
@@ -79,8 +81,8 @@ export class SandboxManager {
       awaitTimeoutS: this.config.awaitTimeoutS,
       handlers,
     }).then(async (s) => {
-      // Load context on first creation if available.
-      if (this.contextPayload !== null) {
+      // Load context on first creation if available (empty list is a valid starting value).
+      if (this.contextPayload !== undefined) {
         await s.loadContext(this.contextPayload);
         this.contextLoaded = true;
       }

package/src/sandbox/sandbox.ts

@@ -24,7 +24,7 @@ import { pinContext, type PinnedContext } from "./context-file.ts";
 import { REJECT, serviceInterrupt, type ReplyBody, type SubLlmHandlers } from "./interrupts.ts";
 import { trace, traceEnabled } from "../util/trace.ts";
 
-export type { LibraryLoadResult, SubcallOpts, SubLlmHandlers } from "./interrupts.ts";
+export type { AddContextResult, SubcallOpts, SubLlmHandlers } from "./interrupts.ts";
 
 export interface SandboxOptions {
   /** Sandbox recursion depth label (passed to the worker, used in interrupt routing). */

package/src/text/tokens.ts

@@ -25,7 +25,7 @@ export function estimateMessageTokens(messages: { content: string }[]): number {
  * Character length of one context entry. `ContextFile`-shaped entries report their content
  * length; anything else falls back to its serialized form.
  *
- * Deliberately does NOT import `isContextFile` from context/library-context.ts: that module
+ * Deliberately does NOT import `isContextFile` from context/namespace.ts: that module
  * imports `estimateTokens` from here, so the reverse import would be a cycle. `in`-narrowing
  * needs no type guard and no cast.
  */
@@ -74,8 +74,8 @@ const isTokenizedEntry = (v: unknown): v is { readonly tokens: number } =>
   typeof v === "object" && v !== null && typeof (v as { readonly tokens?: unknown }).tokens === "number";
 
 /** Per-file token distribution for a context payload; `undefined` for plain strings or empty arrays.
- *  Handles both serialized ContextFile[] (flat array from serializeForSandbox) and raw ContextBundle
- *  objects ({ files: [...] }) so callers don't need to know which form they received. */
+ *  Handles both a flat ContextFile[] and a raw bundle object ({ files: [...] }) so callers
+ *  don't need to know which form they received. */
 export function contextSizeStats(context: unknown): ContextSizeStats | undefined {
   // Normalise to a flat entry list: accept either a direct array or an object with a .files array.
   const entries: readonly unknown[] = Array.isArray(context)

package/src/tool/repl-details.ts

@@ -2,7 +2,7 @@
  * ReplDetails — structured payload for the repl() tool's AgentToolResult<T>.
  *
  * Mirrors RlmDetails but scoped to a single code execution. Sub-calls (llm_query,
- * rlm_query, load_library) triggered during sandbox execution are
+ * rlm_query, add_context) triggered during sandbox execution are
  * accumulated into the subcalls array for tree rendering.
  */
 

package/src/tool/repl-tool.ts

@@ -20,8 +20,8 @@ import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import type { Model, Usage, Api } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { buildLibraryHandler } from "../bridge/library.ts";
-import { libraryPrefixesIn } from "../context/library-context.ts";
+import { buildAddContextHandler, type AddContextHandlerBundle } from "../bridge/add-context.ts";
+import { contextPrefixesIn } from "../context/namespace.ts";
 import type { SubcallGates } from "../util/concurrency.ts";
 import { LimitGuard, limitsFromConfig } from "../core/limits.ts";
 import type { RlmConfig, RlmInput, RlmResult } from "../core/types.ts";
@@ -115,8 +115,13 @@ export interface ReplToolDeps {
   readonly signal?: AbortSignal;
   readonly onUsage?: (usage: Usage, role: "sub") => void;
   readonly ensureContext?: () => Promise<void>;
-  /** Register a reset hook for sandbox death/dispose (e.g. load_library slot counter). */
+  /** Register a reset hook for sandbox death/dispose (e.g. add_context prefix cache). */
   readonly registerDiscardHook?: (reset: () => void) => void;
+  /**
+   * Hands the live add_context bundle to the extension so the cwd seed can
+   * markLoaded("") / markSeededCwd(abs) — without this, add_context(".") doubles the tree.
+   */
+  readonly registerContextBundle?: (bundle: AddContextHandlerBundle) => void;
 }
 
 export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplToolParams, ReplDetails> {
@@ -159,15 +164,15 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
     signal,
     onUsage,
     runChild,
-    // The session sandbox's context is the child's world. Read lazily so a load_library from an
+    // The session sandbox's context is the child's world. Read lazily so an add_context from an
     // earlier repl() reaches a child spawned in a later one. Populated before any interrupt can
     // fire: execute() awaits ensureContext() before getOrCreate().
     getChildContext: () => sandboxManager.contextPayload ?? undefined,
     trackDetached: (task) => background.track(task),
   });
 
-  const libraryBundle = getConfig().libraryLoader
-    ? buildLibraryHandler({
+  const contextBundle = getConfig().contextLoader
+    ? buildAddContextHandler({
         getCwd: () => sessionCwd,
         getEmitter: () => bridgeState.currentEmitter,
         // Refuse pre-flight whatever the worker would reject, so host idempotency is never
@@ -177,14 +182,20 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
         signal,
         // Keep the manager's replay copy in step with the worker's live `context`, and with it
         // whatever a child spawned after this load will inherit.
-        onLoaded: (payload) => { sandboxManager.appendLibrary(payload); },
+        onLoaded: (payload) => { sandboxManager.appendContext(payload); },
       })
     : undefined;
-  if (libraryBundle) {
+  if (contextBundle) {
     // Re-derive the loaded-prefix cache from the payload that will actually be replayed —
-    // clearing it outright would make the host re-clone a library the recreated worker already has.
-    const bundle = libraryBundle;
-    deps.registerDiscardHook?.(() => bundle.reset(libraryPrefixesIn(sandboxManager.contextPayload)));
+    // clearing it outright would make the host re-clone a source the recreated worker already has.
+    // Re-plant the cwd sentinel if the seed is still in the payload (un-prefixed files).
+    const bundle = contextBundle;
+    deps.registerDiscardHook?.(() => {
+      const prefixes = contextPrefixesIn(sandboxManager.contextPayload);
+      bundle.reset(prefixes);
+      if (bundle.seededCwd() !== undefined) bundle.markLoaded("");
+    });
+    deps.registerContextBundle?.(contextBundle);
   }
 
   return {
@@ -192,14 +203,15 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
     label: "REPL",
     description:
       "PRIMARY tool for ALL repository reading and analysis (read/grep are disabled in RLM mode). " +
-      "Persistent Python sandbox with every file pre-loaded in `context`. Locate first with the " +
-      "free primitives search(query) / grep_context(pattern) / outline(path), then delegate the " +
-      "semantic reading to map_files / llm_query / llm_query_batched / llm_query_chunked " +
-      "(rlm_query for iterative sub-tasks) — stdout returned to you is hard-capped at 4K chars, " +
-      "so printing file bodies is useless. Variables, imports, and the `answers`/`plan` memo " +
-      "persist across calls. Also supports load_library.",
+      "Persistent Python sandbox with loaded files in `context` (starts empty; cwd seeds on first " +
+      "call). Locate first with the free primitives search(query) / grep_context(pattern) / " +
+      "outline(path), then delegate the semantic reading to map_files / llm_query / " +
+      "llm_query_batched / llm_query_chunked (rlm_query for iterative sub-tasks) — stdout " +
+      "returned to you is hard-capped at 4K chars, so printing file bodies is useless. " +
+      "Variables, imports, and the `answers`/`plan` memo persist across calls. Also supports " +
+      "add_context for external dirs/files/git URLs and document conversion.",
     promptSnippet:
-      "repl: run Python in a persistent sandbox holding the whole repository in `context`; " +
+      "repl: run Python in a persistent sandbox holding loaded files in `context`; " +
       "search/grep_context/outline to locate, map_files/llm_query* to read.",
     promptGuidelines: [
       "In RLM mode, read the repository through `repl` only — `read`/`grep` and bash readers are blocked.",
@@ -271,7 +283,7 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
         await deps.ensureContext?.();
         await sandboxManager.getOrCreate({
           ...subcallHandlers,
-          ...(libraryBundle?.handlers ?? {}),
+          ...(contextBundle?.handlers ?? {}),
         });
 
         // Detect queue contention AFTER sandbox init (initPromise settled, isExecuting now accurate)

package/src/tool/rlm-tool.ts

@@ -31,7 +31,7 @@ const CALL_PREVIEW_CHARS = 80;
 
 export const RlmToolParams = Object.freeze(Type.Object({
   prompt: Type.String({ description: "The task or question for the RLM engine" }),
-  context: Type.Optional(Type.String({ description: "Optional context. If omitted, repo is auto-packed via repomix." })),
+  context: Type.Optional(Type.String({ description: "Optional context. If omitted, the working directory is packed into context." })),
 }));
 
 // ── Rendering helpers ──

package/src/ui/config-panel.ts

@@ -20,7 +20,8 @@ const CHOICES = Object.freeze({
   rootSamplingMaxTokens: Object.freeze(["4096", "8192", "16384", "32768"]),
   sandboxInitTimeoutMs: Object.freeze(["10000", "30000", "60000", "120000"]),
   requestTimeoutMs: Object.freeze(["2", "5", "10", "20"]),
-  libraryLoader: Object.freeze(["on", "off"]),
+  contextLoader: Object.freeze(["on", "off"]),
+  autoSeedCwd: Object.freeze(["on", "off"]),
 });
 
 function item(id: string, label: string, currentValue: string, values: readonly string[], description: string): SettingItem {
@@ -49,8 +50,10 @@ export async function showConfigPanel(ctx: ExtensionContext, config: RlmConfig):
     item("rootSamplingMaxTokens", "Root model output cap (tok)", String(config.rootSampling?.maxTokens ?? 16384), CHOICES.rootSamplingMaxTokens, "Max output tokens per root-model turn. Lower values keep each turn lean."),
     item("sandboxInitTimeoutMs", "Sandbox init timeout", String(config.sandboxInitTimeoutMs), CHOICES.sandboxInitTimeoutMs, "How long to wait for the Python worker to start."),
     item("requestTimeoutMs", "Sandbox request timeout (min)", String(Math.round(config.requestTimeoutMs / 60_000)), CHOICES.requestTimeoutMs, "Parent-side watchdog per sandbox request; on breach the Python worker is killed."),
-    item("libraryLoader", "Library loader", config.libraryLoader ? "on" : "off", CHOICES.libraryLoader,
-      "Allow load_library() to pull an external dir, file, or git repo into the shared context list."),
+    item("contextLoader", "Context loader", config.contextLoader ? "on" : "off", CHOICES.contextLoader,
+      "Allow add_context() to pull an external dir, file, document, or git repo into context."),
+    item("autoSeedCwd", "Auto-seed cwd", config.autoSeedCwd ? "on" : "off", CHOICES.autoSeedCwd,
+      "Seed the working directory into context on the first repl() call (otherwise starts empty)."),
     item("__save__", "Save & close", "↵", ["↵"], "Save these settings and close (Esc also saves)."),
   ];
 
@@ -104,7 +107,8 @@ export function applySetting(config: RlmConfig, id: string, value: string): RlmC
       return Object.freeze({ ...config, rootSampling: Object.freeze({ ...config.rootSampling, maxTokens: Number(value) }) });
     case "sandboxInitTimeoutMs": return Object.freeze({ ...config, sandboxInitTimeoutMs: Number(value) });
     case "requestTimeoutMs": return Object.freeze({ ...config, requestTimeoutMs: Number(value) * 60_000 });
-    case "libraryLoader": return Object.freeze({ ...config, libraryLoader: value === "on" });
+    case "contextLoader": return Object.freeze({ ...config, contextLoader: value === "on" });
+    case "autoSeedCwd": return Object.freeze({ ...config, autoSeedCwd: value === "on" });
     default: return config;
   }
 }