@hicaru/pi-rlm 0.1.3 → 0.1.6

package/src/prompts/system.ts

@@ -18,8 +18,56 @@ export interface SystemPromptOptions {
   readonly recursion?: boolean;
   readonly askUserQuestion?: boolean;
   readonly todo?: boolean;
+  readonly pipeline?: boolean;
+  readonly maxPromptChars?: number;
 }
 
+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);
+}
+
+/** 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.";
+
 function howToRunCode(): string {
   return [
     "To run Python, write a fenced ```repl``` block. The REPL **persists** across turns. Only",
@@ -28,29 +76,41 @@ function howToRunCode(): string {
   ].join(" ");
 }
 
-function replGlossary(recursion: boolean, askUserQuestion: boolean, todo: boolean): string {
-  const lines = [
-    "Available in the REPL:",
-    "- `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.",
-    "",
-    "  Chunking example:",
-    "  ```python",
-    "  chunk_size = 5",
-    "  for i in range(0, len(context), chunk_size):",
-    "      batch = context[i:i+chunk_size]",
-    "      results = llm_query_batched([",
-    "          f\"Analyze {f['path']} ({f['tokens']} tok):\\n{f['content']}\"",
-    "          for f in batch",
-    "      ])",
-    "  ```",
+function replGlossary(kind: ContextKind, recursion: boolean, askUserQuestion: boolean, todo: boolean, pipeline: 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,
+      "",
+      "  Chunking example:",
+      "  ```python",
+      "  chunk_size = 5",
+      "  for i in range(0, len(context), chunk_size):",
+      "      batch = context[i:i+chunk_size]",
+      "      results = llm_query_batched([",
+      "          f\"Analyze {f['path']} ({f['tokens']} tok):\\n{f['content']}\"",
+      "          for f in batch",
+      "      ])",
+      "  ```",
+    );
+  }
+  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,
+  );
   if (askUserQuestion) {
     lines.push(
       "- `ask_user_question(questions: list[dict]) -> list[dict]`: pause and present the user",
@@ -86,11 +146,13 @@ function replGlossary(recursion: boolean, askUserQuestion: boolean, todo: boolea
       "    handle. Avoid excessive recursive sub-calls when a batched one-shot would suffice.",
     );
   }
-  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.",
-  );
+  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.",
+    );
+  }
   lines.push(
     "- `SHOW_VARS() -> str`: list every variable currently in the REPL.",
     '- `answer`: a dict initialized to {"content": "", "ready": False}. To submit your final answer,',
@@ -99,24 +161,26 @@ function replGlossary(recursion: boolean, askUserQuestion: boolean, todo: boolea
   return lines.join("\n");
 }
 
-const ORCHESTRATOR_ADDENDUM = [
-  "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.",
-  "",
-  "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.",
-  "",
-  "Sub-call budget is finite on two axes: (1) per-prompt capacity — keep each sub-prompt modestly sized",
-  "(a useful ceiling is ~100K characters), 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.",
-  "",
-  "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`.",
-].join("\n");
+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.",
+    "",
+    "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.",
+    "",
+    `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.",
+    "",
+    "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`.",
+  ].join("\n");
+}
 
 const INTRO = [
   "You are a Recursive Language Model (RLM): a language model with a prompt and a very important",
@@ -126,12 +190,14 @@ const INTRO = [
 /** Build the full RLM system prompt. */
 export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions = {}): string {
   const recursion = opts.recursion ?? false;
+  const kind = contextKindOf(meta.contextType);
+  const maxPromptChars = opts.maxPromptChars ?? DEFAULT_PROMPT_CAP;
   const parts = [
     INTRO,
     "",
     howToRunCode(),
     "",
-    replGlossary(recursion, opts.askUserQuestion ?? false, opts.todo ?? false),
+    replGlossary(kind, recursion, opts.askUserQuestion ?? false, opts.todo ?? false, opts.pipeline ?? 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",
@@ -140,9 +206,12 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
     "Start by probing `context` (print a few lines, count items). Then build up an answer to the query.",
   ];
   if (opts.orchestrator ?? true) {
-    parts.push("", ORCHESTRATOR_ADDENDUM);
+    parts.push("", orchestratorAddendum(maxPromptChars));
   }
-  parts.push("", buildMetadataLine(meta));
+  if (kind === "files") {
+    parts.push("", LARGE_FILE_RULE_LINES.join("\n"));
+  }
+  parts.push("", buildMetadataLine(meta, maxPromptChars));
   return parts.join("\n");
 }
 
@@ -152,24 +221,20 @@ function nativeReplGlossary(): string {
     "## RLM Native Mode — Persistent Python REPL",
     "",
     "Call `repl({code: \"...\"})` to execute Python in a **persistent** sandbox. Variables, imports,",
-    "and state survive across calls — you build up results incrementally. Only `print()` output is",
-    "returned, so always wrap inspections in `print(...)`.",
+    "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).",
     "- `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.",
-    "- `rlm_query(prompt, model=None) -> str` — recursive RLM with its own REPL for complex sub-tasks needing iterative reasoning.",
+    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.",
     "",
-    "**Choosing between `llm_query` and `rlm_query`:** default to `llm_query`/batched; use `rlm_query` only for iterative sub-tasks.",
     "- `todo(action, **kwargs) -> str` — manage a task list. Actions: create, update, list, get, delete, clear. Statuses: pending → in_progress → completed.",
     "- `SHOW_VARS() -> str` — list all variables currently in the REPL.",
-    "- `stage_edit(path, old_text, new_text) -> str`: stage a file edit computed inside the REPL.",
-    "  Read the file from `context`, compute the exact change in Python, then call",
-    "  stage_edit once per file. The repl() result will include a STAGED_EDITS JSON block.",
-    "  The main agent must then call `edit` for each entry verbatim — zero analysis needed.",
-    "- `answer`: dict `{\"content\": \"\", \"ready\": False}`. To submit: `answer[\"content\"] = \"...\"; answer[\"ready\"] = True`.",
+    "- `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",
     "You are an **orchestrator, not a solver**. After probing `context`, decompose the task into sub-LLM / REPL steps,",
@@ -190,30 +255,28 @@ function nativeReplGlossary(): string {
     "    ])",
     "    # aggregate results into a buffer",
     "```",
-    "- Keep sub-prompts ~100K characters; batch ~20 prompts per call. Fat prompts in small batches > thousands of tiny prompts.",
-    "- If your `context` is small enough (<20 files), you CAN read files directly via `read` / `grep` / `zebra-mcp`.",
-    "- For medium/large repos, delegate to sub-LLMs via the REPL.",
+    `- Keep sub-prompts under ${DEFAULT_PROMPT_CAP.toLocaleString()} characters (≈${promptCapTokensK(DEFAULT_PROMPT_CAP)}K tokens); batch ~20 prompts per call. Fat prompts in small batches > thousands of tiny prompts.`,
     "",
     "### Choosing Between Tools",
     "| Tool | When |",
     "|------|------|",
     "| `repl({code})` | Need to chunk/delegate `context` to sub-LLMs; need Python scripting; need REPL state across calls |",
-    "| `read` / `grep` | Inspect a few specific files directly; small codebase |",
     "| `zebra-mcp` | Semantic search over the codebase |",
     "| `edit` | Modify an existing file with exact text replacement (native Pi flow, visible to all plugins) |",
     "| `write` | Create a new file (native Pi flow, visible to all plugins) |",
     "| `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) | Sub-agent stages exact edit params; relay STAGED_EDITS to `edit` |",
+    "| `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 relay the STAGED_EDITS from the result to `edit`. For analysis tasks, write a normal message.",
+    "4. **Finalize**: For file changes, stage them inside repl() via `stage_edit(path, old, new)`, then apply the returned IDs with `apply_edits({ ids })`. For analysis tasks, write a normal message.",
     "",
     "### Task-Specific Patterns",
+    LARGE_FILE_RULE_NATIVE,
     "- Architecture/code review: chunk relevant files and delegate summaries or review to `llm_query_batched`.",
     "- Bug investigation: use Python string/regex search over `context`; delegate matching files for analysis.",
     "- If sub-LLM credits are exhausted, report partial results and stop — do not bypass REPL restrictions.",
@@ -230,29 +293,50 @@ export function buildNativeSystemPrompt(): string {
     "║  NATIVE RLM MODE — YOU ARE AN ORCHESTRATOR, NOT A READER      ║",
     "╚══════════════════════════════════════════════════════════════════╝",
     "",
-    "ABSOLUTE RESTRICTION: Do NOT use `read` or `grep` to access files.",
+    "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.",
+    "",
+    "DELEGATION RULE: if a step needs MEANING from more than ~4K chars of text, that reading MUST",
+    "be an llm_query / llm_query_batched / llm_query_chunked call (rlm_query for iterative",
+    "sub-tasks). Deterministic Python (search, count, slice, json, re) 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.",
     "",
-    "For file changes, use `edit` (modify existing) or `write` (create new) — these route through",
-    "Pi's native tool flow, visible to all plugins with a `+/-` diff preview.",
-    "",
-    "When repl() returns a STAGED_EDITS block, apply each entry by calling `edit` verbatim:",
-    "  edit({ path: entry.path, edits: [{ oldText: entry.oldText, newText: entry.newText }] })",
-    "Do not analyze or modify the parameters — relay them exactly as provided by the sub-agent.",
+    "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.",
     "",
     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. */
+export const NATIVE_PROMPT_BUDGET = 6_000;
+
 /** 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.",
+  "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.]",
+].join("\n");
+
 /** The one-line context metadata, also reused by the per-turn prompt in headless mode. */
-export function buildMetadataLine(meta: PromptMeta): string {
-  const contextDesc = `Your context is a JSON array of ${meta.contextChars.toLocaleString()} total characters — list[dict] where each dict has keys "path" (str), "content" (str), and "tokens" (int). Use Python list slicing to chunk it into batches for sub-LLM delegation.`;
-  const tail = "Each sub-LLM call can handle roughly ~100k tokens at once.";
-  const dist = meta.contextStats
+export function buildMetadataLine(meta: PromptMeta, maxPromptChars = DEFAULT_PROMPT_CAP): string {
+  const kind = contextKindOf(meta.contextType);
+  const contextDesc = kind === "text"
+    ? `Your context is a plain string of ${meta.contextChars.toLocaleString()} characters. Use Python slicing to chunk it for sub-LLM delegation.`
+    : `Your context is a JSON array of ${meta.contextChars.toLocaleString()} total characters — list[dict] where each dict has keys "path" (str), "content" (str), and "tokens" (int). Use Python list slicing to chunk it into batches for sub-LLM delegation.`;
+  const tail = `Each sub-LLM call accepts up to ${maxPromptChars.toLocaleString()} characters (≈${promptCapTokensK(maxPromptChars)}K tokens).`;
+  const dist = kind === "files" && meta.contextStats
     ? ` 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}`;

package/src/registry/edit-registry.ts

@@ -0,0 +1,22 @@
+import type { ProposedEdit } from "../sandbox/protocol.ts";
+
+export class EditRegistry {
+  private readonly edits = new Map<string, ProposedEdit>();
+
+  registerAll(edits: readonly ProposedEdit[] | undefined): void {
+    if (edits === undefined) return;
+    for (const edit of edits) this.edits.set(edit.id, edit);
+  }
+
+  get(id: string): ProposedEdit | undefined {
+    return this.edits.get(id);
+  }
+
+  delete(id: string): boolean {
+    return this.edits.delete(id);
+  }
+
+  clear(): void {
+    this.edits.clear();
+  }
+}

package/src/sandbox/protocol.ts

@@ -27,6 +27,7 @@ export interface LlmReply {
 export type ParentMessage = WorkerRequest | LlmReply;
 
 export interface ProposedEdit {
+  readonly id: string;
   readonly path: string;
   readonly oldText: string;
   readonly newText: string;

package/src/sandbox/sandbox-manager.ts

@@ -13,7 +13,9 @@ export interface SandboxManagerConfig {
   readonly requestTimeoutMs: number;
   readonly python: string;
   readonly sandboxInitTimeoutMs: number;
+  readonly maxPromptChars: number;
   readonly signal?: AbortSignal;
+  readonly onSandboxDiscarded?: () => void;
 }
 
 export class SandboxManager {
@@ -58,6 +60,7 @@ export class SandboxManager {
       python: this.config.python,
       signal: this.config.signal,
       initTimeoutMs: this.config.sandboxInitTimeoutMs,
+      maxPromptChars: this.config.maxPromptChars,
       handlers,
     }).then(async (s) => {
       // Load context on first creation if available.
@@ -116,6 +119,7 @@ export class SandboxManager {
         try { await this.sandbox.dispose(); } catch { /* already dead */ }
         this.sandbox = null;
         this.contextLoaded = false;
+        this.config.onSandboxDiscarded?.();
       }
       throw err;
     } finally {
@@ -139,7 +143,10 @@ export class SandboxManager {
     if (this.disposed) return;
     this.disposed = true;
     await this.sandbox?.dispose();
-    this.sandbox = null;
-    this.contextLoaded = false;
+    if (this.sandbox !== null) {
+      this.sandbox = null;
+      this.contextLoaded = false;
+      this.config.onSandboxDiscarded?.();
+    }
   }
 }

package/src/sandbox/sandbox.ts

@@ -52,6 +52,8 @@ export interface SandboxOptions {
   readonly signal?: AbortSignal;
   /** Worker startup wait before init failure (ms). */
   readonly initTimeoutMs?: number;
+  /** Sub-LLM prompt cap (chars) — sizes llm_query_chunked chunks inside the worker. */
+  readonly maxPromptChars?: number;
 }
 
 const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), "worker.py");
@@ -110,9 +112,17 @@ export class PythonSandbox {
     this.requestTimeoutMs = opts.requestTimeoutMs ?? 20 * 60_000;
     this.initTimeoutMs = opts.initTimeoutMs ?? 30_000;
     const python = opts.python ?? "python3";
+    const workerArgs = [
+      "-u", WORKER_PATH,
+      "--depth", String(opts.depth ?? 1),
+      "--timeout", String(opts.execTimeoutS ?? 600),
+    ];
+    if (opts.maxPromptChars !== undefined) {
+      workerArgs.push("--max-prompt-chars", String(opts.maxPromptChars));
+    }
     this.proc = spawn(
       python,
-      ["-u", WORKER_PATH, "--depth", String(opts.depth ?? 1), "--timeout", String(opts.execTimeoutS ?? 600)],
+      workerArgs,
       { stdio: ["pipe", "pipe", "pipe"], env: sanitizedEnv() },
     ) as ChildProcessWithoutNullStreams;