@draht/rlm 2026.7.12-1

package/dist/sandbox.js

@@ -0,0 +1,273 @@
+/**
+ * OS-level sandbox spawn wrapper for the RLM Python REPL driver.
+ *
+ * This is the REAL security boundary described in
+ * .planning/phases/28-repl-sandbox-safety/28-01-PLAN.md ("IMPORTANT" section
+ * and Architecture section 1) -- NOT `repl_driver.py`'s Python-level
+ * builtins/import allowlist (that's defense-in-depth for a
+ * confused/prompt-injected LLM, not something that stops a deliberately
+ * adversarial payload; the Python object graph makes in-process
+ * confinement of arbitrary Python fundamentally unachievable -- see the
+ * plan for the `__subclasses__`/`gi_frame.f_builtins` escapes that defeat
+ * any purely in-process approach).
+ *
+ * **macOS**: wraps the interpreter with `sandbox-exec -f macos.sb ...`. The
+ * SBPL profile (`../sandbox/macos.sb`) denies network and process-exec
+ * entirely (which alone defeats `os.system`/`subprocess` -- they fork+exec
+ * a shell -- independent of any Python-level import block) and scopes file
+ * access to exactly the Python installation needed to boot plus the
+ * session's workdir. Machine-specific paths (where python3 actually lives)
+ * are discovered here at spawn time via a real subprocess call, never
+ * hardcoded/guessed -- see `resolvePythonInstallation`.
+ *
+ * **Linux**: wraps with `unshare --user --map-root-user --net --mount --`
+ * (empty net namespace = network unreachable at the kernel; mount
+ * namespace for FS confinement), falling back to `bwrap` with equivalent
+ * flags if `unshare` isn't available. Availability is detected at spawn
+ * time, never assumed.
+ *
+ * **Fail closed everywhere**: if the sandboxing mechanism for the current
+ * platform can't be established (wrapper binary missing, profile missing,
+ * Python installation can't be discovered, unsupported platform), every
+ * function here throws `SandboxUnavailableError` synchronously rather than
+ * returning a command that would run the driver unwrapped. There is no
+ * fallback path to an unsandboxed spawn anywhere in this module.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, delimiter as pathDelimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MACOS_PROFILE_PATH = join(__dirname, "..", "sandbox", "macos.sb");
+const DEFAULT_SANDBOX_EXEC_BIN = "/usr/bin/sandbox-exec";
+/**
+ * Thrown whenever the OS-level sandbox can't be established for the current
+ * platform/environment. Callers (see `session.ts`) must let this propagate
+ * and refuse to run rather than catching it and falling back to an
+ * unwrapped spawn -- that fallback is exactly the failure mode Architecture
+ * section 1's "fail closed" requirement exists to prevent.
+ */
+export class SandboxUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SandboxUnavailableError";
+    }
+}
+const pythonInstallationCache = new Map();
+/**
+ * Asks the given `python3` binary (via a real subprocess call -- there is no
+ * static/config-file way to learn a Python install's true executable path
+ * and stdlib root; every install lays these out differently) where it and
+ * its stdlib actually live, then checks for the macOS framework-build
+ * re-exec companion described above. Memoized per `pythonBin` string since
+ * the answer can't change during this process's lifetime and this runs on
+ * every sandboxed spawn.
+ */
+function resolvePythonInstallation(pythonBin) {
+    const cached = pythonInstallationCache.get(pythonBin);
+    if (cached)
+        return cached;
+    let stdout;
+    try {
+        stdout = execFileSync(pythonBin, ["-c", "import sys; print(sys.executable); print(sys.prefix)"], {
+            encoding: "utf8",
+        });
+    }
+    catch (err) {
+        throw new SandboxUnavailableError(`sandbox_violation: could not run ${JSON.stringify(pythonBin)} to discover its installation -- refusing to run the REPL driver unsandboxed. (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const lines = stdout.trim().split("\n");
+    const executableLine = lines[0];
+    const prefixLine = lines[1];
+    if (!executableLine || !prefixLine) {
+        throw new SandboxUnavailableError(`sandbox_violation: unexpected output discovering the Python installation for ${JSON.stringify(pythonBin)}: ${JSON.stringify(stdout)}`);
+    }
+    let realBin;
+    let prefix;
+    try {
+        realBin = realpathSync(executableLine.trim());
+        prefix = realpathSync(prefixLine.trim());
+    }
+    catch (err) {
+        throw new SandboxUnavailableError(`sandbox_violation: could not resolve real filesystem paths for the Python installation -- refusing to run the REPL driver unsandboxed. (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const reexecCandidate = join(prefix, "Resources", "Python.app", "Contents", "MacOS", "Python");
+    const reexecBin = existsSync(reexecCandidate) ? realpathSync(reexecCandidate) : realBin;
+    const installation = { realBin, reexecBin, prefix };
+    pythonInstallationCache.set(pythonBin, installation);
+    return installation;
+}
+/** Resolves a bare command name against `PATH`, returning `null` if not found. Used for the Linux wrappers. */
+function resolveOnPath(name) {
+    const pathEnv = process.env.PATH ?? "";
+    for (const dir of pathEnv.split(pathDelimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function buildMacosCommand(opts) {
+    const sandboxExecBin = opts.sandboxExecBin ?? DEFAULT_SANDBOX_EXEC_BIN;
+    if (!existsSync(sandboxExecBin)) {
+        throw new SandboxUnavailableError(`sandbox_violation: macOS sandbox-exec binary not found at ${JSON.stringify(sandboxExecBin)} -- refusing to run the REPL driver unsandboxed.`);
+    }
+    if (!existsSync(MACOS_PROFILE_PATH)) {
+        throw new SandboxUnavailableError(`sandbox_violation: sandbox profile missing at ${JSON.stringify(MACOS_PROFILE_PATH)} -- refusing to run the REPL driver unsandboxed.`);
+    }
+    const { realBin, reexecBin, prefix } = resolvePythonInstallation(opts.pythonBin ?? "python3");
+    let workdir;
+    let driverPath;
+    try {
+        workdir = realpathSync(opts.workdir);
+        driverPath = realpathSync(opts.driverPath);
+    }
+    catch (err) {
+        throw new SandboxUnavailableError(`sandbox_violation: could not resolve workdir/driver paths -- refusing to run the REPL driver unsandboxed. (${err instanceof Error ? err.message : String(err)})`);
+    }
+    return {
+        command: sandboxExecBin,
+        args: [
+            "-D",
+            `PYTHON_REAL_BIN=${realBin}`,
+            "-D",
+            `PYTHON_REEXEC_BIN=${reexecBin}`,
+            "-D",
+            `PYTHON_PREFIX=${prefix}`,
+            "-D",
+            `DRIVER_PATH=${driverPath}`,
+            "-D",
+            `WORKDIR=${workdir}`,
+            "-f",
+            MACOS_PROFILE_PATH,
+            realBin,
+            driverPath,
+        ],
+    };
+}
+function buildLinuxCommand(opts) {
+    const pythonBin = opts.pythonBin ?? "python3";
+    let workdir;
+    let driverPath;
+    try {
+        workdir = realpathSync(opts.workdir);
+        driverPath = realpathSync(opts.driverPath);
+    }
+    catch (err) {
+        throw new SandboxUnavailableError(`sandbox_violation: could not resolve workdir/driver paths -- refusing to run the REPL driver unsandboxed. (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const unshareBin = opts.unshareBin ?? resolveOnPath("unshare");
+    if (unshareBin && existsSync(unshareBin)) {
+        // Empty user+net namespace: no interfaces besides loopback exist, so
+        // network is unreachable at the kernel regardless of anything Python
+        // itself tries. Mount namespace confines the filesystem view; the
+        // workdir bind-mount (rw) plus the rest of the root (ro, implicit --
+        // `unshare --mount` alone doesn't remount anything) is a coarser
+        // boundary than the macOS profile's explicit allowlist, which is why
+        // `--map-root-user` + a private mount namespace is paired with the
+        // driver only ever being told about `workdir` for file I/O at the
+        // Python-guardrail layer (Phase 28 task 2) -- the kernel-level net
+        // denial is what task 1 owns and is unconditional here.
+        return {
+            command: unshareBin,
+            args: ["--user", "--map-root-user", "--net", "--mount", "--", pythonBin, driverPath],
+        };
+    }
+    const bwrapBin = opts.bwrapBin ?? resolveOnPath("bwrap");
+    if (bwrapBin && existsSync(bwrapBin)) {
+        const binds = ["/usr", "/lib", "/bin", "/sbin"]
+            .filter((path) => existsSync(path))
+            .flatMap((path) => ["--ro-bind", path, path]);
+        if (existsSync("/lib64"))
+            binds.push("--ro-bind", "/lib64", "/lib64");
+        return {
+            command: bwrapBin,
+            args: [
+                "--unshare-user",
+                "--unshare-net",
+                "--unshare-pid",
+                "--die-with-parent",
+                ...binds,
+                "--bind",
+                workdir,
+                workdir,
+                "--proc",
+                "/proc",
+                "--dev",
+                "/dev",
+                "--chdir",
+                workdir,
+                pythonBin,
+                driverPath,
+            ],
+        };
+    }
+    throw new SandboxUnavailableError("sandbox_violation: neither `unshare` nor `bwrap` is available on this Linux host -- refusing to run the REPL driver unsandboxed.");
+}
+/**
+ * Computes the sandboxed command/args for the current platform without
+ * spawning anything. Exposed separately from `spawnSandboxed` so tests can
+ * assert on the resolved invocation and so fail-closed behavior (throwing
+ * `SandboxUnavailableError`) is observable synchronously, before any
+ * process exists.
+ */
+export function resolveSandboxedCommand(opts) {
+    if (process.platform === "darwin")
+        return buildMacosCommand(opts);
+    if (process.platform === "linux")
+        return buildLinuxCommand(opts);
+    throw new SandboxUnavailableError(`sandbox_violation: no OS-level sandbox implementation for platform ${JSON.stringify(process.platform)} -- refusing to run the REPL driver unsandboxed.`);
+}
+/**
+ * Environment variables the sandboxed interpreter is allowed to see, by
+ * allowlist rather than denylist. The OS sandbox itself denies network
+ * access outright, so this isn't the primary defense against exfiltrating
+ * anything read from here -- but the same object-graph escapes that defeat
+ * in-process Python restriction (see this module's doc comment) can still
+ * reach `os.environ` and write it into the session workdir even with
+ * network denied, so the child process should never see more of the parent
+ * Node process's environment (API keys, tokens, credentials, ...) than it
+ * actually needs to boot a working interpreter.
+ */
+const SAFE_ENV_ALLOWLIST = [
+    "PATH",
+    "HOME",
+    "LANG",
+    "LANGUAGE",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TMPDIR",
+    "TZ",
+    "PYTHONHASHSEED",
+    "PYTHONIOENCODING",
+    "PYTHONUTF8",
+];
+/**
+ * Builds a scrubbed environment for the sandboxed child process from
+ * `SAFE_ENV_ALLOWLIST` -- deliberately NOT `{ ...process.env }` (see
+ * `SAFE_ENV_ALLOWLIST`'s doc comment for why the full parent environment,
+ * secrets included, must not be handed to a process running LLM-authored
+ * code).
+ */
+function buildScrubbedEnv() {
+    const scrubbed = {};
+    for (const key of SAFE_ENV_ALLOWLIST) {
+        const value = process.env[key];
+        if (value !== undefined)
+            scrubbed[key] = value;
+    }
+    return scrubbed;
+}
+/**
+ * Spawns `repl_driver.py` wrapped in the platform's OS-level sandbox.
+ * Throws `SandboxUnavailableError` synchronously (before any process is
+ * created) if the sandbox can't be established -- there is no unwrapped
+ * fallback path.
+ */
+export function spawnSandboxed(opts) {
+    const { command, args } = resolveSandboxedCommand(opts);
+    return spawn(command, args, { stdio: ["pipe", "pipe", "pipe"], env: buildScrubbedEnv() });
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAqB,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AACxE,MAAM,wBAAwB,GAAG,uBAAuB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACjD,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACvC,CAAC;CACD;AAuDD,MAAM,uBAAuB,GAAG,IAAI,GAAG,EAA8B,CAAC;AAEtE;;;;;;;;GAQG;AACH,SAAS,yBAAyB,CAAC,SAAiB;IACnD,MAAM,MAAM,GAAG,uBAAuB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACJ,MAAM,GAAG,YAAY,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,sDAAsD,CAAC,EAAE;YAChG,QAAQ,EAAE,MAAM;SAChB,CAAC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,uBAAuB,CAChC,oCAAoC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,kFAC5D,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAChD,GAAG,CACH,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,cAAc,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,CAAC,cAAc,IAAI,CAAC,UAAU,EAAE,CAAC;QACpC,MAAM,IAAI,uBAAuB,CAChC,gFAAgF,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CACtI,CAAC;IACH,CAAC;IAED,IAAI,OAAe,CAAC;IACpB,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACJ,OAAO,GAAG,YAAY,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,uBAAuB,CAChC,2IACC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAChD,GAAG,CACH,CAAC;IACH,CAAC;IAED,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC/F,MAAM,SAAS,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAExF,MAAM,YAAY,GAAuB,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IACxE,uBAAuB,CAAC,GAAG,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACrD,OAAO,YAAY,CAAC;AACrB,CAAC;AAED,+GAA+G;AAC/G,SAAS,aAAa,CAAC,IAAY;IAClC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;QAChD,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC7C,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAyB;IACnD,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,wBAAwB,CAAC;IACvE,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,uBAAuB,CAChC,6DAA6D,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,kDAAkD,CAC7I,CAAC;IACH,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,uBAAuB,CAChC,iDAAiD,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,kDAAkD,CACrI,CAAC;IACH,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,CAAC;IAE9F,IAAI,OAAe,CAAC;IACpB,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACJ,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrC,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,uBAAuB,CAChC,8GACC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAChD,GAAG,CACH,CAAC;IACH,CAAC;IAED,OAAO;QACN,OAAO,EAAE,cAAc;QACvB,IAAI,EAAE;YACL,IAAI;YACJ,mBAAmB,OAAO,EAAE;YAC5B,IAAI;YACJ,qBAAqB,SAAS,EAAE;YAChC,IAAI;YACJ,iBAAiB,MAAM,EAAE;YACzB,IAAI;YACJ,eAAe,UAAU,EAAE;YAC3B,IAAI;YACJ,WAAW,OAAO,EAAE;YACpB,IAAI;YACJ,kBAAkB;YAClB,OAAO;YACP,UAAU;SACV;KACD,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAyB;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC;IAE9C,IAAI,OAAe,CAAC;IACpB,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACJ,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrC,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,uBAAuB,CAChC,8GACC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAChD,GAAG,CACH,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,aAAa,CAAC,SAAS,CAAC,CAAC;IAC/D,IAAI,UAAU,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1C,qEAAqE;QACrE,qEAAqE;QACrE,kEAAkE;QAClE,qEAAqE;QACrE,iEAAiE;QACjE,qEAAqE;QACrE,mEAAmE;QACnE,kEAAkE;QAClE,mEAAmE;QACnE,wDAAwD;QACxD,OAAO;YACN,OAAO,EAAE,UAAU;YACnB,IAAI,EAAE,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC;SACpF,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IACzD,IAAI,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC;aAC7C,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;aAClC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/C,IAAI,UAAU,CAAC,QAAQ,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACtE,OAAO;YACN,OAAO,EAAE,QAAQ;YACjB,IAAI,EAAE;gBACL,gBAAgB;gBAChB,eAAe;gBACf,eAAe;gBACf,mBAAmB;gBACnB,GAAG,KAAK;gBACR,QAAQ;gBACR,OAAO;gBACP,OAAO;gBACP,QAAQ;gBACR,OAAO;gBACP,OAAO;gBACP,MAAM;gBACN,SAAS;gBACT,OAAO;gBACP,SAAS;gBACT,UAAU;aACV;SACD,CAAC;IACH,CAAC;IAED,MAAM,IAAI,uBAAuB,CAChC,kIAAkI,CAClI,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAyB;IAChE,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAClE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACjE,MAAM,IAAI,uBAAuB,CAChC,sEAAsE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,kDAAkD,CACxJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,kBAAkB,GAAG;IAC1B,MAAM;IACN,MAAM;IACN,MAAM;IACN,UAAU;IACV,QAAQ;IACR,UAAU;IACV,QAAQ;IACR,IAAI;IACJ,gBAAgB;IAChB,kBAAkB;IAClB,YAAY;CACH,CAAC;AAEX;;;;;;GAMG;AACH,SAAS,gBAAgB;IACxB,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS;YAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAChD,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAyB;IACvD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;IACxD,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,gBAAgB,EAAE,EAAE,CAAC,CAAC;AAC3F,CAAC","sourcesContent":["/**\n * OS-level sandbox spawn wrapper for the RLM Python REPL driver.\n *\n * This is the REAL security boundary described in\n * .planning/phases/28-repl-sandbox-safety/28-01-PLAN.md (\"IMPORTANT\" section\n * and Architecture section 1) -- NOT `repl_driver.py`'s Python-level\n * builtins/import allowlist (that's defense-in-depth for a\n * confused/prompt-injected LLM, not something that stops a deliberately\n * adversarial payload; the Python object graph makes in-process\n * confinement of arbitrary Python fundamentally unachievable -- see the\n * plan for the `__subclasses__`/`gi_frame.f_builtins` escapes that defeat\n * any purely in-process approach).\n *\n * **macOS**: wraps the interpreter with `sandbox-exec -f macos.sb ...`. The\n * SBPL profile (`../sandbox/macos.sb`) denies network and process-exec\n * entirely (which alone defeats `os.system`/`subprocess` -- they fork+exec\n * a shell -- independent of any Python-level import block) and scopes file\n * access to exactly the Python installation needed to boot plus the\n * session's workdir. Machine-specific paths (where python3 actually lives)\n * are discovered here at spawn time via a real subprocess call, never\n * hardcoded/guessed -- see `resolvePythonInstallation`.\n *\n * **Linux**: wraps with `unshare --user --map-root-user --net --mount --`\n * (empty net namespace = network unreachable at the kernel; mount\n * namespace for FS confinement), falling back to `bwrap` with equivalent\n * flags if `unshare` isn't available. Availability is detected at spawn\n * time, never assumed.\n *\n * **Fail closed everywhere**: if the sandboxing mechanism for the current\n * platform can't be established (wrapper binary missing, profile missing,\n * Python installation can't be discovered, unsupported platform), every\n * function here throws `SandboxUnavailableError` synchronously rather than\n * returning a command that would run the driver unwrapped. There is no\n * fallback path to an unsandboxed spawn anywhere in this module.\n */\n\nimport { type ChildProcess, execFileSync, spawn } from \"node:child_process\";\nimport { existsSync, realpathSync } from \"node:fs\";\nimport { dirname, join, delimiter as pathDelimiter } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst MACOS_PROFILE_PATH = join(__dirname, \"..\", \"sandbox\", \"macos.sb\");\nconst DEFAULT_SANDBOX_EXEC_BIN = \"/usr/bin/sandbox-exec\";\n\n/**\n * Thrown whenever the OS-level sandbox can't be established for the current\n * platform/environment. Callers (see `session.ts`) must let this propagate\n * and refuse to run rather than catching it and falling back to an\n * unwrapped spawn -- that fallback is exactly the failure mode Architecture\n * section 1's \"fail closed\" requirement exists to prevent.\n */\nexport class SandboxUnavailableError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\nexport interface SandboxSpawnOptions {\n\t/** Absolute path to `repl_driver.py`. */\n\tdriverPath: string;\n\t/**\n\t * Absolute path to the session's scratch workdir. The only place the\n\t * sandboxed process may read *and* write freely (besides the read-only\n\t * Python installation itself).\n\t */\n\tworkdir: string;\n\t/**\n\t * Which `python3` to sandbox. Defaults to whatever `python3` resolves to\n\t * on `PATH`. Overridable mainly so tests can point at a specific\n\t * interpreter without mutating `PATH`.\n\t */\n\tpythonBin?: string;\n\t/**\n\t * Override for the macOS `sandbox-exec` binary path. Mainly a test\n\t * injection point for proving fail-closed behavior (point it at a\n\t * nonexistent path and assert setup refuses rather than falling back to\n\t * an unwrapped spawn) -- see Architecture section 1's fail-closed\n\t * requirement and this plan's task 1 test 7.\n\t */\n\tsandboxExecBin?: string;\n\t/** Override for the Linux `unshare` binary path. Mainly for tests. */\n\tunshareBin?: string;\n\t/** Override for the Linux `bwrap` binary path (used if `unshare` is unavailable). Mainly for tests. */\n\tbwrapBin?: string;\n}\n\n/** The concrete command + args a `child_process.spawn` call should use. */\nexport interface SandboxedCommand {\n\tcommand: string;\n\targs: string[];\n}\n\ninterface PythonInstallation {\n\t/** `realpath()`'d absolute path to the interpreter binary that will actually run. */\n\trealBin: string;\n\t/**\n\t * Some macOS \"framework\" Python builds (the python.org installer,\n\t * Homebrew's `--with-framework`) internally `posix_spawn()` themselves\n\t * into a second binary at startup\n\t * (`Resources/Python.app/Contents/MacOS/Python`) before any user code\n\t * runs, to get a normal `.app` bundle identity (Tk/Cocoa access, Dock\n\t * icon, etc.). Confirmed empirically while scoping this profile: without\n\t * allowing this second exec, dyld aborts before `main()` ever runs. Equal\n\t * to `realBin` when no such companion binary exists.\n\t */\n\treexecBin: string;\n\t/** `realpath()`'d `sys.prefix` -- the install root the interpreter needs read access to in order to boot. */\n\tprefix: string;\n}\n\nconst pythonInstallationCache = new Map<string, PythonInstallation>();\n\n/**\n * Asks the given `python3` binary (via a real subprocess call -- there is no\n * static/config-file way to learn a Python install's true executable path\n * and stdlib root; every install lays these out differently) where it and\n * its stdlib actually live, then checks for the macOS framework-build\n * re-exec companion described above. Memoized per `pythonBin` string since\n * the answer can't change during this process's lifetime and this runs on\n * every sandboxed spawn.\n */\nfunction resolvePythonInstallation(pythonBin: string): PythonInstallation {\n\tconst cached = pythonInstallationCache.get(pythonBin);\n\tif (cached) return cached;\n\n\tlet stdout: string;\n\ttry {\n\t\tstdout = execFileSync(pythonBin, [\"-c\", \"import sys; print(sys.executable); print(sys.prefix)\"], {\n\t\t\tencoding: \"utf8\",\n\t\t});\n\t} catch (err) {\n\t\tthrow new SandboxUnavailableError(\n\t\t\t`sandbox_violation: could not run ${JSON.stringify(pythonBin)} to discover its installation -- refusing to run the REPL driver unsandboxed. (${\n\t\t\t\terr instanceof Error ? err.message : String(err)\n\t\t\t})`,\n\t\t);\n\t}\n\n\tconst lines = stdout.trim().split(\"\\n\");\n\tconst executableLine = lines[0];\n\tconst prefixLine = lines[1];\n\tif (!executableLine || !prefixLine) {\n\t\tthrow new SandboxUnavailableError(\n\t\t\t`sandbox_violation: unexpected output discovering the Python installation for ${JSON.stringify(pythonBin)}: ${JSON.stringify(stdout)}`,\n\t\t);\n\t}\n\n\tlet realBin: string;\n\tlet prefix: string;\n\ttry {\n\t\trealBin = realpathSync(executableLine.trim());\n\t\tprefix = realpathSync(prefixLine.trim());\n\t} catch (err) {\n\t\tthrow new SandboxUnavailableError(\n\t\t\t`sandbox_violation: could not resolve real filesystem paths for the Python installation -- refusing to run the REPL driver unsandboxed. (${\n\t\t\t\terr instanceof Error ? err.message : String(err)\n\t\t\t})`,\n\t\t);\n\t}\n\n\tconst reexecCandidate = join(prefix, \"Resources\", \"Python.app\", \"Contents\", \"MacOS\", \"Python\");\n\tconst reexecBin = existsSync(reexecCandidate) ? realpathSync(reexecCandidate) : realBin;\n\n\tconst installation: PythonInstallation = { realBin, reexecBin, prefix };\n\tpythonInstallationCache.set(pythonBin, installation);\n\treturn installation;\n}\n\n/** Resolves a bare command name against `PATH`, returning `null` if not found. Used for the Linux wrappers. */\nfunction resolveOnPath(name: string): string | null {\n\tconst pathEnv = process.env.PATH ?? \"\";\n\tfor (const dir of pathEnv.split(pathDelimiter)) {\n\t\tif (!dir) continue;\n\t\tconst candidate = join(dir, name);\n\t\tif (existsSync(candidate)) return candidate;\n\t}\n\treturn null;\n}\n\nfunction buildMacosCommand(opts: SandboxSpawnOptions): SandboxedCommand {\n\tconst sandboxExecBin = opts.sandboxExecBin ?? DEFAULT_SANDBOX_EXEC_BIN;\n\tif (!existsSync(sandboxExecBin)) {\n\t\tthrow new SandboxUnavailableError(\n\t\t\t`sandbox_violation: macOS sandbox-exec binary not found at ${JSON.stringify(sandboxExecBin)} -- refusing to run the REPL driver unsandboxed.`,\n\t\t);\n\t}\n\tif (!existsSync(MACOS_PROFILE_PATH)) {\n\t\tthrow new SandboxUnavailableError(\n\t\t\t`sandbox_violation: sandbox profile missing at ${JSON.stringify(MACOS_PROFILE_PATH)} -- refusing to run the REPL driver unsandboxed.`,\n\t\t);\n\t}\n\n\tconst { realBin, reexecBin, prefix } = resolvePythonInstallation(opts.pythonBin ?? \"python3\");\n\n\tlet workdir: string;\n\tlet driverPath: string;\n\ttry {\n\t\tworkdir = realpathSync(opts.workdir);\n\t\tdriverPath = realpathSync(opts.driverPath);\n\t} catch (err) {\n\t\tthrow new SandboxUnavailableError(\n\t\t\t`sandbox_violation: could not resolve workdir/driver paths -- refusing to run the REPL driver unsandboxed. (${\n\t\t\t\terr instanceof Error ? err.message : String(err)\n\t\t\t})`,\n\t\t);\n\t}\n\n\treturn {\n\t\tcommand: sandboxExecBin,\n\t\targs: [\n\t\t\t\"-D\",\n\t\t\t`PYTHON_REAL_BIN=${realBin}`,\n\t\t\t\"-D\",\n\t\t\t`PYTHON_REEXEC_BIN=${reexecBin}`,\n\t\t\t\"-D\",\n\t\t\t`PYTHON_PREFIX=${prefix}`,\n\t\t\t\"-D\",\n\t\t\t`DRIVER_PATH=${driverPath}`,\n\t\t\t\"-D\",\n\t\t\t`WORKDIR=${workdir}`,\n\t\t\t\"-f\",\n\t\t\tMACOS_PROFILE_PATH,\n\t\t\trealBin,\n\t\t\tdriverPath,\n\t\t],\n\t};\n}\n\nfunction buildLinuxCommand(opts: SandboxSpawnOptions): SandboxedCommand {\n\tconst pythonBin = opts.pythonBin ?? \"python3\";\n\n\tlet workdir: string;\n\tlet driverPath: string;\n\ttry {\n\t\tworkdir = realpathSync(opts.workdir);\n\t\tdriverPath = realpathSync(opts.driverPath);\n\t} catch (err) {\n\t\tthrow new SandboxUnavailableError(\n\t\t\t`sandbox_violation: could not resolve workdir/driver paths -- refusing to run the REPL driver unsandboxed. (${\n\t\t\t\terr instanceof Error ? err.message : String(err)\n\t\t\t})`,\n\t\t);\n\t}\n\n\tconst unshareBin = opts.unshareBin ?? resolveOnPath(\"unshare\");\n\tif (unshareBin && existsSync(unshareBin)) {\n\t\t// Empty user+net namespace: no interfaces besides loopback exist, so\n\t\t// network is unreachable at the kernel regardless of anything Python\n\t\t// itself tries. Mount namespace confines the filesystem view; the\n\t\t// workdir bind-mount (rw) plus the rest of the root (ro, implicit --\n\t\t// `unshare --mount` alone doesn't remount anything) is a coarser\n\t\t// boundary than the macOS profile's explicit allowlist, which is why\n\t\t// `--map-root-user` + a private mount namespace is paired with the\n\t\t// driver only ever being told about `workdir` for file I/O at the\n\t\t// Python-guardrail layer (Phase 28 task 2) -- the kernel-level net\n\t\t// denial is what task 1 owns and is unconditional here.\n\t\treturn {\n\t\t\tcommand: unshareBin,\n\t\t\targs: [\"--user\", \"--map-root-user\", \"--net\", \"--mount\", \"--\", pythonBin, driverPath],\n\t\t};\n\t}\n\n\tconst bwrapBin = opts.bwrapBin ?? resolveOnPath(\"bwrap\");\n\tif (bwrapBin && existsSync(bwrapBin)) {\n\t\tconst binds = [\"/usr\", \"/lib\", \"/bin\", \"/sbin\"]\n\t\t\t.filter((path) => existsSync(path))\n\t\t\t.flatMap((path) => [\"--ro-bind\", path, path]);\n\t\tif (existsSync(\"/lib64\")) binds.push(\"--ro-bind\", \"/lib64\", \"/lib64\");\n\t\treturn {\n\t\t\tcommand: bwrapBin,\n\t\t\targs: [\n\t\t\t\t\"--unshare-user\",\n\t\t\t\t\"--unshare-net\",\n\t\t\t\t\"--unshare-pid\",\n\t\t\t\t\"--die-with-parent\",\n\t\t\t\t...binds,\n\t\t\t\t\"--bind\",\n\t\t\t\tworkdir,\n\t\t\t\tworkdir,\n\t\t\t\t\"--proc\",\n\t\t\t\t\"/proc\",\n\t\t\t\t\"--dev\",\n\t\t\t\t\"/dev\",\n\t\t\t\t\"--chdir\",\n\t\t\t\tworkdir,\n\t\t\t\tpythonBin,\n\t\t\t\tdriverPath,\n\t\t\t],\n\t\t};\n\t}\n\n\tthrow new SandboxUnavailableError(\n\t\t\"sandbox_violation: neither `unshare` nor `bwrap` is available on this Linux host -- refusing to run the REPL driver unsandboxed.\",\n\t);\n}\n\n/**\n * Computes the sandboxed command/args for the current platform without\n * spawning anything. Exposed separately from `spawnSandboxed` so tests can\n * assert on the resolved invocation and so fail-closed behavior (throwing\n * `SandboxUnavailableError`) is observable synchronously, before any\n * process exists.\n */\nexport function resolveSandboxedCommand(opts: SandboxSpawnOptions): SandboxedCommand {\n\tif (process.platform === \"darwin\") return buildMacosCommand(opts);\n\tif (process.platform === \"linux\") return buildLinuxCommand(opts);\n\tthrow new SandboxUnavailableError(\n\t\t`sandbox_violation: no OS-level sandbox implementation for platform ${JSON.stringify(process.platform)} -- refusing to run the REPL driver unsandboxed.`,\n\t);\n}\n\n/**\n * Environment variables the sandboxed interpreter is allowed to see, by\n * allowlist rather than denylist. The OS sandbox itself denies network\n * access outright, so this isn't the primary defense against exfiltrating\n * anything read from here -- but the same object-graph escapes that defeat\n * in-process Python restriction (see this module's doc comment) can still\n * reach `os.environ` and write it into the session workdir even with\n * network denied, so the child process should never see more of the parent\n * Node process's environment (API keys, tokens, credentials, ...) than it\n * actually needs to boot a working interpreter.\n */\nconst SAFE_ENV_ALLOWLIST = [\n\t\"PATH\",\n\t\"HOME\",\n\t\"LANG\",\n\t\"LANGUAGE\",\n\t\"LC_ALL\",\n\t\"LC_CTYPE\",\n\t\"TMPDIR\",\n\t\"TZ\",\n\t\"PYTHONHASHSEED\",\n\t\"PYTHONIOENCODING\",\n\t\"PYTHONUTF8\",\n] as const;\n\n/**\n * Builds a scrubbed environment for the sandboxed child process from\n * `SAFE_ENV_ALLOWLIST` -- deliberately NOT `{ ...process.env }` (see\n * `SAFE_ENV_ALLOWLIST`'s doc comment for why the full parent environment,\n * secrets included, must not be handed to a process running LLM-authored\n * code).\n */\nfunction buildScrubbedEnv(): NodeJS.ProcessEnv {\n\tconst scrubbed: NodeJS.ProcessEnv = {};\n\tfor (const key of SAFE_ENV_ALLOWLIST) {\n\t\tconst value = process.env[key];\n\t\tif (value !== undefined) scrubbed[key] = value;\n\t}\n\treturn scrubbed;\n}\n\n/**\n * Spawns `repl_driver.py` wrapped in the platform's OS-level sandbox.\n * Throws `SandboxUnavailableError` synchronously (before any process is\n * created) if the sandbox can't be established -- there is no unwrapped\n * fallback path.\n */\nexport function spawnSandboxed(opts: SandboxSpawnOptions): ChildProcess {\n\tconst { command, args } = resolveSandboxedCommand(opts);\n\treturn spawn(command, args, { stdio: [\"pipe\", \"pipe\", \"pipe\"], env: buildScrubbedEnv() });\n}\n"]}

package/dist/session.d.ts

@@ -0,0 +1,162 @@
+/**
+ * `RlmSession` — the RLM root loop.
+ *
+ * root-LLM-produces-code -> REPL-executes -> truncated-stdout ->
+ * history-append -> FINAL-check, per
+ * .planning/phases/26-rlm-core-primitives/26-01-PLAN.md, Architecture
+ * section 4. Talks to `../python/repl_driver.py` over the newline-delimited
+ * JSON wire protocol documented in that file's module docstring (and
+ * section 2-3 of the plan).
+ */
+import type { RlmHistoryEntry, RlmResult, RlmSessionOptions } from "./types.js";
+/**
+ * Extracts Python source from a root-LLM response.
+ *
+ * Per R26-RLM.4, the response is expected to contain a ```repl or ```python
+ * fenced block (possibly surrounded by prose explaining the plan). Falls
+ * back to the whole (trimmed) response when no fence is present, so mocked
+ * `rootLlm` callbacks in tests can return raw code directly.
+ */
+export declare function extractPythonCode(response: string): string;
+/**
+ * Truncates captured stdout to `limit` characters, appending an explicit
+ * marker for how many characters were cut — matching the `[truncated N
+ * chars]` format R28-SBX.4 (Phase 28) will enforce as a hard cap. This phase
+ * only applies it as a plain formatting rule, not a safety mechanism.
+ */
+export declare function truncateStdout(stdout: string, limit: number): string;
+/**
+ * Restricted Python-literal parser used to turn a `FINAL_VAR`-produced
+ * `repr()` string back into a real JS value.
+ *
+ * Handles the JSON-safe subset the plan calls out: `None`/`True`/`False`,
+ * int/float, single- or double-quoted strings (with the common backslash
+ * escapes), lists, tuples (mapped to arrays — JS has no tuple type), and
+ * dicts (mapped to plain objects; keys are coerced with `String(...)`).
+ * Anything it can't parse (custom object reprs like `<Foo object at
+ * 0x...>`, sets, NaN/Infinity, etc.) falls back to the raw repr string
+ * rather than throwing, so a result is never lost — see the module-level
+ * note in this file's neighboring test for why raw-string fallback beats
+ * failing the whole run.
+ */
+export declare function pythonReprToValue(repr: string): unknown;
+export declare class RlmSession {
+    private readonly opts;
+    private readonly child;
+    private readonly workdir;
+    private readonly stdoutTruncateChars;
+    private readonly maxIterations;
+    private readonly stepTimeoutMs;
+    private readonly maxRssBytes;
+    private readonly rssPollIntervalMs;
+    private readonly maxSubCalls;
+    private readonly maxTotalCostUsd;
+    private readonly getAccumulatedCostUsd;
+    private readonly history;
+    private readonly ready;
+    private buffer;
+    private messageQueue;
+    private waiters;
+    private terminated;
+    private terminationError;
+    private lastFinal;
+    private subCallCount;
+    private rssPollTimer;
+    private rssPollInFlight;
+    constructor(opts: RlmSessionOptions);
+    private onStdoutChunk;
+    private markTerminated;
+    /**
+     * Hard-kills the driver subprocess and marks the session terminated with
+     * `error` in one step. Used by every resource-limit enforcement path (RSS
+     * ceiling, wall-clock timeout, budget exhaustion) -- these are Node-side
+     * hard kills, not attempts at graceful in-process recovery (Phase 28
+     * Architecture sections 3 and 6). `markTerminated`'s first-write-wins
+     * guard means whichever of these fires first supplies the message callers
+     * actually see, even though the child's own `exit` handler will also fire
+     * shortly after and try to (harmlessly, redundantly) mark terminated too.
+     */
+    private killAndTerminate;
+    /**
+     * Starts the Node-side RSS poll loop (Phase 28 Architecture section 3) --
+     * the real memory enforcement mechanism, not any Python-level
+     * `RLIMIT_AS`. Runs for the child process's whole lifetime; `unref()`d so
+     * it never by itself keeps the host Node process alive past everything
+     * else finishing. A `maxRssBytes <= 0` disables polling entirely.
+     */
+    private startRssPolling;
+    private pollRss;
+    /**
+     * Pre-dispatch sub-call budget check (Phase 28 Architecture section 6,
+     * R28-SBX.5): called *before* an `llm_query_request` is ever forwarded to
+     * `opts.llmQuery`, so the (budget+1)th attempted sub-call never actually
+     * dispatches -- the session is killed right here instead. Deliberately
+     * NOT also checked before dispatching a whole step: a step that never
+     * attempts another sub-call can still legitimately finish (e.g. call
+     * FINAL immediately) even after the budget is otherwise exhausted, and
+     * pre-emptively killing such a step here would be wrong.
+     */
+    private checkSubCallBudget;
+    /**
+     * Pre-dispatch cost budget check (Phase 28 Architecture section 6,
+     * R28-SBX.5): called before dispatching a step's `rootLlm` turn and
+     * before forwarding a sub-call to `opts.llmQuery`. No-ops unless both
+     * `maxTotalCostUsd` and `getAccumulatedCostUsd` are supplied -- see
+     * `RlmSessionOptions.maxTotalCostUsd`'s doc comment for why an unpaired
+     * option is a no-op rather than a guess.
+     */
+    private checkCostBudget;
+    /**
+     * Races `promise` against the configured wall-clock step timeout
+     * (Phase 28 Architecture section 3, R28-SBX.3) -- the real timeout
+     * enforcement mechanism. On expiry, hard-kills the driver subprocess and
+     * rejects with `RlmStepTimeoutError`, even if `promise` itself is stuck
+     * awaiting something that `markTerminated`'s waiter-rejection can't reach
+     * (e.g. a slow/hung `opts.llmQuery` callback, as opposed to a pending
+     * `nextMessage()` wait) -- the explicit `reject` here is what actually
+     * unblocks the caller in that case, not just a formality.
+     */
+    private withStepTimeout;
+    private nextMessage;
+    private send;
+    /**
+     * Sends one `exec` message and handles any `llm_query_request` round-trips
+     * until the matching `exec_result`, all under the wall-clock step timeout
+     * (`withStepTimeout`, Phase 28 Architecture section 3).
+     */
+    private runExec;
+    /** The message loop `runExec` races against the step timeout -- split out so `withStepTimeout` can wrap just this. */
+    private collectExecResult;
+    private seedContext;
+    /**
+     * Runtime proof the OS-level sandbox is actually enforcing for *this*
+     * process (Phase 28 Architecture section 1) -- sends `{"type":
+     * "self_test"}` and requires the driver's `self_test_result` response to
+     * report both a network connect attempt and an out-of-workdir file read
+     * failing. Throws `RlmSandboxViolationError` (fail-closed, refusing to run
+     * at all) if:
+     *   - the driver never responds (crash/hang -- guarded by the same
+     *     wall-clock timeout as a normal step, via `withStepTimeout`),
+     *   - the response isn't a well-formed `self_test_result`, or
+     *   - either check reports the sandbox did NOT block the attempt.
+     *
+     * Deliberately does not go through `runExec`/the guarded `exec()` wire
+     * message: `repl_driver.py`'s `_run_self_test` handles `self_test`
+     * on a route that bypasses its own Python-level guardrails (restricted
+     * builtins, import allowlist, AST screen) entirely, because a self-test
+     * *routed through* those guardrails would be a false positive -- e.g.
+     * `import socket` failing on the guardrail import allowlist looks
+     * identical to `import socket` failing because the OS sandbox denied the
+     * connection, even with the OS sandbox completely disabled. See
+     * `_run_self_test`'s docstring in repl_driver.py for the full reasoning.
+     */
+    private runSelfTest;
+    private resolveFinal;
+    /** One root-LLM turn: get code, exec it, append history, may resolve a final. */
+    step(): Promise<RlmHistoryEntry>;
+    /** Loops `step()` until a FINAL/FINAL_VAR, `maxIterations`, or an unrecoverable driver error. */
+    run(): Promise<RlmResult>;
+    /** Kills the underlying python3 subprocess and removes its scratch workdir. Safe to call more than once. */
+    dispose(): void;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA4GhF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASvD;AAoND,qBAAa,UAAU;IAwBV,OAAO,CAAC,QAAQ,CAAC,IAAI;IAvBjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA6B;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IAEtC,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,eAAe,CAAS;IAEhC,YAA6B,IAAI,EAAE,iBAAiB,EAyEnD;IAED,OAAO,CAAC,aAAa;IAqBrB,OAAO,CAAC,cAAc;IAatB;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;YAST,OAAO;IAoBrB;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAYvB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,IAAI;IAOZ;;;;OAIG;YACW,OAAO;IAKrB,sHAAsH;YACxG,iBAAiB;YA4BjB,WAAW;IAOzB;;;;;;;;;;;;;;;;;;;;;OAqBG;YACW,WAAW;IAyBzB,OAAO,CAAC,YAAY;IAWpB,iFAAiF;IAC3E,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC,CAyBrC;IAED,iGAAiG;IAC3F,GAAG,IAAI,OAAO,CAAC,SAAS,CAAC,CAoD9B;IAED,4GAA4G;IAC5G,OAAO,IAAI,IAAI,CAUd;CACD"}