@hicaru/pi-rlm 0.3.0 → 0.3.1

package/README.md

@@ -166,6 +166,24 @@ inherited by every child spawned afterwards.
 > each holds a full Python process and its own copy of the inherited context. Error and
 > wall-clock caps (above) still bound a runaway tree.
 
+## Subagents and environment
+
+RLM never confiscates native file tools (`read` / `grep` / bash readers) unless `repl` is in
+the **active** tool set — the paper's trade is all-or-nothing. Process-boundary subagents that
+spawn pi with a `--tools` allowlist without `repl` therefore keep ordinary file access.
+
+Optional env conventions (for packages that want an explicit full bypass):
+
+| Env | Meaning |
+|---|---|
+| `PI_SUBAGENT_CHILD=1` | Full RLM bypass in this process (no tools / hooks / flags). |
+| `PI_RLM_FORCE_IN_SUBAGENT=1` | Experimental: opt a child back into RLM. **Consumed on activate** (not inherited after). Refused when `PI_RLM_DEPTH >= maxDepth`. |
+| `PI_RLM_DEPTH` | Cross-process depth counter (default `0`). Bumped when force-in activates. |
+
+In-process recursion (`rlm_query`) still uses `maxDepth` from `/rlm-config` and is unrelated to
+these env vars. Set `RLM_TRACE_FILE` to a path for JSONL traces of bypass / force / block-skip
+decisions.
+
 ## Security
 
 - **Key isolation**: provider keys live only in TypeScript (`AuthStorage`); the sandbox

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hicaru/pi-rlm",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "author": "hicaru",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -21,7 +21,21 @@ import { formatContextListing } from "./context/listing.ts";
 import type { AddContextHandlerBundle } from "./bridge/add-context.ts";
 import { buildNativeSystemPrompt, NATIVE_TURN_REMINDER } from "./prompts/native.ts";
 import { bashCommandFromInput, isFileReadingCommand, capToolResultText, BASH_BLOCK_REASON } from "./mode/native-guards.ts";
+import {
+  isSubagentChildBypass,
+  commitSubagentForceActivation,
+  shouldEnforceNativeReaderBlock,
+  processRlmDepth,
+} from "./mode/subagent.ts";
 import { errorMessage } from "./util/errors.ts";
+import { trace, traceEnabled } from "./util/trace.ts";
+
+export {
+  isSubagentChildBypass,
+  commitSubagentForceActivation,
+  shouldEnforceNativeReaderBlock,
+  processRlmDepth,
+} from "./mode/subagent.ts";
 
 const BLOCKED_NATIVE_TOOLS = Object.freeze(new Set(["read", "grep"]));
 /** How often to keep the parent sandbox's request watchdog alive during detached work. */
@@ -29,6 +43,23 @@ const WATCHDOG_HEARTBEAT_MS = 30_000;
 const CAPPED_RESULT_TOOLS = Object.freeze(new Set(["bash", "find", "ls"]));
 
 export default function rlmExtension(pi: ExtensionAPI): void {
+  // Subagent children run a native tool flow; RLM's contract is the opposite
+  // (block read/grep, route through repl). Env fast path: full bypass when
+  // PI_SUBAGENT_CHILD=1 (unless force-in under the depth cap). See mode/subagent.ts.
+  if (isSubagentChildBypass()) {
+    if (traceEnabled) {
+      trace("subagent.bypass", {
+        reason: process.env.PI_RLM_FORCE_IN_SUBAGENT === "1" ? "force_depth_cap" : "child",
+        depth: processRlmDepth(),
+      });
+    }
+    return;
+  }
+  commitSubagentForceActivation();
+  if (traceEnabled && process.env.PI_SUBAGENT_CHILD === "1") {
+    trace("subagent.force", { depth: processRlmDepth() });
+  }
+
   // Init synchronously with defaults — ensures commands/tools/handlers register before session_start
   const config = mergeConfig({});
   const controller = new RlmController(config);
@@ -203,9 +234,16 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     setRlmModeStatus(ctx.ui, controller, ctx.getContextUsage());
   });
 
