@hicaru/pi-rlm 0.1.7 → 0.1.9

package/src/index.ts

@@ -7,8 +7,6 @@ import { registerRlmCommand } from "./commands/rlm.ts";
 import { registerRlmConfigCommand } from "./commands/rlm-config.ts";
 import { createRlmTool } from "./tool/rlm-tool.ts";
 import { createReplTool } from "./tool/repl-tool.ts";
-import { createApplyEditsTool } from "./tool/apply-edits-tool.ts";
-import { EditRegistry } from "./registry/edit-registry.ts";
 import { loadSettings, mergeConfig, resolveModelId } from "./config/settings.ts";
 import { RlmController, cheapestModel } from "./mode/rlm-mode.ts";
 import { postRlmGuide } from "./ui/intro.ts";
@@ -26,14 +24,14 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   // Init synchronously with defaults — ensures commands/tools/handlers register before session_start
   const config = mergeConfig({});
   const controller = new RlmController(config);
-  const editRegistry = new EditRegistry();
+  let onSandboxDiscardExtra: (() => void) | undefined;
   const sandboxManager = new SandboxManager({
     execTimeoutS: config.execTimeoutS,
     requestTimeoutMs: config.requestTimeoutMs,
     python: config.python,
     sandboxInitTimeoutMs: config.sandboxInitTimeoutMs,
     maxPromptChars: config.maxPromptChars,
-    onSandboxDiscarded: () => { editRegistry.clear(); },
+    onSandboxDiscarded: () => { onSandboxDiscardExtra?.(); },
   });
   let packedContextText: string | undefined;
   let contextPackPromise: Promise<string | undefined> | undefined;
