@hicaru/pi-rlm 0.2.0 → 0.2.2

package/src/prompts/system.ts

@@ -5,6 +5,17 @@
  * exposes `context`, the sub-LLM functions, and the `answer` dict the model flips to submit.
  */
 import type { ContextSizeStats } from "../text/tokens.ts";
+import {
+  contextKindOf,
+  DEFAULT_PROMPT_CAP,
+  ENV_TIPS,
+  howToRunCode,
+  LARGE_FILE_RULE_LINES,
+  promptCapTokensK,
+  replGlossary,
+} from "./glossary.ts";
+
+export { contextKindOf, type ContextKind } from "./glossary.ts";
 
 export interface PromptMeta {
   readonly contextType: string;
@@ -16,275 +27,10 @@ export interface PromptMeta {
 export interface SystemPromptOptions {
   readonly orchestrator?: boolean;
   readonly recursion?: boolean;
-  readonly askUserQuestion?: boolean;
-  readonly todo?: boolean;
-  readonly pipeline?: boolean;
   readonly maxPromptChars?: number;
   readonly libraryLoader?: boolean;
-}
-
-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";
-}
-
-const DEFAULT_PROMPT_CAP = 400_000;
-
-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.
- */
-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. */
-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). */
-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.",
-]);
-
-/** Why a file the user mentioned may be missing from `context`. */
-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). */
-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). */
-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). */
-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.
- */
-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 and survive snapshots.",
-  "**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. */
-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 turns and snapshots: **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");
-
-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(" ");
-}
-
-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(
-      "- `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,
-      "",
-      "  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,
-    ...DELEGATION_GLOSSARY_LINES,
-  );
-  if (askUserQuestion) {
-    lines.push(
-      "- `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?}.",
-      "  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.",
-    );
-  }
-  if (todo) {
-    lines.push(
-      "- `todo(action, **kwargs) -> str`: manage a task list visible to the user.",
-      "  Actions: create(subject, description?, status='pending'), update(id, status?, activeForm?),",
-      "  list(filterStatus?), get(id), delete(id), clear().",
-      "  Status flow: pending → in_progress → completed.",
-      "  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",
-      "  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.",
-    );
-  }
-  if (pipeline) {
-    lines.push(
-      "- `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(
-    "- `answers` / `plan`: two dicts that persist across turns and snapshots. 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");
+  /** depth > 0 — this run is an rlm_query child and its `context` is the parent's world. */
+  readonly child?: boolean;
 }
 
 function orchestratorAddendum(maxPromptChars: number): string {
@@ -324,8 +70,7 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
     howToRunCode(),
     "",
     replGlossary(
-      kind, recursion, opts.askUserQuestion ?? false, opts.todo ?? false,
-      opts.pipeline ?? false, opts.libraryLoader ?? false,
+      kind, recursion, opts.libraryLoader ?? false, opts.child ?? false,
     ),
     "",
     "REPL stdout over ~800 characters is truncated to a short excerpt — large results stay in your",
@@ -346,123 +91,6 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
   return parts.join("\n");
 }
 
