pi-repl-py 0.1.1 → 0.2.0

package/src/extension/prompt.ts

@@ -1,54 +1,76 @@
-// --- prompt: the execute tool's model-facing contract (pure, no pi/toolbox dependency) ---
-// --- mirrors pi-robust-edit's schema/domain split: content lives here; the thin adapter in tool-meta wires it in ---
+// --- prompt: the execute tool's model-facing contract (pure, no pi/helper dep) ---
 
 export const executeToolDescription =
-	"Execute Python in a persistent evaluator — the session's working memory. Variables, imports, " +
-	"functions, and data survive across every call. read, write, edit, and bash are Python functions " +
-	"available in every cell, not separate tools. A cell returns its final expression; anything else " +
-	"prints. Runs in the project-local venv, so a command that starts python or pip must target that venv.";
+	"You have one tool: a persistent Python workspace backed by a real `ipython` kernel. " +
+	"Variables, imports, functions, and data survive across cells and turns. Use this tool to read files, " +
+	"run shell commands, search code, transform data, and build up solutions — all inside Python. " +
+	"Helpers in `~/.pi/agent/pi-repl/helpers/` are loaded at boot as functions; see what's loaded with " +
+	"`[k for k in globals() if not k.startswith('_')]`. A cell returns its final expression; printed output " +
+	"is captured separately.";
 
 export const executePromptSnippet =
-	"Execute Python in a persistent evaluator whose variables, imports, and functions survive across " +
-	"calls; read/write/edit/bash are Python functions in every cell, plus anything you define and reuse; " +
-	"ls() lists them, help(name) shows usage";
+	"Use the Python workspace: keep state in variables, batch independent reads/searches in one cell, " +
+	"edit files safely, and iterate in small cells.";
 