-  // ── System prompt: native RLM mode addendum (only when enabled) ──
+  /** True when the native-mode trade holds: enabled AND repl is in the active tool set. */
+  const nativeTradeHolds = (): boolean =>
+    shouldEnforceNativeReaderBlock({
+      enabled: controller.enabled,
+      activeToolNames: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : undefined,
+    });
+
+  // ── System prompt: native RLM mode addendum (only when the trade holds) ──
   pi.on("before_agent_start", async (event) => {
-    if (!controller.enabled) return;
+    if (!nativeTradeHolds()) return;
     return { systemPrompt: event.systemPrompt + "\n\n" + buildNativeSystemPrompt() };
   });
 
@@ -218,7 +256,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
         !(message.role === "custom" && message.customType === "rlm-intro")
         && !(message.role === "user" && typeof message.content === "string" && message.content === NATIVE_TURN_REMINDER),
     );
-    if (!controller.enabled) return { messages: filtered };
+    if (!nativeTradeHolds()) return { messages: filtered };
 
     type PiMessage = (typeof filtered)[number];
 
@@ -256,8 +294,15 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   // `edit`/`write` stay unblocked so the agent modifies files through Pi's native
   // tool flow (visible to all plugins, +/- diff preview). File reading/searching
   // belongs in the REPL, and bash output is capped as a backstop.