-/** Adapts the REPL glossary for native mode — agent calls `repl({code})` instead of writing ```repl``` blocks. */
-function nativeReplGlossary(): string {
-  return [
-    "## RLM Native Mode — Persistent Python REPL",
-    "",
-    "Call `repl({code: \"...\"})` to execute Python in a **persistent** sandbox. Variables, imports,",
-    "State persists; only `print()` output is returned, so wrap inspections in `print(...)`.",
-    "",
-    "### REPL Environment",
-    "- `context`: list[dict] — every file in the repository. Each dict: `path` (str), `content` (str), `tokens` (int).",
-    "",
-    "Retrieval — free (no sub-LLM call, no tokens). **Start here, before guessing filenames:**",
-    "- `search(query, k=10, path_glob=None) -> [{path, line, score, snippet}]` — BM25 over `context`. Returns pointers, not bodies.",
-    "- `grep_context(pattern, k=50, path_glob=None, before=0, after=0) -> {hits, counts, total, truncated}` — regex; `counts` stays complete when `hits` is capped. Lexical needles only.",
-    "- `outline(path) -> str` — definition/heading skeleton with line numbers. Orient in ~200 chars instead of printing 20K.",
-    "",
-    "Delegation — everything semantic goes through these:",
-    "- `map_files(files, prompt, model=None) -> {path: answer}` — ask `prompt` of many files; batches and splits oversized files for you. **The default way to read many files.**",
-    "- `llm_map_reduce(items, map_prompt, reduce_prompt, model=None) -> str` — map in one batch, then reduce with one call.",
-    "- `llm_query(prompt, model=None) -> str` — one-shot sub-LLM. Use for extraction, summarization, Q&A over a chunk.",
-    "- `llm_query_batched(prompts, model=None) -> list[str]` — concurrent sub-LLM calls; output order matches input order.",
-    CHUNKED_GLOSSARY_LINE_NATIVE,
-    "- `rlm_query(prompt, model=None) -> str` — recursive RLM with its own REPL for complex sub-tasks needing iterative reasoning. Prefer llm_query — rlm_query is slower and costlier.",
-    "- `rlm_query_batched(prompts, model=None) -> list[str]` — concurrent recursive RLM calls.",
-    "",
-    "",
-    "- `answers` / `plan` — dicts persisted across every repl() call and snapshot. Your memo.",
-    "- `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.",
-    "- `answer`: dict `{\"content\": \"\", \"ready\": False}`. Setting `answer[\"ready\"] = True` delivers it to the user; do not restate it.",
-    "",
-    ENV_TIPS_CONDENSED,
-    "",
-    "### Worked pattern",
-    "```python",
-    'hits = search("where is retry/backoff configured?", k=8)',
-    "paths = sorted({h['path'] for h in hits})",
-    'answers.update(map_files(paths, "Describe any retry/backoff policy here, with line numbers. Say NONE if absent."))',
-    "print({p: a[:80] for p, a in answers.items()})",
-    "```",
-    `- Sub-prompts cap at ${DEFAULT_PROMPT_CAP.toLocaleString()} chars (≈${promptCapTokensK(DEFAULT_PROMPT_CAP)}K tokens); ~20 prompts per batch. Fat prompts in small batches > thousands of tiny prompts.`,
-    "",
-    "### Choosing Between Tools",
-    "| Tool | When |",
-    "|------|------|",
-    "| `repl({code})` | ALL repository reading, search, and analysis; Python scripting; state across calls |",
-    "| `edit` / `write` | Change or create a file. Compose oldText/newText yourself; exact match required |",
-    "| `search` / `grep_context` / `outline` (in repl) | Locate the relevant slice — free, do this first |",
-    "| `zebra-mcp` | Semantic/embedding search when lexical `search` misses the concept |",
-    "| `map_files` / `llm_query_batched` (in repl) | Read/extract/classify that slice |",
-    "| `rlm_query` (in repl) | Sub-task needing its own iterative reasoning and REPL |",
-    "| `todo` (in repl) | Track multi-step progress visibly to the user |",
-    "",
-    "### Task-Specific Patterns",
-    LARGE_FILE_RULE_NATIVE,
-    "- Architecture/code review: `search` for the subsystem, then `map_files` the hits.",
-    "- Bug investigation: `grep_context` for the literal symbol/message, then `map_files` the matching files.",
-    "- Finalizing: for file changes call `edit`/`write` directly so Pi validates the anchor and renders the diff; for analysis, write a normal message.",
-    "- If sub-LLM credits are exhausted, report partial results and stop — do not bypass REPL restrictions.",
-    "",
-    "Reserve your own tokens for high-level decisions: what to ask next, how to combine sub-LLM outputs, when to finalize.",
-    "Delegate everything else. Do not submit a final answer before inspecting `context`.",
-  ].join("\n");
-}
-
-/** Build the native-mode system prompt for the main Pi agent. */
-export function buildNativeSystemPrompt(): string {
-  return [
-    "╔══════════════════════════════════════════════════════════════════╗",
-    "║  NATIVE RLM MODE — YOU ARE AN ORCHESTRATOR, NOT A READER      ║",
-    "╚══════════════════════════════════════════════════════════════════╝",
-    "",
-    "ENFORCED BY THE RUNTIME (not advisory):",
-    "- `read`/`grep` are blocked; bash readers (cat/sed/head/tail/awk/rg) are blocked; bash output is hard-capped at 4K chars.",
-    "- repl() stdout returned to you is hard-capped at 4K chars — printing file bodies is USELESS; the text will not reach you.",
-    "",
-    "LOCATE-THEN-DELEGATE: `search(query)` / `grep_context(pattern)` / `outline(path)` cost nothing",
-    "— run them FIRST to find the relevant slice. Then, if a step needs MEANING from more than ~4K",
-    "chars, that reading MUST be a map_files / llm_query / llm_query_batched / llm_query_chunked",
-    "call (rlm_query for iterative sub-tasks). Deterministic Python over `context` is free and",
-    "preferred for lookups. Semantic reading is always delegated.",
-    "",
-    "All file content is pre-loaded in the REPL `context` variable. Use ONLY `repl({code})`.",
-    "If sub-LLM credits are exhausted → report the error to the user and stop.",
-    "",
-    "AUTHORING RULE: sub-LLMs (`llm_query` family) READ — they extract, locate, and summarize.",
-    "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");
-}
-
-/** Soft cap on the static native prompt. Leaves headroom for per-turn context injection
- *  without bloating the root model's system prompt. Exceeded → phase-guards.ts fails.
- *  Raised from 6K when the retrieval glossary and the condensed decomposition doctrine
- *  landed; both buy far more than they cost (paper Table 2, Fig. 4a). */
-export const NATIVE_PROMPT_BUDGET = 7_500;
-
-/** Exported for tests — prompt length without context metadata (which is injected separately). */
-export const NATIVE_PROMPT_STATIC = buildNativeSystemPrompt();
-
-/** Per-turn last-position reminder for native mode — appended to every context build. */
-export const NATIVE_TURN_REMINDER = [
-  "[RLM orchestrator contract — enforced by the runtime, not optional:",
-  "repl() stdout to you is hard-capped at 4K chars; read/grep and bash readers are blocked.",
-  "LOCATE FIRST with search() / grep_context() / outline() — they cost nothing. Any SEMANTIC",
-  "reading MUST then go through map_files / llm_query / llm_query_batched / llm_query_chunked",
-  "(rlm_query for iterative sub-tasks). Memoize what you reuse in `answers`; a value not in",
-  "`answers` does not exist. 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.",
-  "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. */
 export function buildMetadataLine(meta: PromptMeta, maxPromptChars = DEFAULT_PROMPT_CAP): string {
   const kind = contextKindOf(meta.contextType);

package/src/sandbox/context-file.ts

@@ -0,0 +1,154 @@
+/**
+ * Temp-file transport for sandbox context payloads, with refcounted sharing.
+ *
+ * Two callers, two ownership models, one writer:
+ *  - `writeContextTempFile` — non-owning. `load_library` uses it because the WORKER unlinks
+ *    that file after reading it (see sandbox.ts serviceInterrupt / worker.py `_load_library`).
+ *  - `pinContext` — refcounted. Every child RLM of one node inherits the SAME payload, so an
+ *    18-way fan-out would otherwise cost 18 serializations and 18 files. Pins are keyed by
+ *    payload identity, which is a free version key: `mergeLibraryIntoContext` always returns a
+ *    NEW array, so loading a library mints a new key and old holders keep their own file.
+ *
+ * Serialization is chunked with an await between chunks so the event loop is never blocked for
+ * more than ~SERIALIZE_CHUNK entries. A Worker Thread was considered and rejected: posting the
+ * payload structured-clones the whole array, which costs about what the stringify costs and
+ * doubles peak RSS.
+ */
+
+import { open, unlink, type FileHandle } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Entries serialized per await. Bounds the longest synchronous span on the event loop. */
+const SERIALIZE_CHUNK = 64;
+
+/** A temp file on disk holding a serialized context payload. */
+export interface ContextTempFile {
+  readonly path: string;
+  /** True when the file holds JSON; false when the payload was a raw string. */
+  readonly json: boolean;
+}
+
+/** A shared, refcounted context file. Every holder must `release()` exactly once. */
+export interface PinnedContext extends ContextTempFile {
+  /** Drop this holder's reference; unlinks once the last holder releases. Idempotent. */
+  release(): Promise<void>;
+}
+
+interface PinEntry extends ContextTempFile {
+  refs: number;
+}
+
+/**
+ * Live pins keyed by payload identity, storing the in-flight PROMISE rather than the settled
+ * entry. Children of one node race here (each drives its own sandbox, so nothing else
+ * serializes them); inserting the promise before the first await makes them join one write
+ * instead of each starting their own and orphaning the loser's file.
+ */
+const pins = new Map<unknown, Promise<PinEntry>>();
+
+function tempPath(isJson: boolean): string {
+  const suffix = isJson ? "json" : "txt";
+  return join(
+    tmpdir(),
+    `rlm-ctx-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.${suffix}`,
+  );
+}
+
+/** Write a JSON array incrementally, yielding to the event loop between chunks. */
+async function writeChunkedArray(handle: FileHandle, items: readonly unknown[]): Promise<void> {
+  await handle.write("[");
+  const buf = new Array<string>(SERIALIZE_CHUNK);
+  let n = 0;
+  for (let i = 0; i < items.length; i++) {
+    // Comma prefix beats trimming a trailing one; no `+=` accumulation anywhere.
+    buf[n++] = i === 0 ? JSON.stringify(items[i]) : `,${JSON.stringify(items[i])}`;
+    if (n === SERIALIZE_CHUNK) {
+      await handle.write(buf.join("")); // the await is the yield point
+      n = 0;
+    }
+  }
+  if (n > 0) await handle.write(buf.slice(0, n).join(""));
+  await handle.write("]");
+}
+
+/**
+ * Serialize a payload to a fresh temp file. The caller owns the file and decides when (or
+ * whether) to unlink it.
+ */
+export async function writeContextTempFile(payload: unknown): Promise<ContextTempFile> {
+  const json = typeof payload !== "string";
+  const path = tempPath(json);
+  try {
+    const handle = await open(path, "w");
+    try {
+      if (typeof payload === "string") await handle.write(payload);
+      else if (Array.isArray(payload)) await writeChunkedArray(handle, payload);
+      else await handle.write(JSON.stringify(payload));
+    } finally {
+      await handle.close();
+    }
+  } catch (err) {
+    await unlink(path).catch(() => {});
+    throw err;
+  }
+  return Object.freeze({ path, json });
+}
+
+async function writePinEntry(payload: unknown): Promise<PinEntry> {
+  const file = await writeContextTempFile(payload);
+  return { path: file.path, json: file.json, refs: 1 };
+}
+
+/** One holder's view of a pin. `shared` entries are evicted from the map at refcount zero. */
+function handleFor(key: unknown, entry: PinEntry, shared: boolean): PinnedContext {
+  let released = false;
+  return Object.freeze({
+    path: entry.path,
+    json: entry.json,
+    release: async (): Promise<void> => {
+      if (released) return; // idempotent per handle, so a `finally` cannot double-decrement
+      released = true;
+      entry.refs -= 1;
+      if (entry.refs > 0) return;
+      if (shared) pins.delete(key);
+      await unlink(entry.path).catch(() => {});
+    },
+  });
+}
+
+/**
+ * Acquire a shared context file for `payload`. Holders must `release()` exactly once; the file
+ * is unlinked when the last one does.
+ */
+export async function pinContext(payload: unknown): Promise<PinnedContext> {
+  // Only arrays are shared. Their identity is a meaningful version key; a string's is not
+  // (two equal strings may or may not be the same reference), and the string payloads here are
+  // one-off child prompts with nothing to share anyway.
+  if (!Array.isArray(payload)) {
+    return handleFor(payload, await writePinEntry(payload), false);
+  }
+
+  const existing = pins.get(payload);
+  if (existing !== undefined) {
+    const entry = await existing;
+    entry.refs += 1;
+    return handleFor(payload, entry, true);
+  }
+
+  // Insert synchronously, BEFORE any await, so a concurrent caller sees this write in flight.
+  const pending = writePinEntry(payload);
+  pins.set(payload, pending);
+  try {
+    return handleFor(payload, await pending, true);
+  } catch (err) {
+    // Evict the rejected promise so a later caller retries instead of awaiting a poisoned pin.
+    pins.delete(payload);
+    throw err;
+  }
+}
+
+/** Live pin count. Exported for tests asserting the sharing and the unlink-once behaviour. */
+export function pinnedCount(): number {
+  return pins.size;
+}