-// --- the function doctrine riding the execute tool; sections keep every rule findable and rankable as hard or soft ---
+// --- the workspace doctrine riding the execute tool ---
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
-		"## What's in every cell",
-		...preloaded,
-		"Not sure what's available? Call ls() first; help(name) shows a signature and notes.",
-		"",
-		"## How to use them",
-		"These are your file and shell tools — call them. Don't reimplement read/write/edit/bash in Python, " +
-			"and don't fork a near-copy under a new name; a new def overwrites an old one by name, so extend " +
-			"the existing function instead.",
-		"Define a new function only to reuse it: if you'll run this shape again with different inputs, write " +
-			"it once as def and call it by arguments — otherwise just run the cell.",
-		"Do the job, then answer with the result. Don't tell the user you 'defined a function' or 'built a " +
-			"tool'; that's internal machinery.",
-		"",
-		"## Examples",
-		"Good — defined once, called by arguments:",
-		"  def fetch_news(query, hl='en', gl='US', limit=15): <fetch + parse to a list>",
-		"  fetch_news('Turkey')",
-		"  fetch_news('Nigeria', hl='en-NG')",
-		"Compose them:",
-		"  def find_files(pattern, root='.'): <walk root, filter by pattern>",
-		"  def count_lines(paths): ...",
-		"  count_lines(find_files('*.csv'))      # one call",
-		"",
-		"## Efficiency",
-		"Everything a cell prints stays in context for the whole turn, so print slices, matches, or counts — " +
-			"never whole files — and keep large values in variables.",
-		"For whole-filesystem or large-directory scans, use the shell tools (find, fd, du, grep), not a " +
-			"Python os.walk: it pays a syscall per file and runs minutes on a big tree. Example: " +
-			"`find -xdev -type f -size +100M | sort -rn | head`. Reserve Python for analysing the results.",
-		"",
-		"## When it breaks",
-		"If the output starts with <rlm_engine_reset>, the kernel was rebuilt: data is restored but your " +
-			"functions are gone — recreate any helper you need and re-verify a variable before trusting it.",
-		"The standard library is available; don't install packages into the evaluator. Run out-of-tree " +
-			"projects through their own environment.",
+		"## This workspace is your only tool",
+		"In `--repl` mode, `execute` is the only callable tool. Read files, run shell, search, and edit " +
+			"all happen inside Python.",
+		"",
+		"## The loop is generate → execute → observe → iterate",
+		"Write a cell, run it, observe the result, then write the next cell. Build solutions incrementally.",
+		"",
+		"## State persists",
+		"Variables, imports, and functions survive across cells and turns. Assign read/search results to " +
+			"named variables and reuse them.",
+		"",
+		"## Chain big tasks into verifiable steps",
+		"Break ambitious requests into independently checkable steps. Confirm assumptions before writing " +
+			"code that depends on them.",
+		"",
+		"## Shell & files are plain Python",
+		"`!cmd` / `%%bash` for fire-and-forget shell; `subprocess.run(..., timeout=...)` when you need the result back " +
+			"as a value — always set a `timeout` on anything that could hang (the evaluator does not kill a " +
+			"silent cell automatically). `open()` / `pathlib` read and write files. For safe edits: read the full " +
+			"file, modify in memory, write once, then re-read to verify.",
+		"",
+		"## Batch independent work, keep exploratory cells small",
+		"Batch independent reads, searches, and setup steps in one cell to reduce round-trips. Keep " +
+			"exploratory/iterative cells small so you can observe and adjust.",
+		"",
+		"## Search efficiently",
+		"Use `rg`, `fd`, `grep`, `find` via `subprocess.run` for deep searches, not Python loops.",
+		"",
+		...(preloaded.length
+			? [
+					"## Helpers",
+					"User helpers load from `~/.pi/agent/pi-repl/helpers/`. Their descriptions appear below. " +
+						"List what's loaded with `[k for k in globals() if not k.startswith('_')]`.",
+					"",
+					...preloaded,
+					"",
+				]
+			: []),
+		"## Compose and reuse",
+		"If the same pattern appears more than once, wrap it in a `def` and reuse it.",
+		"",
+		"## Output discipline",
+		"Printing is a context cost: everything a cell prints stays in the transcript. Print slices, " +
+			"counts, and summaries. Keep large values in variables. End a cell with `;` to suppress the " +
+			"last-expression echo.",
+		"",
+		"## Environment boundary",
+		"The evaluator runs in a project-local venv, not the system Python. Do not install a target project's " +
+			"dependencies into the evaluator just to make that project run there. Run external projects " +
+			"through their own interface and normal commands.",
+		"",
+		"## Engine reset guard",
+		"If the output begins with `<repl_engine_reset>`, the kernel was rebuilt from the last snapshot. " +
+			"Some variables may be revived, some lost, and anything defined after the snapshot is gone. " +
+			"Re-verify variables before reusing them — never interpolate a restored variable into a shell " +
+			"command until you have confirmed it still holds what you expect. Functions, classes, and live " +
+			"handles cannot be snapshotted and must be redefined.",
 	];
 }

package/src/extension/render-core.ts

