@hicaru/pi-rlm 0.3.1 → 0.3.3

package/src/prompts/native.ts

@@ -1,4 +1,9 @@
-/** Native-mode prompts — the main Pi agent drives the sandbox through the `repl` tool. */
+/** Native-mode prompts — the main Pi agent drives the sandbox through the `repl` tool.
+ *
+ * Structure mirrors rlm_test api_v5_anthropic (best bake-off arm): role → contract → routing →
+ * few-shots → anti-patterns → REPL surface. Goal: multi-area work fires rlm_batch / rlm_query
+ * as Task (BG), not serial repl+native read.
+ */
 
 import {
   CHUNKED_GLOSSARY_LINE_NATIVE,
@@ -11,65 +16,52 @@ import {
 /** 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] — the files you have loaded (starts empty; cwd seeds on first repl()). Each dict: `path` (str), `content` (str), `tokens` (int).",
-    "",
-    "Retrieval — free (no sub-LLM call, no tokens). **Start here, before guessing filenames:**",
-    "- `search(query, k=10, path_glob=None) -> [{path, line, score, snippet}]` — BM25 over `context`. Returns pointers, not bodies.",
-    "- `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.",
+    "## REPL surface (inside `repl({code})` only)",
+    "",
+    "Persistent Python sandbox. Only `print(...)` returns; variables/`answers`/`plan` persist across repl calls.",
+    "",
+    "### Free locate (no sub-LLM tokens)",
+    "- `search(query, k=10, path_glob=None) -> [{path, line, score, snippet, text}]` — BM25 pointers, not bodies",
+    "- `grep_context(pattern, k=50, …) -> {hits, counts, total, truncated}` — regex / lexical needles",
+    "- `outline(path) -> str` — definition skeleton (~200 chars)",
+    "",
+    "### Always-spawn fan-out (return Task + run ↯bg — NEVER the answer)",
+    "| Call | await_task → | When | NOT for |",
+    "|------|--------------|------|---------|",
+    "| `llm_query(prompt)` | str | cheap fact **from text in prompt** | reading files (no disk) |",
+    "| `llm_batch(prompts)` | list[str] | many cheap facts in **parallel** | multi-step research |",
+    "| `map_files(files, prompt)` | dict[path,str] | same question over many files | multi-step per file |",
+    "| `llm_query_chunked(text, prompt)` | list[str] | one huge text, auto-chunked | structured data |",
+    "| `rlm_query(task, paths=None)` | str | **one** multi-step study | ≥2 independent studies |",
+    "| `rlm_batch(tasks, paths=None)` | list[str] | **≥2 independent studies in parallel** | trivia / one-shots |",
+    "",
+    "Collect: `await_task(t)` or `await_task([t1,t2,…])`. `task.done` when settled.",
+    "The child inherits your `context`; send instructions + optional `paths=['src/auth/']` prefixes — never paste file bodies. **Children are sandboxed — they cannot mutate your `answers`, `plan`, or REPL variables.**",
     CHUNKED_GLOSSARY_LINE_NATIVE,
-    "- `rlm_query(prompt, model=None, paths=None) -> str` — recursive RLM with its own REPL for complex sub-tasks needing iterative reasoning. Prefer llm_query — rlm_query is slower and costlier. The child inherits your `context` (loaded files + ctx/ sources) and takes your prompt as its question, so describe the task; never paste file text. `paths=['src/auth/']` narrows its context by prefix.",
-    "- `rlm_query_batched(prompts, model=None) -> list[str]` — concurrent recursive RLM calls.",
-    "- `spawn(fn, *args) -> Task` / `rlm_await(t)` / `rlm_await_all(ts)` — start `llm_query`, `llm_query_batched`, `llm_query_chunked`, `map_files`, `rlm_query` or `rlm_query_batched` without waiting (NOT `llm_map_reduce`); collect later, order preserved. Tasks outlive the repl() call, so spawn slow work early and await when you need it.",
-    "",
+    "- `llm_map_reduce(...)` **blocks** (map then reduce) — prefer Tasks when you can interleave free work.",
+    "- `spawn(fn, *args) -> Task` optional alias for always-spawn tools (not llm_map_reduce).",
     "",
-    "- `answers` / `plan` — dicts persisted across every repl() call. Your memo.",
-    "- `add_context(source) -> dict`: append dir/file/document/git URL into `context` under `ctx/<id>/…`. Documents converted to Markdown. Return is metadata only — always use `context`.",
-    "- `SHOW_VARS() -> str` — list all variables currently in the REPL.",
-    "- `answer`: dict `{\"content\": \"\", \"ready\": False}`. Setting `answer[\"ready\"] = True` delivers it to the user; do not restate it.",
+    "### Memo / finalize",
+    "- `answers` / `plan` — persistent dicts. **If a value isn't in `answers`, it doesn't exist.**",
+    "- `add_context(source) -> dict` — append external dir/file/doc/git under `ctx/<id>/…` (metadata only).",
+    "- `SHOW_VARS()` — list REPL vars. `answer[\"ready\"]=True` only for headless finalize (native: write a normal message).",
     "",
     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.`,
+    `- Sub-prompts cap ${DEFAULT_PROMPT_CAP.toLocaleString()} chars (≈${promptCapTokensK(DEFAULT_PROMPT_CAP)}K tok); ~20 prompts/batch.`,
     "",
-    "### Choosing Between Tools",
+    "### Outside REPL",
     "| 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 |",
-    "",
-    "### 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.",
+    "| `repl({code})` | **All** bulk repo locate + fan-out analysis |",
+    "| `edit` / `write` | Apply a change **you** authored after research |",
+    "| `zebra-mcp` | Embedding search when lexical `search` misses |",
+    "| native `read`/`grep` | Only tiny pin-point files for an **edit anchor** — never bulk study |",
     "",
-    "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`.",
+    LARGE_FILE_RULE_NATIVE,
+    "- Architecture/multi-module: `rlm_batch` per area (or map_files for one-shot extracts).",
+    "- Bug hunt: `grep_context` needle → `map_files` / `rlm_query` on hits — not serial native read.",
+    "- Credits exhausted → report partials and stop.",
   ].join("\n");
 }
 
@@ -80,48 +72,98 @@ export function buildNativeSystemPrompt(): string {
     "║  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.",
+    "You never invent file contents. Multi-step / multi-area repo work goes through the REPL fan-out API.",
+    "Large tool/repl outputs are hard-capped (~4K chars).",
+    "",
+    "AUTHORING RULE: sub-LLMs (`llm_query` / `rlm_query` family) READ only — extract, locate, summarize.",
+    "They never author code you will ship. Once you know WHAT to change, compose exact oldText/newText",
+    "yourself and apply with `edit` / `write`. Never re-type file bodies or Task results into chat.",
+    "",
+    "THINKING RULE: complex decomposition (≥3 modules, architecture decisions, uncertainty",
+    "about which files hold the answer) → think out loud before the first repl() call.",
+    "Simple lookups, known paths, one-shot extracts → jump straight to repl().",
+    "Premature repl() calls on uncertain targets waste more tokens than 1–2 sentences of planning.",
+    "",
+    "<contract>",
+    "Inside `repl({code})`, EVERY heavy call returns a Task immediately (not the answer):",
+    "  llm_query | llm_batch | map_files | llm_query_chunked | rlm_query | rlm_batch  →  Task",
+    "ONLY `await_task(t)` / `await_task([…])` returns content. Fan-out runs detached (↯bg) and outlives the cell.",
+    "If you printed a Task and did not await_task, you do **not** know the answer yet.",
+    "Fire independent Tasks first → free `search`/`grep_context`/`outline` → then await_task.",
+    "Do NOT await after every independent spawn (that serializes wall time).",
+    "</contract>",
+    "",
+    "<routing>",
+    "Pick the smallest tool that fits:",
+    "- One cheap pure-text fact **with the text already in the prompt** → llm_query",
+    "- Many similar facts/chunks **with text embedded** → llm_batch(prompts=[…])",
+    "- Same question over repo files in `context` → **map_files(files|paths, prompt)**  // attaches content",
+    "- One multi-step study (own locate loop over context) → rlm_query(task=…, paths=…)",
+    "- ≥2 independent multi-step areas/modules → **rlm_batch(tasks=[…])**  // PREFER over serial rlm_query",
+    "- Dependent edit: rlm_query(research NO edits) → await_task → then YOU write edit/write",
+    "CRITICAL: `llm_query` / `llm_batch` have **NO filesystem and NO `context`** — only the string you pass.",
+    "NEVER: llm_query(\"Read pi-plugin/…/foo.ts fully…\") — the worker will say it cannot access files.",
+    "To study real files: map_files / rlm_query / rlm_batch (they see `context`) OR put the slice in the prompt yourself.",
+    "NEVER use llm_batch for \"fix the whole codebase\". NEVER use rlm_batch for trivia.",
+    "NEVER bulk-read the repo with native read/grep or by printing file bodies in repl.",
+    "</routing>",
+    "",
+    "<examples>",
+    "E1 multi-area study (PREFER rlm_batch — parallel workers):",
+    "```python",
+    "t = rlm_batch([",
+    '  "Study pi-plugin/rlm/src/commands/ — how is RLM toggled ON/OFF? NO edits. Paths + symbols.",',
+    '  "Study pi-plugin/rlm/src/mode/rlm-mode.ts + settings — enabled default + persistence. NO edits.",',
+    '  "Study pi-plugin/rlm/src/ui/status.ts — status line format. NO edits. Exact string patterns.",',
+    "])",
+    "hits = search(\"setEnabled OR toggle OR enabled\", k=12)  # free while workers run",
+    "print([h[\"path\"] for h in hits[:8]])",
+    "reports = await_task(t)",
+    "answers[\"toggle\"] = reports",
+    "print({i: r[:200] for i, r in enumerate(reports)})",
+    "```",
     "",
-    "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.",
+    "E2 locate then map_files (one-shot extracts, not multi-step):",
+    "```python",
+    'hits = search("where is retry/backoff configured?", k=8)',
+    "paths = sorted({h['path'] for h in hits})",
+    't = map_files(paths, "Describe any retry/backoff policy; line numbers. NONE if absent.")',
+    "answers.update(await_task(t))",
+    "print({p: a[:80] for p, a in answers.items()})",
+    "```",
     "",
-    "Loaded file content lives in the REPL `context` variable (cwd seeds on first call). Use ONLY `repl({code})`.",
-    "If sub-LLM credits are exhausted → report the error to the user and stop.",
+    "E3 parallel llm_batch:",
+    "```python",
+    't = llm_batch(["one-line purpose of file A", "one-line purpose of file B"])',
+    "print(await_task(t))",
+    "```",
     "",
-    "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.",
+    "E4 BAD: serial native read of many files, or await after every independent spawn",
+    "  → Wall-clock time scales linearly. Fire independent Tasks first, then await all.",
+    "E5 BAD: treat Task / map_files return as the answer without await_task",
+    "  → You'll read a Task repr, not the data. Silent garbage.",
+    "E6 BAD: one giant rlm_query that tries study+edit+verify for the whole tree",
+    "  → Token limits + no parallelism. Split into rlm_batch tasks per module.",
+    "E7 BAD: llm_batch([\"Read path/to/a.ts…\", \"Read path/to/b.ts…\"]) — paths only, no content → useless",
+    "  → llm_batch has no filesystem: it only sees the text string you paste.",
+    "E7 GOOD instead: map_files([\"path/to/a.ts\",\"path/to/b.ts\"], \"…question…\") or rlm_batch multi-step tasks",
+    "</examples>",
+    "",
+    "<rules>",
+    "1. LOCATE-THEN-DELEGATE: free search/grep/outline first; semantic reading only via Task tools.",
+    "2. Multi-module / multi-question tasks → rlm_batch (or several Tasks) in **one** repl when independent.",
+    "3. Self-contained task strings: goal + scope + success + \"NO edits\" for pure study.",
+    "4. AUTHORING: sub-LLMs READ only. You compose every edit oldText/newText yourself.",
+    "5. Memoize into `answers`. Never reuse facts only from truncated stdout.",
+    "6. Cap ~4–6 heavy concurrent rlm workers; prefer one rlm_batch over N serial rlm_query.",
+    "</rules>",
     "",
     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), then again for
- *  spawn/rlm_await: the async fan-out API is part of the model-visible contract, and
- *  ~50 tokens is worth the model actually using it. */
-export const NATIVE_PROMPT_BUDGET = 7_700;
+/** Soft cap on the static native prompt. Raised for v5-style contract/routing/examples. */
+export const NATIVE_PROMPT_BUDGET = 9_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");

package/src/prompts/system.ts

@@ -31,26 +31,31 @@ export interface SystemPromptOptions {
   readonly contextLoader?: boolean;
   /** depth > 0 — this run is an rlm_query child and its `context` is the parent's world. */
   readonly child?: boolean;
+  /** The recursion depth of this run (0 = root, 1 = first child, etc.). */
+  readonly depth?: number;
 }
 
 function orchestratorAddendum(maxPromptChars: number): string {
   return [
-    "As an RLM you are an **orchestrator, not a solver**. After you probe `context` and understand the",
-    "task, pause and plan: state how the task decomposes into sub-LLM / REPL steps, then execute one step",
-    "at a time, printing a small sample of each result to verify before moving on.",
+    "As an RLM you are an **orchestrator, not a solver**. Probe `context`, plan decomposition, then",
+    "fan out — do not solve multi-step module work yourself in a long chain of thought.",
     "",
-    "Your own context window is small. Push every long-context operation — reading, summarizing,",
-    "classifying, answering sub-questions — into `llm_query` / `llm_query_batched` instead of pulling raw",
-    "text into your own message stream. Conversely, if a Python keyword/regex search over `context` would",
-    "already pin the answer, just read it directly. Aggregate the small results back in Python.",
+    "<contract> llm_query / llm_batch / map_files / rlm_query / rlm_batch return Task (not the answer).",
+    "Only await_task returns content. Fire independent Tasks first, free search, then await_task.",
+    "Do not await after every independent spawn.</contract>",
     "",
-    `Sub-call budget is finite on two axes: (1) per-prompt capacity — each sub-prompt must stay under ${maxPromptChars.toLocaleString()} characters`,
-    `(hard cap; ≈${promptCapTokensK(maxPromptChars)}K tokens), packing a chunk of many items per call; (2) batch fan-out —`,
-    "keep batches to roughly ~20 prompts. Fat prompts in small batches beat thousands of tiny prompts.",
-    "If the workload exceeds both at once, filter aggressively in Python first, then batch the survivors.",
+    "<routing> one-shot facts → llm_query/llm_batch/map_files; one multi-step study → rlm_query;",
+    "≥2 independent multi-step areas → rlm_batch (prefer over serial rlm_query). NEVER print file",
+    "bodies into your own stream when a Task tool can read them.</routing>",
     "",
-    "Reserve your own tokens for high-level decisions: what to ask next, how to combine sub-LM outputs,",
-    "when to finalize. Delegate everything else. Do not submit a final answer before inspecting `context`.",
+    "Your own context window is small. Push long-context work into sub-calls. If free search/grep",
+    "already pins a tiny fact, use that. Aggregate small results in Python / `answers`.",
+    "",
+    `Sub-call budget: (1) per-prompt < ${maxPromptChars.toLocaleString()} chars (≈${promptCapTokensK(maxPromptChars)}K tok);`,
+    "(2) ~20 prompts per llm_batch. Fat prompts in small batches beat thousands of tiny prompts.",
+    "Filter in Python first when both axes overflow.",
+    "",
+    "Reserve your tokens for planning, combining, and finalizing. Do not finalize before inspecting `context`.",
   ].join("\n");
 }
 
@@ -66,6 +71,15 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
   const maxPromptChars = opts.maxPromptChars ?? DEFAULT_PROMPT_CAP;
   const parts = [
     INTRO,
+  ];
+  if ((opts.depth ?? 0) > 0) {
+    parts.push(
+      "",
+      `**Recursion depth: ${opts.depth}.** You are a sub-RLM — focus narrowly on your assigned`,
+      "task. Delegate (rlm_query/rlm_batch) only if the task itself must decompose further.",
+    );
+  }
+  parts.push(
     "",
     howToRunCode(),
     "",
@@ -78,7 +92,7 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
     "dump a whole sub-LLM result. The full content persists across turns in REPL variables (call `SHOW_VARS()`).",
     "",
     "Start by probing `context` (print a few lines, count items). Then build up an answer to the query.",
-  ];
+  );
   if (opts.orchestrator ?? true) {
     // Two counterweights, both required (paper App. B): the addendum bounds OVER-recursion
     // (batching/cost), ENV_TIPS bounds UNDER-recursion (solving it yourself).
@@ -102,5 +116,5 @@ export function buildMetadataLine(meta: PromptMeta, maxPromptChars = DEFAULT_PRO
     ? ` Your context has ${meta.contextStats.files} files; per-file tokens run min ${meta.contextStats.min.toLocaleString()} / median ${meta.contextStats.median.toLocaleString()} / max ${meta.contextStats.max.toLocaleString()} — use this to gauge how many files fit per batch.`
     : "";
   const body = `${contextDesc} ${tail}${dist}`;
-  return meta.rootPrompt ? `Answer the following: ${meta.rootPrompt}\n\n${body}` : body;
+  return meta.rootPrompt ? `<task>${meta.rootPrompt}</task>\n\n${body}` : body;
 }