@@ -81,7 +79,6 @@ export default function rlmExtension(pi: ExtensionAPI): void {
 
   // ── Tool registration ──
   pi.registerTool(createRlmTool(controller));
-  pi.registerTool(createApplyEditsTool(editRegistry));
   let guidePosted = false;
 
   pi.on("session_start", async (_event, ctx) => {
@@ -105,8 +102,8 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           getModel: () => controller.resolveModels(ctx)?.model,
           getWorkerModel: () => controller.resolveModels(ctx)?.worker,
           registry: ctx.modelRegistry,
-          editRegistry,
           config: controller.config,
+          registerDiscardHook: (reset) => { onSandboxDiscardExtra = reset; },
           ensureContext: async () => {
             const contextText = await ensureRepositoryContext(ctx.cwd ?? process.cwd());
             if (contextText === undefined) throw new Error("repository context could not be loaded into RLM sandbox");

package/src/mode/native-guards.ts

@@ -86,7 +86,7 @@ export function replDelegationNudge(stdoutChars: number, delegated: boolean): st
   if (delegated || stdoutChars <= NUDGE_STDOUT_CHARS) return undefined;
   return (
     `\n[RLM: this repl() printed ${stdoutChars.toLocaleString()} chars with 0 sub-LLM calls — ` +
-    "delegate semantic reading via llm_query / llm_query_batched / llm_query_chunked instead of " +
-    "reading output yourself.]"
+    "if you were READING, delegate via llm_query / llm_query_batched / llm_query_chunked. " +
+    "Authoring an edit body yourself is correct and needs no delegation.]"
   );
 }

package/src/prompts/phases.ts

@@ -0,0 +1,104 @@
+/**
+ * Per-phase guidance for the gated RLM pipeline.
+ * Injected at each phase boundary; the only channel between phases is durable
+ * artifacts under .rlm/artifacts/.
+ */
+import type { Phase } from "../core/pipeline.ts";
+
+const CLARIFY_GUIDANCE = Object.freeze([
+  "## Clarify phase (intake interview)",
+  "Interview the user until the task is understood. The engine COUNTS ask_user_question",
+  "rounds it services — you cannot advance without having actually asked at least once.",
+  "",
+  "1. Intent first: ask ONE open-ended intent question (what problem, who hits it, what",
+  "   success looks like). Options are answer *shapes* (e.g. end user / maintainer / operator);",
+  "   do NOT mark a Recommended option. The automatic Other / free-text path carries the real framing.",
+  "   Up to 2 more intent rounds if the answer still cannot scope a narrow probe; then proceed",
+  "   with what you have.",
+  "2. Probe before asking more: ground follow-ups in the REPL (deterministic search over",
+  "   context, a few llm_query reads) so questions cite real code as file:line.",
+  "3. Confirm inferences, don't record them: batch inferred decisions into one call —",
+  "   \"From the code I inferred <behavior> (file:line). Keep or change?\" The user's answer",
+  "   is the Decision, not your inference.",
+  "4. Scope / shape / detail rounds, one at a time: recommended option first; architecture",
+  "   (shape) options must state the tradeoff (\"optimizes X, costs Y\") — never one option",
+  "   masquerading as a choice; 2–4 independent detail questions may batch in one call.",
+  "5. Classify answers: Decision → record; Correction → re-probe that seam, re-ask dependents;",
+  "   Defer → ## Open Questions.",
+  "6. Terminate on depth, not politeness: stop when every raised branch has a Decision or a",
+  "   Deferral and ## Problem & Intent holds the user's own words verbatim. Do not pad the",
+  "   interview; do not ask a final \"looks good?\" rubber-stamp.",
+  "7. Then save_artifact(\"clarification\", content) with frontmatter:",
+  "     status: ready",
+  "     decisions_count: N",
+  "     open_questions_count: M",
+  "   and body sections:",
+  "     ## Problem & Intent  (user's words VERBATIM)",
+  "     ## Decisions         (one '- ' bullet per decision)",
+  "     ## Open Questions    (one '- ' bullet per deferral; may be empty with count 0)",
+  "     ## Non-Goals",
+  '   Then advance_phase("research", summary).',
+].join("\n"));
+
+const RESEARCH_GUIDANCE = Object.freeze([
+  "## Research phase",
+  "Read the clarifications artifact (if present) and honor recorded Decisions; do not silently",
+  "resolve Open Questions.",
+  "Probe the repository, delegate long reads via `llm_query_batched` / `llm_query_chunked`.",
+  "Every factual claim about the code MUST be cited as `path/file.ext:LINE` (or `LINE-LINE`).",
+  "The engine VERIFIES citations against the working tree — unbacked citations reject advance.",
+  "When research is complete, write ONE research document with a `## Findings` section and call:",
+  '  `save_artifact("research", content)`  # frontmatter must include `status: ready`',
+  '  `advance_phase("blueprint", summary)`',
+  "Do not implement code in this phase.",
+].join("\n"));
+
+const BLUEPRINT_GUIDANCE = Object.freeze([
+  "## Blueprint phase",
+  "Read the clarifications artifact (if present) and plan only within recorded Decisions;",
+  "Open Questions that would block the design must be re-asked via ask_user_question, not assumed.",
+  'Produce ONE plan document and save it with `save_artifact("plan", content)`.',
+  "This pipeline is read-only: it produces a plan a human or a native-mode agent executes;",
+  "do not write source files here (sandbox write modes are blocked).",
+  "Write changes as exact, copy-pasteable before/after code — never as prose instructions.",
+  "The ENGINE derive-checks the document — these are hard gates, not suggestions:",
+  "- frontmatter: `status: ready`, `phase_count: N`, `phases: [{n: 1, title: ...}, ...]`",
+  "- `phases:` / `phase_count` MUST match the `## Phase N:` body headings exactly (fenced examples ignored)",
+  "- every `file:line` citation MUST resolve against the working tree at this revision",
+  "Each `## Phase N: <title>` section contains:",
+  "- `### Changes Required` — per file: path + the exact intended change",
+  "- `### Success Criteria` — `#### Automated Verification:` (runnable commands) and",
+  "  `#### Manual Verification:` checklists",
+  "Phases must be independently implementable in order, each leaving the tree working.",
+  'When ready: `advance_phase("validate", summary)`.',
+].join("\n"));
+
+const VALIDATE_GUIDANCE = Object.freeze([
+  "## Validate phase (adversarial plan review)",
+  "Nothing has been implemented — you are reviewing the PLAN, not a diff.",
+  "Read the goal artifact (verbatim brief), the clarifications artifact (recorded Decisions),",
+  "and the plan. For each plan phase check against the working tree:",
+  "- every cited `file:line` still resolves and says what the plan claims",
+  "- every file the phase edits exists (or is created by an earlier phase)",
+  "- no phase contradicts a recorded Decision or silently resolves an Open Question",
+  "- the Success Criteria are actually runnable and actually prove the change",
+  "- phases are independently implementable in the stated order",
+  "Write ONE review via `save_artifact(\"validation\", content)` with frontmatter:",
+  "- `status: ready`",
+  "- `blockers_count: <int >= 0>`  # MEASURED — routing key; not prose",
+  "- `verdict: pass | fail`  # pass requires blockers_count === 0",
+  "Each blocker needs a resolvable `file:line` citation.",
+  "Then finalize: `answer[\"content\"] = <the reviewed plan + review summary>; answer[\"ready\"] = True`.",
+  "If `blockers_count > 0`, the engine re-enters blueprint (bounded by maxBackwardJumps).",
+].join("\n"));
+
+const GUIDANCE: Readonly<Record<Phase, string>> = Object.freeze({
+  clarify: CLARIFY_GUIDANCE,
+  research: RESEARCH_GUIDANCE,
+  blueprint: BLUEPRINT_GUIDANCE,
+  validate: VALIDATE_GUIDANCE,
+});
+
+export function phaseGuidance(phase: Phase): string {
+  return GUIDANCE[phase];
+}

package/src/prompts/system.ts

@@ -20,6 +20,7 @@ export interface SystemPromptOptions {
   readonly todo?: boolean;
   readonly pipeline?: boolean;
   readonly maxPromptChars?: number;
+  readonly libraryLoader?: boolean;
 }
 
 export type ContextKind = "files" | "text";
@@ -76,7 +77,14 @@ function howToRunCode(): string {
   ].join(" ");
 }
 
-function replGlossary(kind: ContextKind, recursion: boolean, askUserQuestion: boolean, todo: boolean, pipeline: boolean): string {
+function replGlossary(
+  kind: ContextKind,
+  recursion: boolean,
+  askUserQuestion: boolean,
+  todo: boolean,
+  pipeline: boolean,
+  libraryLoader: boolean,
+): string {
   const lines = ["Available in the REPL:"];
   if (kind === "text") {
     lines.push(
@@ -116,8 +124,9 @@ function replGlossary(kind: ContextKind, recursion: boolean, askUserQuestion: bo
       "- `ask_user_question(questions: list[dict]) -> list[dict]`: pause and present the user",
       "  with 1-4 structured questions. Each question: {question, header, options: [{label, description}],",
       "  multiSelect?}. Returns list of {question, selected: [label], custom?}.",
-      "  Use when you have 2-4 concrete options from your analysis and need a decision before proceeding.",
-      "  DO NOT ask open-ended chat questions — use concrete options grounded in code/data.",
+      "  Default: use concrete options grounded in code/data (2–4 choices, Recommended first when ranking).",
+      "  Exception — clarify-phase intent rounds: lead with an open-ended intent question whose options",
+      "  are answer *shapes* (not a Recommended pick); free-text / Other carries the real framing.",
       "  Only valid at root depth; returns an error inside rlm_query sub-calls.",
     );
   }
@@ -130,6 +139,25 @@ function replGlossary(kind: ContextKind, recursion: boolean, askUserQuestion: bo
       "  Use to plan multi-step work before starting, then mark tasks as you complete them.",
     );
   }
+  if (libraryLoader) {
+    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.",
+      "",
+      "  ```python",
+      "  info = load_library(\"/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\"])]",
+      "  ```",
+    );
+  }
   if (recursion) {
     lines.push(
       "- `rlm_query(prompt, model=None)` / `rlm_query_batched(prompts, model=None)`: recursive RLM",
@@ -148,9 +176,16 @@ function replGlossary(kind: ContextKind, recursion: boolean, askUserQuestion: bo
   }
   if (pipeline) {
     lines.push(
-      "- `advance_phase(phase: str, summary=None) -> str`: transition the root RLM pipeline to the next phase.",
-      "  Valid phases in order: 'research' → 'blueprint' → 'implement' → 'validate'. You must advance forward",
-      "  one phase at a time. Only callable at the root depth; returns an error in sub-RLM contexts.",
+      "- `save_artifact(kind: str, content: str) -> str`: persist a stage artifact under `.rlm/artifacts/`.",
+      "  Kinds: `'clarification'` | `'research'` | `'plan'` | `'validation'`. Must match the current phase.",
+      "  Frontmatter must eventually include `status: ready` before `advance_phase` will accept the transition.",
+      "- `advance_phase(phase: str, summary=None) -> str`: transition to the next pipeline phase.",
+      "  Order: 'clarify' → 'research' → 'blueprint' → 'validate' (one step at a time;",
+      "  clarify is skipped when ask_user_question is disabled). The pipeline is READ-ONLY.",
+      "  **advance_phase is validated by the engine** — it measures the latest saved artifact",
+      "  (status, structure, citations, blockers_count; clarify also requires ≥1 ask_user_question round).",
+      "  A rejected transition returns the gate error for you to fix; the phase does NOT advance.",
+      "  Only callable at root depth.",
     );
   }
   lines.push(
@@ -197,7 +232,10 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
     "",
     howToRunCode(),
     "",
-    replGlossary(kind, recursion, opts.askUserQuestion ?? false, opts.todo ?? false, opts.pipeline ?? false),
+    replGlossary(
+      kind, recursion, opts.askUserQuestion ?? false, opts.todo ?? false,
+      opts.pipeline ?? false, opts.libraryLoader ?? false,
+    ),
     "",
     "REPL stdout over ~800 characters is truncated to a short excerpt — large results stay in your",
     "REPL variables as buffers. Re-print only the slice you need (e.g. `print(result[:500])`); never",
@@ -232,8 +270,8 @@ function nativeReplGlossary(): string {
     "- `rlm_query_batched(prompts, model=None) -> list[str]` — concurrent recursive RLM calls.",
     "",
     "- `todo(action, **kwargs) -> str` — manage a task list. Actions: create, update, list, get, delete, clear. Statuses: pending → in_progress → completed.",
+    "- `load_library(source) -> dict`: append external dir/file/git tree into `context` under `lib/<id>/…`. Return is metadata only — always use `context`.",
     "- `SHOW_VARS() -> str` — list all variables currently in the REPL.",
-    "- `stage_edit(path, old_text, new_text) -> str`: stages an edit and returns an edit ID; apply IDs with `apply_edits`.",
     "- `answer`: dict `{\"content\": \"\", \"ready\": False}`. Setting `answer[\"ready\"] = True` delivers it to the user; do not restate it.",
     "",
     "### Orchestrator Pattern",
@@ -262,18 +300,19 @@ function nativeReplGlossary(): string {
     "|------|------|",
     "| `repl({code})` | Need to chunk/delegate `context` to sub-LLMs; need Python scripting; need REPL state across calls |",
     "| `zebra-mcp` | Semantic search over the codebase |",
-    "| `edit` | Native Pi edit tool; prefer `stage_edit` + `apply_edits` from REPL for file changes in native RLM mode |",
-    "| `write` | Create a new file (native Pi flow, visible to all plugins) |",
+    "| `edit` | Change an existing file. Compose oldText/newText yourself; exact match required |",
+    "| `write` | Create a new file |",
     "| `llm_query` (inside repl) | Extract, summarize, or classify a chunk of text |",
     "| `rlm_query` (inside repl) | Complex sub-task needing iterative reasoning with its own REPL |",
     "| `todo` (inside repl) | Track multi-step progress visibly to the user |",
-    "| `stage_edit(path, old, new)` (inside repl) | Stage exact edit params; apply returned IDs with `apply_edits` |",
     "",
     "### Workflow",
     "1. **Plan**: Create todos for the multi-step analysis. Probe `context` — print length, inspect a few entries.",
     "2. **Chunk & Delegate**: Slice `context` into batches, delegate each batch to sub-LLMs via `llm_query_batched`.",
     "3. **Aggregate**: Collect results in Python, pass aggregated results to a final `llm_query` or produce the answer directly.",
-    "4. **Finalize**: For file changes, stage them inside repl() via `stage_edit(path, old, new)`, then apply the returned IDs with `apply_edits({ ids })`. Do not use the native `edit` tool directly for native RLM file changes unless explicitly asked. For analysis tasks, write a normal message.",
+    "4. **Finalize**: For file changes, call the native `edit` / `write` tools directly — you",
+    "   author the change, and Pi validates the anchor and renders the diff. For analysis tasks,",
+    "   write a normal message.",
     "",
     "### Task-Specific Patterns",
     LARGE_FILE_RULE_NATIVE,
@@ -305,9 +344,11 @@ export function buildNativeSystemPrompt(): string {
     "All file content is pre-loaded in the REPL `context` variable. Use ONLY `repl({code})`.",
     "If sub-LLM credits are exhausted → report the error to the user and stop.",
     "",
-    "For file changes, prefer `stage_edit()` inside repl(); it returns edit IDs and keeps edit bodies out of your output.",
-    "When repl() returns STAGED_EDITS, apply them with `apply_edits({ ids: [\"e1\", ...] })`.",
-    "Never re-type file paths, oldText, newText, file bodies, or `answer[\"content\"]` in your own output.",
+    "AUTHORING RULE: sub-LLMs (`llm_query` family) READ — they extract, locate, and summarize.",
+    "They never author code you will ship. Once you know WHAT to change, compose the exact",
+    "oldText / newText yourself and apply it with `edit`. Delegated code is written by a small",
+    "model with no view of the codebase; it is a research aid, never a patch.",
+    "Never re-type file bodies or `answer[\"content\"]` in your own output.",
     "",
     nativeReplGlossary(),
   ].join("\n");
@@ -326,7 +367,9 @@ export const NATIVE_TURN_REMINDER = [
   "repl() stdout to you is hard-capped at 4K chars; read/grep and bash readers are blocked.",
   "Any SEMANTIC reading of file/text content MUST go through llm_query / llm_query_batched /",
   "llm_query_chunked (rlm_query for iterative sub-tasks). Deterministic Python (search, count,",
-  "slice, json) is free. Keep your own output to decisions and aggregation.]",
+  "slice, json) is free. AUTHORING IS NOT READING: you write every edit body yourself and apply",
+  "it with the native `edit` / `write` tools — never delegate code you will ship to a sub-LLM.",
+  "Keep your own output to decisions, authored edits, and aggregation.]",
 ].join("\n");
 
 /** The one-line context metadata, also reused by the per-turn prompt in headless mode. */

package/src/prompts/user.ts

@@ -3,16 +3,24 @@
  * Native mode does not use these — pi's own loop supplies the turns.
  */
 
-export function buildTurnPrompt(iteration: number, maxIterations: number, gateMessage?: string): string {
+export function buildTurnPrompt(
+  iteration: number,
+  maxIterations: number,
+  gateMessage?: string,
+  phaseGuidanceText?: string,
+): string {
+  const parts: string[] = [];
+  if (phaseGuidanceText) parts.push(phaseGuidanceText);
+  if (gateMessage) parts.push(gateMessage);
+  const prefix = parts.length > 0 ? `${parts.join("\n\n")}\n\n` : "";
   const body = `Turn ${iteration + 1}/${maxIterations}:`;
-  const gate = gateMessage ? `\n${gateMessage}\n\n` : "";
   if (iteration === 0) {
     return (
       "You have not interacted with the REPL or seen your context yet. Look at the context first; " +
-      `do not provide a final answer yet.\n\n${gate}${body}`
+      `do not provide a final answer yet.\n\n${prefix}${body}`
     );
   }
-  return `${gate}${body}`;
+  return `${prefix}${body}`;
 }
 
 /** Asked once when the engine runs out of turns without a submitted answer. */

package/src/sandbox/protocol.ts

@@ -21,18 +21,21 @@ export interface LlmReply {
   readonly response?: string;
   readonly responses?: readonly string[];
   readonly answers?: readonly AskAnswer[];
+  /** load_library reply: temp file with the packed payload (+ resume index / namespace). */
+  readonly path?: string;
+  readonly json?: boolean;
+  readonly index?: number;
+  readonly files?: number;
+  readonly chars?: number;
+  readonly source_id?: string;
+  readonly path_prefix?: string;
+  /** Host-side idempotency: library already loaded — no path payload. */
+  readonly already_loaded?: boolean;
   readonly error?: string;
 }
 
 export type ParentMessage = WorkerRequest | LlmReply;
 
-export interface ProposedEdit {
-  readonly id: string;
-  readonly path: string;
-  readonly oldText: string;
-  readonly newText: string;
-}
-
 /** A normal response to a request (keyed by the request `id`). */
 export interface WorkerResponse {
   readonly id: string;
@@ -43,7 +46,6 @@ export interface WorkerResponse {
   readonly stderr?: string;
   readonly final_answer?: string | null;
   readonly answer_content?: string;
-  readonly edits?: readonly ProposedEdit[];
   readonly raised?: boolean;
   readonly execution_time?: number;
   // user-created variable names after this exec (filters builtins/context) — Metadata(stdout) for history orientation
@@ -62,8 +64,10 @@ export type InterruptKind =
   | "rlm_query"
   | "rlm_query_batched"
   | "advance_phase"
+  | "save_artifact"
   | "ask_user_question"
-  | "todo";
+  | "todo"
+  | "load_library";
 
 export interface AskOption {
   readonly label: string;
@@ -111,6 +115,12 @@ interface AdvancePhaseInterrupt extends InterruptBase {
   readonly summary?: string;
 }
 
+interface SaveArtifactInterrupt extends InterruptBase {
+  readonly type: "save_artifact";
+  readonly artifactKind?: string;
+  readonly content?: string;
+}
+
 export interface AskUserQuestionInterrupt extends InterruptBase {
   readonly type: "ask_user_question";
   readonly questions: readonly AskQuestion[];
@@ -132,13 +142,20 @@ export interface TodoInterrupt extends InterruptBase {
   readonly includeDeleted?: boolean;
 }
 
+export interface LoadLibraryInterrupt extends InterruptBase {
+  readonly type: "load_library";
+  readonly source?: string;
+}
+
 /** A mid-exec sub-LLM/tool request from the worker. */
 export type WorkerInterrupt =
   | PromptInterrupt
   | BatchedPromptInterrupt
   | AdvancePhaseInterrupt
+  | SaveArtifactInterrupt
   | AskUserQuestionInterrupt
-  | TodoInterrupt;
+  | TodoInterrupt
+  | LoadLibraryInterrupt;
 
 export type WorkerMessage = WorkerResponse | WorkerInterrupt;
 
@@ -148,8 +165,10 @@ export const INTERRUPT_KINDS = Object.freeze(new Set<InterruptKind>([
   "rlm_query",
   "rlm_query_batched",
   "advance_phase",
+  "save_artifact",
   "ask_user_question",
   "todo",
+  "load_library",
 ]));
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -178,7 +197,6 @@ export interface ReplResult {
   readonly stderr: string;
   readonly finalAnswer: string | null;
   readonly answerContent: string;
-  readonly edits: readonly ProposedEdit[];
   readonly raised: boolean;
   readonly executionTimeMs: number;
   /** User-created variable names after this exec (builtins/context filtered out). */

package/src/sandbox/sandbox.ts

@@ -26,6 +26,18 @@ import {
 } from "./protocol.ts";
 import { 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>/
+  readonly index: number;        // resume-sidecar index (not a REPL var name); -1 if alreadyLoaded
+  readonly files?: number;
+  readonly chars: number;
+  readonly sourceId: string;
+  readonly pathPrefix: string;
+  /** Host already has this library — no pack, no sidecar, empty payload. */
+  readonly alreadyLoaded?: boolean;
+}
+
 /** Handlers the bridge installs to service sub-LLM interrupts. Return the reply payload. */
 export interface SubLlmHandlers {
   llmQuery(prompt: string, model: string | null, depth: number): Promise<string>;
@@ -33,8 +45,10 @@ export interface SubLlmHandlers {
   rlmQuery(prompt: string, model: string | null, depth: number): Promise<string>;
   rlmQueryBatched(prompts: readonly string[], model: string | null, depth: number): Promise<string[]>;
   advancePhase(phase: string, summary: string | undefined, depth: number): Promise<string>;
+  saveArtifact(kind: string, content: string, depth: number): Promise<string>;
   askUserQuestion(questions: readonly AskQuestion[], depth: number): Promise<AskAnswer[]>;
   todo(action: string, params: Record<string, unknown>, depth: number): Promise<string>;
+  loadLibrary(source: string, depth: number): Promise<LibraryLoadResult>;
 }
 
 export interface SandboxOptions {
@@ -54,6 +68,11 @@ export interface SandboxOptions {
   readonly initTimeoutMs?: number;
   /** Sub-LLM prompt cap (chars) — sizes llm_query_chunked chunks inside the worker. */
   readonly maxPromptChars?: number;
+  /**
+   * When true, the worker rejects open() write modes (pipeline read-only runs).
+   * Native repl() data work leaves this false so scratch-file writes still work.
+   */
+  readonly readOnly?: boolean;
 }
 
 const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), "worker.py");
@@ -76,12 +95,14 @@ const REJECT: SubLlmHandlers = {
   rlmQuery: async () => formatError("sub-LLM bridge not configured"),
   rlmQueryBatched: async (p) => p.map(() => formatError("sub-LLM bridge not configured")),
   advancePhase: async () => formatError("phase advancement not available"),
+  saveArtifact: async () => formatError("save_artifact not available"),
   askUserQuestion: async (questions) => questions.map((q) => ({
     question: q.question,
     selected: [],
     custom: formatError("ask_user_question not configured"),
   })),
   todo: async () => formatError("todo not configured"),
+  loadLibrary: async () => { throw new Error("load_library not configured"); },
 };
 
 /** Distributive omit so each union member keeps its own fields (plain Omit collapses to shared keys). */
@@ -120,6 +141,9 @@ export class PythonSandbox {
     if (opts.maxPromptChars !== undefined) {
       workerArgs.push("--max-prompt-chars", String(opts.maxPromptChars));
     }
+    if (opts.readOnly) {
+      workerArgs.push("--read-only");
+    }
     this.proc = spawn(
       python,
       workerArgs,
@@ -200,7 +224,6 @@ export class PythonSandbox {
       stderr: res.stderr ?? "",
       finalAnswer: res.final_answer ?? null,
       answerContent: res.answer_content ?? "",
-      edits: res.edits ?? [],
       raised: res.raised ?? false,
       executionTimeMs: Math.round((res.execution_time ?? 0) * 1000),
       varNames: res.var_names ?? [],
@@ -285,6 +308,15 @@ export class PythonSandbox {
     }
   }
 
+  /**
+   * Refresh the parent-side request watchdog for every pending request.
+   * Used during long mid-exec work that does not
+   * produce additional worker interrupts on this sandbox.
+   */
+  refreshWatchdog(): void {
+    this.touchPending();
+  }
+
   private send(msg: ParentMessage): void {
     this.proc.stdin.write(`${JSON.stringify(msg)}\n`);
   }
@@ -346,6 +378,9 @@ export class PythonSandbox {
       } else if (msg.type === "advance_phase") {
         const response = await h.advancePhase(msg.phase ?? "", msg.summary, d);
         this.reply(msg.rid, { response });
+      } else if (msg.type === "save_artifact") {
+        const response = await h.saveArtifact(msg.artifactKind ?? "", msg.content ?? "", d);
+        this.reply(msg.rid, { response });
       } else if (msg.type === "ask_user_question") {
         const answers = await h.askUserQuestion(msg.questions ?? [], d);
         this.reply(msg.rid, { answers });
@@ -355,13 +390,53 @@ export class PythonSandbox {
         );
         const response = await h.todo(msg.action ?? "list", params, d);
         this.reply(msg.rid, { response });
+      } else if (msg.type === "load_library") {
+        const lib = await h.loadLibrary(msg.source ?? "", d);
+        if (lib.alreadyLoaded) {
+          // No temp file — worker short-circuits on already_loaded.
+          this.reply(msg.rid, {
+            already_loaded: true,
+            index: lib.index,
+            files: 0,
+            chars: lib.chars,
+            source_id: lib.sourceId,
+            path_prefix: lib.pathPrefix,
+          });
+        } else {
+          const isJson = typeof lib.payload !== "string";
+          const path = await this.writeContextFile(lib.payload, isJson);
+          // Worker reads then unlinks (worker._load_library). Host must not unlink here —
+          // if the worker is SIGKILLed before os.remove, the temp file leaks in tmpdir (acceptable).
+          this.reply(msg.rid, {
+            path,
+            json: isJson,
+            index: lib.index,
+            files: lib.files,
+            chars: lib.chars,
+            source_id: lib.sourceId,
+            path_prefix: lib.pathPrefix,
+          });
+        }
       }
     } catch (err) {
       this.reply(msg.rid, { error: err instanceof Error ? err.message : String(err) });
     }
   }
 
-  private reply(rid: string, body: { response?: string; responses?: string[]; answers?: AskAnswer[]; error?: string }): void {
+  private reply(rid: string, body: {
+    response?: string;
+    responses?: string[];
+    answers?: AskAnswer[];
+    path?: string;
+    json?: boolean;
+    index?: number;
+    files?: number;
+    chars?: number;
+    source_id?: string;
+    path_prefix?: string;
+    already_loaded?: boolean;
+    error?: string;
+  }): void {
     if (!this.disposed) this.send({ type: "llm_reply", rid, ...body });
   }