+  // Fail-open when repl is not active (e.g. --tools allowlist without repl): never
+  // confiscate readers without a working substitute (RLM paper §2 trade).
   pi.on("tool_call", async (event) => {
-    if (!controller.enabled) return;
+    if (!nativeTradeHolds()) {
+      if (traceEnabled && controller.enabled) {
+        trace("native.block_skip", { toolName: event.toolName, reason: "no_active_repl" });
+      }
+      return;
+    }
     if (BLOCKED_NATIVE_TOOLS.has(event.toolName)) {
       return {
         block: true,
@@ -271,7 +316,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   });
 
   pi.on("tool_result", async (event) => {
-    if (!controller.enabled || !CAPPED_RESULT_TOOLS.has(event.toolName)) return;
+    if (!nativeTradeHolds() || !CAPPED_RESULT_TOOLS.has(event.toolName)) return;
     let changed = false;
     const content = event.content.map((c) => {
       if (c.type !== "text") return c;

package/src/mode/subagent.ts

@@ -0,0 +1,68 @@
+/**
+ * Subagent / process-boundary isolation for RLM.
+ *
+ * Two layers:
+ *   1. Env fast path — packages that set PI_SUBAGENT_CHILD=1 fully bypass RLM.
+ *   2. Capability gate — never confiscate native readers unless `repl` is in the
+ *      active tool set (paper trade: scaffold only if the REPL substitute exists).
+ *
+ * In-process rlm_query depth is handled by subcall-handlers.childRun; this module
+ * only covers OS-process children (pi subagents), which restart at depth 0.
+ */
+import { DEFAULT_CONFIG } from "../config/defaults.ts";
+
+export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
+export const RLM_FORCE_IN_SUBAGENT_ENV = "PI_RLM_FORCE_IN_SUBAGENT";
+export const RLM_DEPTH_ENV = "PI_RLM_DEPTH";
+
+/** Cross-process depth from env. Missing / invalid → 0. */
+export function processRlmDepth(): number {
+  const raw = process.env[RLM_DEPTH_ENV];
+  if (raw === undefined || raw === "") return 0;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return n;
+}
+
+/**
+ * True when this process should not activate RLM at all (no tools / hooks / flags).
+ *
+ * - Parent (no PI_SUBAGENT_CHILD=1) → false.
+ * - Child without force → true.
+ * - Child with force but depth >= maxDepth → true (refuse force; paper §7 cost bound).
+ * - Child with force and depth < maxDepth → false (experimental opt-in).
+ */
+export function isSubagentChildBypass(maxDepth: number = DEFAULT_CONFIG.maxDepth): boolean {
+  if (process.env[SUBAGENT_CHILD_ENV] !== "1") return false;
+  if (process.env[RLM_FORCE_IN_SUBAGENT_ENV] !== "1") return true;
+  return processRlmDepth() >= maxDepth;
+}
+
+/**
+ * Call only when RLM will activate. Scrubs force so grandchildren that inherit env
+ * do not re-open unbounded force; bumps PI_RLM_DEPTH for any re-set force path.
+ * No-op when not a forced child under the depth cap.
+ */
+export function commitSubagentForceActivation(maxDepth: number = DEFAULT_CONFIG.maxDepth): void {
+  if (process.env[SUBAGENT_CHILD_ENV] !== "1") return;
+  if (process.env[RLM_FORCE_IN_SUBAGENT_ENV] !== "1") return;
+  if (processRlmDepth() >= maxDepth) return;
+  const next = processRlmDepth() + 1;
+  delete process.env[RLM_FORCE_IN_SUBAGENT_ENV];
+  process.env[RLM_DEPTH_ENV] = String(next);
+}
+
+/**
+ * RLM's native-mode trade: confiscate read/grep (and bash readers) only when the
+ * substitute is actually callable. Fail-open when the active tool list is unknown
+ * or does not include `repl` (official pi subagent uses --tools without repl).
+ */
+export function shouldEnforceNativeReaderBlock(opts: {
+  readonly enabled: boolean;
+  readonly activeToolNames: readonly string[] | undefined;
+}): boolean {
+  if (!opts.enabled) return false;
+  const names = opts.activeToolNames;
+  if (names === undefined) return false;
+  return names.includes("repl");
+}

package/src/sandbox/py/guards.py

@@ -19,6 +19,13 @@ import sys
 from contextlib import contextmanager
 from typing import Any
 
+from hostio import pin_stdio_utf8
+
+# Pin UTF-8 before anything reads or writes a frame. On Windows these three default to the
+# locale encoding (cp1252), while the JSONL protocol Node speaks is UTF-8 both ways — see
+# issue #7. reconfigure() mutates in place, so the REAL_* captures below are the same objects.
+pin_stdio_utf8()
+
 # Capture the REAL stdio before exec() redirects sys.stdout/sys.stderr into buffers.
 # All protocol writes must go to the real stdout even while user code's prints are captured.
 REAL_STDOUT = sys.stdout

package/src/sandbox/py/hostio.py

@@ -0,0 +1,57 @@
+"""Host↔worker transport, pinned to UTF-8.
+
+Every byte the host hands this worker is UTF-8: the context temp files come from Node's
+FileHandle.write(string) (default utf8, see sandbox/context-file.ts) and the JSONL frames come
+off a pipe Node writes the same way. Python does NOT match that — text I/O defaults to the
+locale encoding, which is cp1252 on a Western Windows install. That mismatch is issue #7: a
+packed repo holding any non-ASCII byte raised UnicodeDecodeError before the REPL ever ran.
+
+Encoding is therefore never left to the locale here. Interpreter-wide UTF-8 mode (-X utf8=1,
+set by the host in sandbox.ts) covers model-written open(); these two functions cover the
+scaffold's own I/O, and they win outright — PYTHONIOENCODING overrides -X utf8=1, and
+reconfigure() overrides PYTHONIOENCODING.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+from typing import Any
+
+ENCODING = "utf-8"
+
+
+def read_host_payload(path: str, is_json: bool) -> Any:
+    """Read a payload the host serialized to a temp file.
+
+    Strict on decode errors by design. The host always writes UTF-8, so a failure here is a
+    transport bug, not bad input — and errors="replace" would hand the model silently
+    mojibake'd source code instead of surfacing the problem.
+
+    The explicit encoding= is intentionally redundant with -X utf8=1 under a normal spawn:
+    UTF-8 mode already makes the default encoding UTF-8. It still matters so a standalone
+    import of this module (or a worker started without -X utf8=1) cannot silently reintroduce
+    issue #7. phase-encoding.ts check 6 (AST / EncodingWarning) is the only automated guard
+    that encoding= is present — do not drop either side of that net.
+    """
+    with io.open(path, "r", encoding=ENCODING) as f:
+        return json.load(f) if is_json else f.read()
+
+
+def pin_stdio_utf8() -> None:
+    """Force the three real streams to UTF-8, whatever the locale or PYTHONIOENCODING says.
+
+    The write side uses surrogatepass, not strict: model code can synthesize a lone surrogate
+    (a bad decode, a truncated pair), and json.dumps(ensure_ascii=False) would then raise
+    inside _send — killing the worker on a request it had already completed. The read side
+    uses replace so a corrupt frame comes back as a "bad json" error response instead of an
+    exception that escapes main()'s loop and takes the worker down (fail-soft I/O, AGENTS.md).
+    """
+    for stream, errors in (
+        (sys.stdin, "replace"),
+        (sys.stdout, "surrogatepass"),
+        (sys.stderr, "surrogatepass"),
+    ):
+        if isinstance(stream, io.TextIOWrapper):  # not a TextIOWrapper under some test harnesses
+            stream.reconfigure(encoding=ENCODING, errors=errors)

package/src/sandbox/py/worker.py

@@ -44,6 +44,7 @@ from guards import (
     REAL_STDERR as _REAL_STDERR,
     REAL_STDIN as _REAL_STDIN,
 )
+from hostio import read_host_payload
 from retrieval import (
     _Bm25Index,
     _chunk_text,
@@ -591,8 +592,7 @@ class Worker:
         if not isinstance(path, str):
             return "Error: malformed add_context reply (no path)"
         try:
-            with io.open(path, "r") as f:
-                payload = json.load(f) if r.get("json") else f.read()
+            payload = read_host_payload(path, bool(r.get("json")))
         finally:
             try:
                 os.remove(path)  # worker owns temp-file cleanup (host does NOT unlink)
@@ -706,8 +706,7 @@ class Worker:
         `index` is accepted for protocol compatibility but ignored — there is only
         one context slot. Sources are merged on the host (or via add_context).
         """
-        with open(path, "r") as f:
-            payload = json.load(f) if is_json else f.read()
+        payload = read_host_payload(path, bool(is_json))
         self._context_payload = payload
         self.ns["context"] = payload
         # Drop legacy multi-slot names if present.

package/src/sandbox/sandbox.ts

@@ -111,6 +111,11 @@ export class PythonSandbox {
     this.initTimeoutMs = opts.initTimeoutMs ?? 30_000;
     const python = opts.python ?? "python3";
     const workerArgs = [
+      // -X utf8=1: the scaffold states its own encoding explicitly (py/hostio.py), but MODEL
+      // code gets a real open() — guards.py exposes it deliberately — and on Windows that
+      // would default to cp1252 (issue #7). UTF-8 mode covers the whole interpreter; the
+      // scaffold's explicit encoding= still wins where PYTHONIOENCODING would override this.
+      "-X", "utf8=1",
       "-u", WORKER_PATH,
       "--depth", String(opts.depth ?? 1),
       "--timeout", String(opts.execTimeoutS ?? 600),
@@ -124,7 +129,9 @@ export class PythonSandbox {
     this.proc = spawn(
       python,
       workerArgs,
-      { stdio: ["pipe", "pipe", "pipe"], env: sanitizedEnv() },
+      // windowsHide: without it each sandbox flashes a console window on Windows (pi sets
+      // this on every spawn — bash.ts / shell.ts). Same Windows surface as issue #7.
+      { stdio: ["pipe", "pipe", "pipe"], env: sanitizedEnv(), windowsHide: true },
     ) as ChildProcessWithoutNullStreams;
 
     this.proc.stdout.setEncoding("utf8");