@@ -1,4 +1,4 @@
-// --- pure layout, free of pi imports so unit tests can drive it directly ---
+/** Pure layout, free of pi imports so unit tests drive it directly. */
 
 export interface ExecuteDetails {
 	status?: "ok" | "error" | "aborted" | string;
@@ -21,7 +21,7 @@ export interface ExecuteRenderState {
 	hasResult: boolean;
 }
 
-import { previewCell } from "./preview-core.js";
+import { previewCell } from "./preview/index.js";
 
 export type StatusKind = "error" | "aborted" | "running" | "queued" | "done";
 export type BgKind = "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
@@ -49,11 +49,7 @@ export function formatDuration(durationMs: number | undefined): string | undefin
 
 const SGR_PATTERN = /\x1b\[([0-9;]*)m/g;
 
-/**
- * Append a reset when `line` ends with a foreground or background color still
- * open, so a span that wrapping split across lines cannot bleed into the
- * trailing padding or the next row.
- */
+/** Close an open color so a line wrapped across words can't bleed into padding or the next row. */
 export function closeOpenSgr(line: string): string {
 	let fgOpen = false;
 	let bgOpen = false;
@@ -134,7 +130,7 @@ function outputText(state: ExecuteRenderState): string {
 function topLine(state: ExecuteRenderState, width: number, deps: RenderDeps): string {
 	const code = state.code.trimEnd();
 	const preview = previewCell(code);
-	const language = preview.kind === "shell" ? "repl · shell" : preview.kind === "agent" ? "repl · agent" : "repl";
+	const language = preview.kind === "shell" ? "repl · shell" : "repl";
 	const prefix = `${marker(state, deps)} ${deps.fg("muted", language)}`;
 
 	// --- suffix priority: expand hint > error > duration > counts, so truncation never hides the expand key ---
@@ -168,7 +164,7 @@ function topLine(state: ExecuteRenderState, width: number, deps: RenderDeps): st
 	// --- budget: width minus leading space, prefix, suffix, and separators ---
 	const fixed = 1 + deps.visibleWidth(prefix) + separatorWidth + deps.visibleWidth(suffix);
 	const previewBudget = Math.max(8, width - fixed - separatorWidth);
-	// --- a semantic preview is a one-line summary; highlight Python code, accent shell/agent intent ---
+	// --- a semantic preview is a one-line summary; highlight Python code, accent shell intent ---
 	let middle = "";
 	if (preview.text) {
 		const previewText =

package/src/extension/render.ts

@@ -1,9 +1,4 @@
-/**
- * TUI adapter for the `execute` cell renderer.
- *
- * Binds pi's theme, syntax highlighting, key hints, and width primitives to the
- * pure layout in render-core.ts, which is unit-tested outside pi's runtime.
- */
+/** TUI adapter binding pi's theme/width to the unit-tested pure layout in render-core.ts. */
 
 import { highlightCode, keyHint, keyText, rawKeyHint, type Theme } from "@mariozechner/pi-coding-agent";
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
@@ -35,11 +30,7 @@ function makeDeps(theme: Theme): RenderDeps {
 	};
 }
 
-/**
- * The layout of a cell only changes when its state or the spinner frame does,
- * but the TUI repaints on every frame. Rendering from a key of both stops the
- * recompute-per-frame (and with it, flicker on wide panes).
- */
+/** The layout only changes on state/spinner change, but the TUI repaints every frame; key by both to avoid recompute flicker. */
 function renderVersion(state: ExecuteRenderState): string {
 	const details = state.details ? JSON.stringify(state.details) : "";
 	return [

package/src/extension/session-engine.ts

@@ -1,12 +1,8 @@
-// A session may get teardown without session_start on reload, so revival is part of create() (was a real defect)
+// revival is part of create() so a session that gets teardown without a session_start reload still revives
 
 import type { RestoreResult } from "../engine/index.js";
 
-/**
- * A revived session can carry hundreds of variables; listing them all turns
- * the banner and the reset notice into a wall. Show enough to orient, then
- * count the rest.
- */
+/** Show enough names to orient, then count the rest (a revive can carry hundreds). */
 export function summarizeNames(names: readonly string[], limit: number): string {
 	if (names.length <= limit) return names.join(", ");
 	return `${names.slice(0, limit).join(", ")} … and ${names.length - limit} more`;
@@ -22,23 +18,15 @@ export interface EngineLifecycleDeps<E extends RevivableEngine> {
 	create(): E;
 	/** Tears the current engine down, flushing its final snapshot. */
 	dispose(engine: E): Promise<void>;
-	/**
-	 * Tears down an engine that cannot cooperate — a wedged guest cannot serve
-	 * the snapshot flush dispose would ask of it. Falls back to dispose.
-	 */
+	/** Kill-then-rebuild when a wedged engine cannot serve the snapshot flush. */
 	discard?(engine: E): Promise<void>;
 }
 
-/**
- * Why an engine came into existence. `startup` is the expected path and is
- * already announced in the transcript; `cell` means an engine had to be built
- * to serve a tool call, which only happens when the previous one went away
- * mid-session — the case the model needs told about in-band.
- */
+/** `startup` is announced in the transcript; `cell` means an engine was rebuilt mid-session and needs an in-band notice. */
 export type AcquireOrigin = "startup" | "cell";
 
 function formatEngineResetNotice(restore: RestoreResult | null): string {
-	const lines = ["<rlm_engine_reset>"];
+	const lines = ["<repl_engine_reset>"];
 	if (!restore) {
 		// --- no snapshot at all: namespace is genuinely empty ---
 		lines.push(
@@ -73,7 +61,7 @@ function formatEngineResetNotice(restore: RestoreResult | null): string {
 		}
 		lines.push("Anything defined after the last snapshot is also gone.");
 	}
-	lines.push("Re-verify a variable before reusing it, especially inside shell interpolation.", "</rlm_engine_reset>");
+	lines.push("Re-verify a variable before reusing it, especially inside shell interpolation.", "</repl_engine_reset>");
 	return lines.join("\n");
 }
 
@@ -81,25 +69,19 @@ export class EngineLifecycle<E extends RevivableEngine> {
 	private engine?: E;
 	private revival?: Promise<RestoreResult | null>;
 	private pendingNotice?: string;
-	/** Teardown in progress; a rebuild must not overlap the final snapshot flush. */
 	private teardown?: Promise<void>;
-	/** First-build in progress: concurrent acquire() must not spawn two engines. */
+	/** First-build in progress. */
 	private acquiring?: Promise<{ engine: E; restore: RestoreResult | null; created: boolean }>;
 
 	constructor(private readonly deps: EngineLifecycleDeps<E>) {}
 
-	/**
-	 * The live engine, built and revived if it does not exist yet.
-	 * Revival is awaited here so a caller never sees an un-revived namespace.
-	 */
+	/** Built and revived on demand; awaited so callers never see an un-revived namespace. */
 	async acquire(origin: AcquireOrigin): Promise<{ engine: E; restore: RestoreResult | null; created: boolean }> {
 		if (this.engine) {
 			return { engine: this.engine, restore: await this.revival!, created: false };
 		}
-		// --- two concurrent acquires on an empty engine must share one build ---
 		if (this.acquiring) return this.acquiring;
 		const build = (async () => {
-			// --- a teardown flushing its final snapshot must finish before the rebuild reads it ---
 			while (this.teardown) await this.teardown;
 			if (this.engine) {
 				const held: E = this.engine;
@@ -131,11 +113,7 @@ export class EngineLifecycle<E extends RevivableEngine> {
 		await this.teardownWith((engine) => this.deps.dispose(engine));
 	}
 
-	/**
-	 * Teardown for an engine that cannot cooperate (e.g. wedged in synchronous
-	 * code). Skips the snapshot flush a graceful dispose would attempt; the next
-	 * acquire builds a fresh engine revived from the last completed snapshot.
-	 */
+	/** Kill-then-rebuild for a wedged engine; skips the final snapshot flush, uses the last good one. */
 	async discard(): Promise<void> {
 		await this.teardownWith((engine) => (this.deps.discard ?? this.deps.dispose)(engine));
 	}

package/src/extension/tool-meta.ts

@@ -1,15 +1,15 @@
 // --- tool-meta: thin surface assembling the execute tool's prompt from pure modules ---
-// --- the model contract lives in prompt.ts; only the toolbox wiring stays here ---
+// --- the model contract lives in prompt.ts; only the helpers wiring stays here ---
 
+import { buildHelpersMap } from "./helpers.js";
 import { buildPromptGuidelines, executePromptSnippet, executeToolDescription } from "./prompt.js";
-import { buildToolboxMap } from "./toolbox.js";
 
 export const EXECUTE_DESCRIPTION = executeToolDescription;
 export const EXECUTE_PROMPT_SNIPPET = executePromptSnippet;
 
-// --- build the guidelines from the toolbox, falling back when nothing is preloaded ---
-export function buildExecutePromptGuidelines(toolboxDir?: string): string[] {
-	const map = buildToolboxMap(toolboxDir);
-	const preloaded = map.length > 0 ? map : ["(none preloaded: define your own)"];
+// --- build the guidelines from the one helpers dir (default ~/.pi/agent/pi-repl/helpers) ---
+export function buildExecutePromptGuidelines(): string[] {
+	const map = buildHelpersMap();
+	const preloaded = map.length > 0 ? map : [];
 	return buildPromptGuidelines(preloaded);
 }

package/src/engine/guest.py

@@ -1,320 +0,0 @@
-"""
-guest.py — the real IPython kernel guest evaluator for pi-repl.
-
-The host spawns this once. It starts a local ipykernel subprocess via
-jupyter_client, keeps it for the session, and bridges the wire protocol to it
-(stdin = commands, fd 3 = results). State survives because the kernel process
-does. Frames carry a nonce the host mints and the guest erases, so agent code
-cannot forge protocol traffic.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import sys
-import time
-
-# --- protocol envelope ---
-ENVELOPE_KEY = "__rlm"
-NONCE_ENV = "PI_RLM_NONCE"
-PROTOCOL_FD = 3
-
-NONCE = os.environ.get(NONCE_ENV, "")
-os.environ.pop(NONCE_ENV, None)
-
-# --- per-cell timeout: 0 = no cap; else a silence watchdog (no output for N seconds) ---
-CELL_TIMEOUT_S = float(os.environ.get("PI_REPL_TIMEOUT_MS", "0") or "0") / 1000.0
-
-# --- snapshot/restore use a fixed window, not the cell silence timer ---
-SNAPSHOT_TIMEOUT_S = 90.0
-
-# --- cap buffered output so a runaway print can't grow guest memory or send one giant frame ---
-MAX_CELL_OUTPUT_CHARS = 1_000_000
-
-# --- fd 3 protocol writer; dup'd so we don't close the caller's fd 3 on exit ---
-_proto = os.fdopen(os.dup(PROTOCOL_FD), "w", buffering=1)
-
-
-def _send(msg):
-    envelope = {ENVELOPE_KEY: 1, **msg}
-    if NONCE:
-        envelope["n"] = NONCE
-    _proto.write(json.dumps(envelope) + "\n")
-    _proto.flush()
-
-
-def _decode(line):
-    if ENVELOPE_KEY not in line:
-        return None
-    try:
-        obj = json.loads(line)
-    except Exception:
-        return None
-    if obj.get(ENVELOPE_KEY) != 1 or not isinstance(obj.get("type"), str):
-        return None
-    if NONCE and obj.get("n") != NONCE:
-        return None
-    return obj
-
-
-# --- toolbox: one function per *.py, exec'd into every kernel (PI_TOOLBOX_DIR) ---
-
-def _toolbox_files(directory):
-    """Return {function_name: source} for each *.py in `directory`."""
-    if not directory:
-        return {}
-    d = os.path.expanduser(directory)
-    if not os.path.isdir(d):
-        return {}
-    names = {}
-    for entry in sorted(os.listdir(d)):
-        if not entry.endswith(".py"):
-            continue
-        name = entry[:-3]
-        if not name.isidentifier() or name.startswith("_"):
-            continue
-        try:
-            with open(os.path.join(d, entry), encoding="utf-8") as f:
-                names[name] = f.read()
-        except OSError:
-            continue
-    return names
-
-DEFAULT_TOOLBOX_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "toolbox")
-TOOLBOX_DIR = os.environ.get("PI_TOOLBOX_DIR", "").strip()
-# --- Merge: built-ins are supreme; a config toolboxDir adds others and overrides on name ---
-_TOOLBOX_SRC = _toolbox_files(DEFAULT_TOOLBOX_DIR)
-if TOOLBOX_DIR and os.path.expanduser(TOOLBOX_DIR) != DEFAULT_TOOLBOX_DIR:
-    _TOOLBOX_SRC.update(_toolbox_files(TOOLBOX_DIR))
-
-# --- help/ls are part of the evaluator, not the toolbox ---
-INTRINSIC = """
-# --- ls() filters IPython-injected names out of the tool list ---
-_RPL_LS_NOISE = {'exit', 'quit', 'get_ipython', 'open', 'display'}
-
-def ls():
-    return sorted(n for n in globals() if n not in _RPL_LS_NOISE and not n.startswith('_') and callable(globals()[n]))
-
-def help(name=None):
-    if name is None:
-        return ls()
-    fn = globals().get(name)
-    if fn is None or not callable(fn):
-        return f"no such function: {name!r}"
-    return fn.__doc__ or f"{name} (no docstring)"
-"""
-
-
-from jupyter_client import KernelManager
-
-
-class Kernel:
-    """A persistent subprocess ipykernel + blocking client."""
-
-    def __init__(self):
-        self.km = KernelManager(kernel_name="python3")
-        self.km.start_kernel()
-        self.kc = self.km.client()
-        self.kc.start_channels()
-        self.kc.wait_for_ready(timeout=30)
-        self._preload()
-
-    def _preload(self):
-        """Exec every toolbox function + the intrinsic help/ls into the kernel ns."""
-        code = INTRINSIC + "\n"
-        for src in _TOOLBOX_SRC.values():
-            code += src + "\n"
-        if code.strip():
-            self.kc.execute(code)
-            self._drain()
-
-    def _drain(self):
-        try:
-            while True:
-                m = self.kc.get_iopub_msg(timeout=1)
-                if m.get("msg_type") == "status" and m.get("content", {}).get("execution_state") == "idle":
-                    break
-        except Exception:
-            pass
-
-    def _drain_execution(self, code, timeout):
-        """Run `code`; return (stdout, stderr, error_text, result, timed_out).
-
-        `timeout <= 0` means "no cap": a cell runs until it reports idle.
-        `timeout > 0` is a SILENCE watchdog — it trips only once the cell has
-        produced no message for `timeout` seconds. A silent-but-running command
-        (e.g. `find ... | sort`) is allowed to complete; a stalled one (dead
-        kernel, or nothing for the silence window) reports `timed_out=True` so
-        the caller can surface a real hang instead of faking success.
-        """
-        msg_id = self.kc.execute(code)
-        out, err, error, result = [], [], None, None
-        out_len, err_len = 0, 0
-        timed_out = False
-        # --- silence clock only starts once the cell begins (grace for a fresh kernel) ---
-        last_activity: float | None = None
-        while True:
-            if not self.km.is_alive():
-                timed_out = True
-                break
-            if last_activity is not None and timeout and (time.monotonic() - last_activity) >= timeout:
-                timed_out = True
-                break
-            wait = (timeout - (time.monotonic() - last_activity)) if (last_activity is not None and timeout) else 0.25
-            try:
-                m = self.kc.get_iopub_msg(timeout=max(0.01, min(0.25, wait)))
-            except Exception:
-                continue
-            if m.get("parent_header", {}).get("msg_id") != msg_id:
-                continue
-            if last_activity is None:
-                last_activity = time.monotonic()
-            else:
-                last_activity = time.monotonic()
-            mt = m.get("msg_type")
-            c = m.get("content", {})
-            if mt == "stream":
-                is_out = c.get("name") == "stdout"
-                text = c.get("text", "") or ""
-                if is_out:
-                    if out_len < MAX_CELL_OUTPUT_CHARS:
-                        take = text[: MAX_CELL_OUTPUT_CHARS - out_len]
-                        out.append(take)
-                        out_len += len(take)
-                else:
-                    if err_len < MAX_CELL_OUTPUT_CHARS:
-                        take = text[: MAX_CELL_OUTPUT_CHARS - err_len]
-                        err.append(take)
-                        err_len += len(take)
-            elif mt == "execute_result":
-                result = c.get("data", {}).get("text/plain")
-            elif mt == "error":
-                error = "\n".join(c.get("traceback", ["(no traceback)"]))
-            elif mt == "status" and c.get("execution_state") == "idle":
-                break
-        if timed_out:
-            # --- best-effort cancel so the NEXT cell doesn't queue behind this one ---
-            try:
-                self.kc.interrupt_kernel()
-            except Exception:
-                pass
-        return "".join(out), "".join(err), error, result, timed_out
-
-    def execute(self, code):
-        """Idle-sync path used by snapshot/restore; not a user cell."""
-        return self._drain_execution(code, SNAPSHOT_TIMEOUT_S)[:4]
-
-    def run_cell(self, code):
-        """Run a user cell under the per-cell timeout, so the model learns
-        when work did not finish."""
-        return self._drain_execution(code, CELL_TIMEOUT_S)
-
-    def snapshot_globals(self):
-        # --- snapshot only user state (skip toolbox/intrinsic functions and _ names) ---
-        tool_names = sorted(set(_TOOLBOX_SRC) | {"ls", "help", "function_description"})
-        skip_names = json.dumps(tool_names)
-        out, _, _, _ = self.execute(
-            "import pickle as _pk, base64 as _b64, json as _js\n"
-            "__rlm_skip = set(" + skip_names + ") | {'In','Out','get_ipython','exit','quit','open'}\n"
-            "__rlm_v = {}\n__rlm_f = []\n"
-            "for _k, _v in list(globals().items()):\n"
-            "    # skip IPython bookkeeping and names with a leading underscore\n"
-            "    if _k.startswith('__') or _k.startswith('_') or _k in __rlm_skip:\n"
-            "        continue\n"
-            "    try:\n"
-            "        __rlm_v[_k] = _b64.b64encode(_pk.dumps(_v)).decode()\n"
-            "    except Exception as _e:\n"
-            "        __rlm_f.append({'name': _k, 'reason': str(_e)})\n"
-            "print('__RLC_SNAPSHOT__' + _js.dumps({'vars': __rlm_v, 'failed': __rlm_f}))\n"
-        )
-        marker = "__RLC_SNAPSHOT__"
-        if marker not in out:
-            # --- marker never printed: serialization stalled; report incomplete so the host keeps the last good file ---
-            return {}, [], False
-        try:
-            o = json.loads(out.split(marker)[-1])
-            return o.get("vars", {}), o.get("failed", []), True
-        except Exception:
-            return {}, [], False
-
-    def restore_globals(self, vars_):
-        if not vars_:
-            return [], []
-        # --- restore each variable in one atomic kernel call so one failure reports itself ---
-        code2 = (
-            "import pickle as _pk, base64 as _b64, json as _js\n"
-            "__rl_r = {'restored': [], 'failed': []}\n"
-            + "\n".join(
-                "try:\n"
-                f"    globals()[{name!r}] = _pk.loads(_b64.b64decode({b64!r}))\n"
-                f"    __rl_r['restored'].append({name!r})\n"
-                "except Exception as _e:\n"
-                f"    __rl_r['failed'].append({{'name': {name!r}, 'reason': str(_e)}})\n"
-                for name, b64 in vars_.items()
-            )
-            + "\nprint('__RLC_RESTORE__' + _js.dumps(__rl_r))"
-        )
-        out, _, _, _ = self.execute(code2)
-        marker = "__RLC_RESTORE__"
-        if marker not in out:
-            return [], []
-        try:
-            obj = json.loads(out.split(marker)[-1])
-            return obj.get("restored", []), obj.get("failed", [])
-        except Exception:
-            return [], []
-
-
-def _line_error(text):
-    lines = text.split("\n")
-    return {"name": "", "message": text, "stack": lines[:12]}
-
-
-def main():
-    kernel = Kernel()
-    _send({"type": "ready"})
-
-    for line in sys.stdin:
-        msg = _decode(line)
-        if not msg:
-            continue
-        t = msg["type"]
-        if t == "ping":
-            _send({"type": "pong", "id": msg["id"]})
-        elif t == "snapshot":
-            vars_, failed, complete = kernel.snapshot_globals()
-            _send({"type": "snapshot_result", "id": msg["id"], "vars": vars_, "failed": failed, "complete": complete})
-        elif t == "restore":
-            restored, failed = kernel.restore_globals(msg.get("vars", {}))
-            _send({"type": "restore_result", "id": msg["id"], "restored": restored, "failed": failed})
-        elif t == "list_names":
-            names = list(kernel.snapshot_globals()[0].keys())
-            _send({"type": "names_result", "id": msg["id"], "names": names})
-        elif t == "run":
-            cell_id = msg.get("cellId")
-            stdout, stderr, error, result, timed_out = kernel.run_cell(msg.get("code", ""))
-            if stdout:
-                _send({"type": "stream", "cellId": cell_id, "name": "stdout", "chunk": stdout})
-            if stderr:
-                _send({"type": "stream", "cellId": cell_id, "name": "stderr", "chunk": stderr})
-            if timed_out:
-                tmsg = {
-                    "name": "Timeout",
-                    "message": f"cell did not finish within {CELL_TIMEOUT_S:g}s and may still be running",
-                    "stack": ["[cell timed out]"],
-                }
-                _send({"type": "done", "cellId": cell_id, "status": "error", "error": tmsg})
-            elif error:
-                _send({"type": "done", "cellId": cell_id, "status": "error", "error": _line_error(error)})
-            else:
-                _send({"type": "done", "cellId": cell_id, "status": "ok", "result": result})
-        # --- a single-threaded guest can't read 'abort' mid-cell; the host discards+rebuilds ---
-
-
-if __name__ == "__main__":
-    try:
-        main()
-    except Exception as e:
-        _send({"type": "done", "cellId": "", "status": "error", "error": _line_error(str(e))})
-        sys.exit(1)