@hicaru/pi-rlm 0.2.1 → 0.2.2

package/src/core/types.ts

@@ -1,8 +1,6 @@
 /** Shared configuration + runtime types for the RLM engine. */
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
-import type { AskAnswer, AskQuestion } from "../sandbox/protocol.ts";
-import type { ReconstructResult } from "../state/resume.ts";
 
 export interface Sampling {
   readonly maxTokens?: number;
@@ -10,17 +8,6 @@ export interface Sampling {
   readonly reasoning?: ThinkingLevel;
 }
 
-export interface RunLogConfig {
-  /** Default: true — always-on, opt-out. */
-  readonly enabled?: boolean;
-  /** Default: ".rlm/runs". Directory under cwd for run artifacts. */
-  readonly dir?: string;
-  /** Default: true — whether to write sandbox.pkl snapshots. */
-  readonly snapshot?: boolean;
-  /** Default: 50 — prune oldest runs beyond this count on each new run. */
-  readonly maxRuns?: number;
-}
-
 export interface RlmConfig {
   /** Persistent editor-routing mode; when enabled, plain interactive prompts use RLM. */
   readonly enabled: boolean;
@@ -34,10 +21,11 @@ export interface RlmConfig {
   readonly requestTimeoutMs: number;
   /** Concurrency pool for *_batched sub-calls. */
   readonly maxConcurrentSubcalls: number;
+  /** Concurrent recursive child engines admitted per depth. Lower than maxConcurrentSubcalls:
+   *  each child is a Python subprocess holding its own copy of the inherited context. */
+  readonly maxConcurrentChildren: number;
   /** Reject sub-LLM prompts larger than this many chars. */
   readonly maxPromptChars: number;
-  /** Max USD spend across the whole tree before the engine stops (undefined = no cap). */
-  readonly maxBudgetUsd?: number;
   /** Max wall-clock ms across the whole tree before the engine stops (undefined = no cap). */
   readonly maxTimeoutMs?: number;
   /** Max total input+output tokens across the whole tree before the engine stops (undefined = no cap). */
@@ -46,10 +34,6 @@ export interface RlmConfig {
   readonly maxErrors?: number;
   /** Append the orchestrator addendum to the system prompt. */
   readonly orchestrator: boolean;
-  /** Enable the phase pipeline (advance_phase + stall nags) at depth 0. */
-  readonly pipeline: boolean;
-  /** Max validate→blueprint corrective re-entries when validation reports blockers (default 2). */
-  readonly maxBackwardJumps: number;
   /** Summarize the trajectory when it grows past the threshold (keeps the root window small). */
   readonly compaction: boolean;
   /** Compact when estimated history tokens reach this fraction of the model's context window. */
@@ -58,10 +42,6 @@ export interface RlmConfig {
   readonly python: string;
   /** Worker startup wait before treating sandbox init as failed (ms). */
   readonly sandboxInitTimeoutMs: number;
-  /** Allow ask_user_question() calls from the root REPL. */
-  readonly askUserQuestion: boolean;
-  /** Allow todo() calls from the REPL. */
-  readonly todo: boolean;
   /** Enable the load_library() REPL scaffold (external dirs/files/git repos as extra context slots). */
   readonly libraryLoader: boolean;
   /** ThinkingLevel for the root smart model (set via /rlm-config). */
@@ -76,8 +56,6 @@ export interface RlmConfig {
   readonly subSystemPrompt?: string;
   /** Sampling for sub-LLM (worker) calls. */
   readonly subSampling: Readonly<Sampling>;
-  /** Optional run-state persistence configuration. Enabled by default. */
-  readonly runLog?: RunLogConfig;
 }
 
 /** Input to a (headless) RLM run. */
@@ -92,12 +70,8 @@ export interface RlmInput {
   readonly parentNodeId?: string;
   /** "provider/id" — overrides the root model for this run (set by recursive rlm_query). */
   readonly modelOverride?: string;
-  /** Remaining budget for this subtree (set by parent from its LimitGuard). */
-  readonly remainingBudgetUsd?: number;
   /** Remaining timeout for this subtree (set by parent from its LimitGuard). */
   readonly remainingTimeoutMs?: number;
-  /** Depth-0 resume payload — controller rebuilds this from the trail's `reconstructRlmState()`. */
-  readonly resume?: ReconstructResult & { readonly ok: true };
 }
 
 /** Result of a completed RLM run. */
@@ -111,11 +85,4 @@ export interface RlmResult {
 }
 
 /** A function that runs an RLM to completion — used to wire recursion (rlm_query). */
-export interface InteractiveDeps {
-  /** Called when the sandbox issues ask_user_question; undefined = feature disabled. */
-  readonly onAskUserQuestion?: (questions: readonly AskQuestion[]) => Promise<AskAnswer[]>;
-  /** Called when the sandbox issues todo; undefined = feature disabled. */
-  readonly onTodo?: (action: string, params: Record<string, unknown>) => Promise<string>;
-}
-
 export type RunRlm = (input: RlmInput) => Promise<RlmResult>;

package/src/index.ts

@@ -7,7 +7,8 @@ import { registerRlmConfigCommand } from "./commands/rlm-config.ts";
 import { createRlmTool } from "./tool/rlm-tool.ts";
 import { createReplTool } from "./tool/repl-tool.ts";
 import { loadSettings, mergeConfig, resolveModelId } from "./config/settings.ts";
-import { RlmController, cheapestModel } from "./mode/rlm-mode.ts";
+import { RlmController } from "./mode/rlm-mode.ts";
+import { cheapestModel } from "./mode/llm-model.ts";
 import { postRlmGuide } from "./ui/intro.ts";
 import { setRlmModeStatus } from "./ui/status.ts";
 import { markdownTheme } from "./ui/theme-adapter.ts";
@@ -15,7 +16,7 @@ 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 { buildNativeSystemPrompt, NATIVE_TURN_REMINDER } from "./prompts/system.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";
 
@@ -42,9 +43,8 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   });
   // One admission gate for the whole session: spawn() lets the sandbox put many requests on
   // the wire at once, so nothing smaller than session scope actually bounds fan-out.
-  const gates = createSubcallGates(config.maxConcurrentSubcalls);
+  const gates = createSubcallGates(config.maxConcurrentSubcalls, config.maxConcurrentChildren);
   const background = new BackgroundTasks({
-    maxBudgetUsd: config.maxBudgetUsd,
     maxTimeoutMs: config.maxTimeoutMs,
     maxTokens: config.maxTokens,
     maxErrors: config.maxErrors,
@@ -79,7 +79,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   const settingsReady = loadSettings()
     .then((persisted) => {
       controller.config = mergeConfig(persisted.config);
-      controller.savedWorkerRef = persisted.worker;
+      controller.savedLlmRef = persisted.llm;
     })
     .catch((err) => {
       console.warn(`[rlm] settings load failed: ${errorMessage(err)}`);
@@ -120,22 +120,33 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     const flag = pi.getFlag("rlm");
     if (typeof flag === "boolean") controller.setConfig(Object.freeze({ ...controller.config, enabled: flag }));
 
-    if (controller.savedWorkerRef) {
-      const resolved = resolveModelId(ctx.modelRegistry, controller.savedWorkerRef);
-      if (resolved) controller.workerModel = resolved;
+    // Reload the catalog before the worker-model pick below reads it. Newer pi builds make
+    // `getAvailable()` an async-populated snapshot that starts empty, and picking from an empty
+    // catalog silently falls back to the root model. Called with no arguments and awaited so it
+    // is valid whether `refresh` returns void (current) or a promise (newer); fail-soft, because
+    // a refresh error must not abort session start.
+    try {
+      await ctx.modelRegistry.refresh();
+    } catch (err) {
+      console.warn(`[rlm] model registry refresh failed: ${errorMessage(err)}`);
+    }
+
+    if (controller.savedLlmRef) {
+      const resolved = resolveModelId(ctx.modelRegistry, controller.savedLlmRef);
+      if (resolved) controller.llmModel = resolved;
     }
 
     // Re-register repl tool each session to pick up model provider changes
-    const workerModel = controller.workerModel ?? cheapestModel(ctx.modelRegistry) ?? ctx.model;
+    const llmModel = controller.llmModel ?? cheapestModel(ctx.modelRegistry) ?? ctx.model;
     const model = ctx.model;
-    if (workerModel && model) {
+    if (llmModel && model) {
       try {
         pi.registerTool(createReplTool({
           sandboxManager,
           model,
-          workerModel,
+          llmModel,
           getModel: () => controller.resolveModels(ctx)?.model,
-          getWorkerModel: () => controller.resolveModels(ctx)?.worker,
+          getLlmModel: () => controller.resolveModels(ctx)?.llm,
           registry: ctx.modelRegistry,
           getConfig: () => controller.config,
           gates,

package/src/mode/llm-model.ts

@@ -0,0 +1,54 @@
+/**
+ * Sub-LLM model ranking — "cheapest available", with free models winning outright.
+ *
+ * Pi's `ModelCost` is non-nullable (`packages/ai/src/types.ts`), so a free model is a literal 0,
+ * not a null. That makes plain price sorting ambiguous rather than wrong: subscription and
+ * token-plan providers also publish 0, and a stable sort would hand back whichever 0-cost entry
+ * happened to be first in catalog order. The tie-breaks below are what actually pick a usable
+ * free model — and what make the pick identical across sessions and catalog reorderings.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+
+/** $/Mtok, input-weighted 3:1 — a sub-call sends a file body and gets back a sentence. */
+function priceOf(model: Model<Api>): number {
+  const { input, output, cacheRead } = model.cost;
+  return input * 3 + output + cacheRead;
+}
+
+/** True when the model costs nothing to call on any axis. */
+export function isFreeModel(model: Model<Api>): boolean {
+  return priceOf(model) === 0;
+}
+
+/**
+ * Negative when `a` is the better sub-LLM.
+ *
+ * Window before maxTokens before id: a free model with a 4K context is useless for bulk reading,
+ * so price alone must not decide. The final id comparison exists only to make the result
+ * deterministic — without it the pick drifts whenever a provider reorders its catalog.
+ */
+export function compareLlm(a: Model<Api>, b: Model<Api>): number {
+  return (priceOf(a) - priceOf(b))
+    || (b.contextWindow - a.contextWindow)
+    || (b.maxTokens - a.maxTokens)
+    || `${a.provider}/${a.id}`.localeCompare(`${b.provider}/${b.id}`);
+}
+
+/**
+ * Best sub-LLM among the models whose provider has configured auth.
+ *
+ * Single pass rather than `[...models].sort()[0]`: the copy and the sort both allocate for a
+ * result that is one element.
+ */
+export function cheapestModel(registry: ModelRegistry): Model<Api> | undefined {
+  const models = registry.getAvailable();
+  let best: Model<Api> | undefined;
+  for (let i = 0; i < models.length; i++) {
+    const model = models[i];
+    if (model === undefined) continue;
+    if (best === undefined || compareLlm(model, best) < 0) best = model;
+  }
+  return best;
+}

package/src/mode/rlm-mode.ts

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

package/src/prompts/glossary.ts

@@ -0,0 +1,287 @@
+/**
+ * The REPL vocabulary both prompts are built from.
+ *
+ * Headless (fenced ```repl``` blocks) and native (`repl({code})`) describe the same sandbox, so
+ * every line either lives here once or has an explicit condensed native twin next to it — that
+ * pairing is the whole reason this module exists. Divergence here is a bug: the model is told
+ * about functions that do not exist, or not told about ones that do.
+ */
+
+export type ContextKind = "files" | "text";
+
+/** "str" (raw string context, e.g. rlm_query children) → text; everything else → files. */
+export function contextKindOf(contextType: string): ContextKind {
+  return contextType === "str" ? "text" : "files";
+}
+
+export const DEFAULT_PROMPT_CAP = 400_000;
+
+export function promptCapTokensK(maxPromptChars: number): number {
+  return Math.round(maxPromptChars / 4_000);
+}
+
+/**
+ * Deterministic retrieval over `context` (headless + native).
+ *
+ * The paper's trajectories retrieve with hand-written regex (App. E.1); frontier models do that
+ * well, small ones guess keywords badly, and the first decomposition disproportionately decides
+ * the outcome (§5, Fig. 4a). These cost no tokens and no sub-calls.
+ */
+export const RETRIEVAL_GLOSSARY_LINES: readonly string[] = Object.freeze([
+  "- `search(query: str, k=10, path_glob=None)`: BM25 ranking over `context`. Returns",
+  "  [{path, line, score, snippet}] — POINTERS, not bodies. **Start here.** It is free:",
+  "  no sub-LLM call, no tokens. Use it before you guess at filenames or write regex.",
+  "- `grep_context(pattern, k=50, path_glob=None, before=0, after=0) -> dict`: regex over",
+  "  `context`. Returns {hits: [{path, line, text}], counts: {path: n}, total, truncated} —",
+  "  `counts` is complete even when `hits` is capped, so a wide pattern reports its shape",
+  "  instead of flooding you. Use for exact lexical needles; use `search` for meaning.",
+  "- `outline(path) -> str`: definition/heading skeleton of one file with line numbers.",
+  "  Orient in ~200 chars instead of printing 20K. Matches exact path, then suffix, then glob.",
+]);
+
+/** One-line delegation helpers — orchestrating must be cheaper than solving. */
+export const DELEGATION_GLOSSARY_LINES: readonly string[] = Object.freeze([
+  "- `map_files(files, prompt, model=None) -> dict[path, str]`: ask `prompt` of every file and",
+  "  get back {path: answer}. Accepts context entries or paths, packs them into cap-sized",
+  "  batched sub-calls, and splits oversized files automatically. **This is the default way to",
+  "  read many files** — prefer it over hand-rolling a chunk loop.",
+  "- `llm_map_reduce(items, map_prompt, reduce_prompt, model=None) -> str`: map over items in",
+  "  one batch, then reduce the partial answers with a single call. The paper's canonical",
+  "  strategy (query per chunk → aggregate the buffers) as one call.",
+]);
+
+/** Shared glossary entry for the chunked-query helper (headless + native). */
+export const CHUNKED_GLOSSARY_LINES: readonly string[] = Object.freeze([
+  "- `llm_query_chunked(text: str, prompt: str, model=None) -> list[str]`: auto-splits `text` into",
+  "  chunks that fit the sub-LLM prompt cap, fans them out concurrently (order preserved), and",
+  "  returns one answer per chunk. Use it for ANY text too large for a single `llm_query` — a file",
+  "  you open()ed, an oversized sub-result, or several concatenated context files.",
+]);
+
+/** Non-blocking fan-out: spawn now, collect later (headless glossary). */
+export const SPAWN_GLOSSARY_LINES: readonly string[] = Object.freeze([
+  "- `spawn(fn, *args) -> Task`: start `llm_query`, `llm_query_batched`, `llm_query_chunked`,",
+  "  `map_files`, `rlm_query` or `rlm_query_batched` WITHOUT waiting. Returns immediately.",
+  "  (Not `llm_map_reduce` — its reduce step depends on its own map results.)",
+  "- `rlm_await(task)` / `rlm_await_all(tasks) -> list`: collect results; order matches input.",
+  "  Tasks survive across turns, so spawn the slow work first, keep doing useful things, and",
+  "  await only when you actually need the results. `task.done` tells you if it has landed.",
+  "",
+  "  ```python",
+  "  # start the slow sub-agents, then keep working while they run",
+  "  tasks = [spawn(rlm_query, f\"Audit {area} end to end\") for area in areas]",
+  "  hits = [f for f in context if \"TODO\" in f[\"content\"]]   # overlaps with the sub-agents",
+  "  reports = rlm_await_all(tasks)",
+  "  ```",
+]);
+
+/**
+ * What a parent must know about the child it is about to spawn. Without this the model writes
+ * referential prompts ("read lib/x/src/…") on the assumption the child can go fetch them, which
+ * is what made a missing child context degrade silently instead of failing (issue #4).
+ */
+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,",
+  "  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",
+  "  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.",
+]);
+
+/**
+ * Sub-RLM orientation. Emitted only at depth > 0, where `context` is the parent's world rather
+ * 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.",
+]);
+
+/** 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.";
+
+/** The large-on-disk-file protocol (headless + native). */
+export const LARGE_FILE_RULE_LINES: readonly string[] = Object.freeze([
+  "**Large on-disk files (profiles, logs, dumps, generated JSON):** files >1MB or gitignored are",
+  "absent from `context`. Protocol:",
+  '1. Load in Python: `raw = open("dhat-heap.json").read()` — loading into a variable is fine.',
+  "2. Deterministic processing in Python (`json.load`, `re`, counting, aggregation) is fine and preferred.",
+  "3. The moment you need MEANING from raw text (summarize, explain, find anomalies), do NOT read it",
+  "   yourself — call `llm_query_chunked(raw, question)`, or slice + `llm_query_batched`.",
+  "4. Never print more than a small probe (~2K chars) of raw content.",
+  'Example: `parts = llm_query_chunked(raw, "Extract top allocation sites with byte totals")`, then',
+  "aggregate `parts` in Python or with one final `llm_query`.",
+]);
+
+/** Concise native-mode glossary line for the chunked helper (native prompt has a 6K budget). */
+export const CHUNKED_GLOSSARY_LINE_NATIVE =
+  "- `llm_query_chunked(text, prompt, model=None) -> list[str]` — auto-splits oversized text into cap-sized chunks, fans out concurrently; one answer per chunk.";
+
+/** Concise native-mode large-file rule (folds in the context-exclusion note; native 6K budget). */
+export const LARGE_FILE_RULE_NATIVE =
+  "- Files >1MB or gitignored are NOT in `context`: open() + parse deterministically in Python is fine; ANY semantic reading of the raw text goes through llm_query_chunked. Never print >2K chars raw.";
+
+/**
+ * The decomposition doctrine, ported from the RLM paper's Appendix C.3 `<env_tips>` and
+ * retargeted from competition math to repository analysis.
+ *
+ * This block is the single highest-leverage prompt intervention the paper reports: +69.5% on
+ * LongCoT-mini over the same RLM without it (Table 2). Plain RLM prompting alone actually
+ * *regressed* two of the five categories; the doctrine is what fixed them. Its purpose is to
+ * counter under-delegation — the model doing the work itself in the REPL instead of fanning out.
+ *
+ * Note the counterweight: `orchestratorAddendum` carries the anti-OVER-recursion batching rule.
+ * The paper is explicit (App. B) that one prompt does not port across models and that both
+ * guardrails are needed; keep them both.
+ */
+export const ENV_TIPS = [
+  "## Decomposition doctrine",
+  "",
+  "**Orchestrate; don't solve.** A single chain of thought over a large repository drifts —",
+  "you lose partials and compound mistakes. Your sub-LLMs are competent readers: given a",
+  "self-contained prompt and the text, they will extract, locate, classify, and summarize",
+  "reliably. Trust them; don't do their reading yourself.",
+  "",
+  "Your job: (1) find the relevant slice with `search` / `grep_context` / `outline`,",
+  "(2) delegate all semantic reading to `map_files` / `llm_query_batched` / `llm_map_reduce`,",
+  "(3) memoize every result you will reuse in `answers`, (4) sanity-check an answer before",
+  "another step depends on it, (5) assemble the final answer from `answers` by lookup.",
+  "Your own compute is: pointers, dict lookups, string formatting, and decisions.",
+  "",
+  "### The only state that matters",
+  "`answers` and `plan` are dicts that persist across every turn.",
+  "**If a value isn't in `answers`, it doesn't exist.** Do not trust a number from your own",
+  "earlier reasoning or from truncated stdout — context drifts. Memoize everything you reuse.",
+  "",
+  "### Shape of a run",
+  "1. Probe: `print(len(context))`, `search(<the user's question>)`. Do not print file bodies.",
+  "2. Plan: write the sub-questions into `plan`; each must be answerable from a named slice.",
+  "3. Fan out: one `map_files` / `llm_query_batched` per independent group, not one call per",
+  "   file. Store results into `answers` keyed by path or sub-question.",
+  "4. Assemble: build the answer from `answers`. Delegate the aggregation too if it is large.",
+  "",
+  "### Red flags — you are off track",
+  "- Printing file bodies to read them yourself → stop, delegate to `map_files`.",
+  "- Writing regex to *infer meaning* (naming conventions, intent, correctness) → that is a",
+  "  sub-LLM job. Regex is for exact lexical needles only.",
+  "- Two turns in with zero sub-LLM calls on an analysis task → you are solving it yourself.",
+  "- About to reuse a value that is not in `answers` → re-derive it and store it.",
+  "- One sub-call per file over dozens of files → batch them; fat prompts in small batches win.",
+].join("\n");
+
+/** Native-mode variant of the doctrine — same rules, sized for the native prompt budget. */
+export const ENV_TIPS_CONDENSED = [
+  "### Decomposition doctrine (paper App. C.3 — worth +69.5% there)",
+  "Orchestrate; don't solve. Loop: `search`/`grep_context`/`outline` to find the slice →",
+  "`map_files` / `llm_query_batched` to read it → memoize into `answers` → assemble by lookup.",
+  "`answers` and `plan` persist across every turn: **if a value isn't in `answers`, it",
+  "doesn't exist** — never reuse a number from your own earlier reasoning or truncated stdout.",
+  "Red flags: printing file bodies to read them; regex used to infer meaning rather than match",
+  "a literal; two turns into an analysis with zero sub-LLM calls; one sub-call per file instead",
+  "of one batch. Exception — AUTHORING is not reading: you write every edit body yourself.",
+].join("\n");
+
+export function howToRunCode(): string {
+  return [
+    "To run Python, write a fenced ```repl``` block. The REPL **persists** across turns. Only",
+    "`print(...)` output (stdout) is returned; a bare expression on the last line is discarded, so",
+    "always wrap inspections in `print(...)`.",
+  ].join(" ");
+}
+
+export function replGlossary(
+  kind: ContextKind,
+  recursion: boolean,
+  libraryLoader: boolean,
+  child: boolean,
+): string {
+  const lines = ["Available in the REPL:"];
+  if (kind === "text") {
+    lines.push(
+      "- `context`: str — the raw text you must analyze. Probe it with slices",
+      "  (`print(context[:2000])`), split it programmatically, and delegate large chunks",
+      "  to sub-LLMs — never dump the whole string into your own output.",
+    );
+  } 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_EXCLUSION_NOTE,
+    );
+    if (child) lines.push(...CHILD_CONTEXT_LINES);
+    lines.push(
+      "",
+      "  Worked example — find the slice, then delegate it:",
+      "  ```python",
+      '  hits = search("where is the retry/backoff policy configured?", k=8)',
+      "  paths = sorted({h['path'] for h in hits})",
+      '  answers.update(map_files(paths, "Describe any retry/backoff policy in this file, with line numbers. Say NONE if absent."))',
+      "  print({p: a[:80] for p, a in answers.items()})",
+      "  ```",
+    );
+  }
+  lines.push(...RETRIEVAL_GLOSSARY_LINES);
+  lines.push(
+    "- `llm_query(prompt: str, model=None) -> str`: a single sub-LLM completion. Use for extraction,",
+    "  summarization, or Q&A over a chunk of text.",
+    "- `llm_query_batched(prompts: list[str], model=None) -> list[str]`: run several sub-LLM calls",
+    "  concurrently; output order matches input order.",
+    ...CHUNKED_GLOSSARY_LINES,
+    ...SPAWN_GLOSSARY_LINES,
+    ...DELEGATION_GLOSSARY_LINES,
+  );
+  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",
+      "  sub-calls. Each child runs a full REPL loop internally — its entire conversation is PRIVATE",
+      "  and never enters your history. Only the final answer (a short string) is returned.",
+      "",
+      "  **Choosing between `llm_query` and `rlm_query`:**",
+      "  - `llm_query` for simple one-shot tasks — summarize a chunk, extract a fact, answer a direct",
+      "    question. It is a single LLM call: fast and cheap. Prefer it by default, and fan out with",
+      "    `llm_query_batched` for parallel one-shots.",
+      "  - `rlm_query` only when a sub-task genuinely needs iterative reasoning with its own code",
+      "    execution (e.g. a sub-context large enough to need its own chunking, or a multi-step",
+      "    reasoning chain). It is slower and more expensive — reserve it for cases `llm_query` cannot",
+      "    handle. Avoid excessive recursive sub-calls when a batched one-shot would suffice.",
+      ...RECURSION_CONTEXT_LINES,
+    );
+  }
+  lines.push(
+    "- `answers` / `plan`: two dicts that persist across turns. Memoize every",
+    "  verified result in `answers` — see the decomposition doctrine below.",
+    "- `SHOW_VARS() -> str`: list every variable currently in the REPL.",
+    '- `answer`: a dict initialized to {"content": "", "ready": False}. To submit your final answer,',
+    '  set `answer["content"]` to the answer text and `answer["ready"] = True`.',
+  );
+  return lines.join("\n");
+}