pi-repl-py 0.1.1 → 0.2.1

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/docs/how-to-functions.md

@@ -1,108 +0,0 @@
-# How to add a toolbox function
-
-A toolbox function is one `.py` file that pi-repl loads into every kernel and
-surfaces to the model through the `execute` tool's prompt guidance (its
-signature + one-line summary appears in `promptGuidelines`). Add a file, and it
-shows up wherever the toolbox is read.
-
-> **When a change shows up.** The kernel loads the toolbox at boot, and the
-> `execute` tool builds its function list at registration (module load), so a
-> toolbox change (add/remove a file, rename one with a `_` prefix) is picked up
-> by a **session restart / `/reload`** — not mid-session.
-
-## Where functions live
-
-By default the extension ships four (`read`, `write`, `edit`, `bash`) in
-`src/engine/toolbox/`. To use your **own** set, set `toolboxDir` in your
-config:
-
-```jsonc
-// ~/.pi/agent/pi-repl/config.json
-{ "toolboxDir": "~/.pi/agent/pi-repl/functions" }
-```
-
-Use an absolute path or a `~`-prefixed one (`~` expands to your home). A bare relative
-path resolves from the process working directory, which is not reliable, so prefer
-an absolute path for a stable per-user folder. Point `toolboxDir` at a directory and
-every `*.py` there is loaded **in addition to** the shipped `read`/`write`/`edit`/`bash`.
-If a file in your folder has the **same name** as a built-in (e.g. `read.py`), your
-version wins and the built-in is ignored for that name.
-
-## The file contract
-
-Every toolbox file must:
-
-1. have a `def` whose signature is the real call an agent would use, and
-2. may declare `function_description` (a short one-line summary shown in the
-   prompt).
-
-A minimal, valid file:
-
-```python
-# pi-repl/functions/summarize.py
-function_description = """Return a first-sentence summary of a text."""
-
-__all__ = ["summarize"]
-
-def summarize(text, limit=1):
-    return ". ".join(text.split(". ")[:limit]) + "."
-```
-
-That is everything. `summarize` loads into the kernel and the `execute` tool's
-prompt guidance shows `summarize(text, limit=1)` after the next session restart.
-
-## The two pieces the loader reads
-
-**1. The signature comes from the `def`, not the description.**
-Arguments are read from the actual `def` line rather than hand-copied into a
-docstring, so the signature the model sees tracks the code for a normal
-single-line signature. Change `def summarize(text,
-limit=1):` to `limit=200`, and after the next session restart the prompt
-updates to match.
-
-**2. The description, from `function_description`, optional.**
-Used as the one-line summary in the `execute` tool's prompt guidance. If you
-omit it, the function is still advertised (by signature), just without a
-one-liner.
-
-Each file should also give the function a real docstring (the text under
-`def`). That docstring is shown by `help(name)` in the kernel and carries the
-deeper usage and gotchas. It does not go into the execute tool's prompt
-guidance (only the one-line `function_description` does). Keep it for
-details, the venv note, and edge cases.
-
-## How much to document
-
-`function_description` is the summary; the `def` docstring is the detail. A
-good `function_description` is one line ("Run a shell command and return its
-result."). A good docstring explains arguments, return value, and any
-non-obvious behavior, including environment facts the model needs
-("the evaluator runs in a project-local venv, not the system python").
-
-## Disabling a file without deleting it
-
-Rename the file to start with an underscore: `_test_helper.py`. The loader
-**(and the execute tool's prompt guidance)** skip underscore-prefixed files, so
-it never reaches the kernel or the model. Use this for scratch or internal
-helpers.
-
-## Good practice
-
-- One function per file, name matches the function.
-- Keep `function_description` one line. Everything else goes in the docstring.
-- Let the signature carry the truth; the description says what it's *for*.
-- A function that can hang (a shell call, network) should say so in its
-  docstring so the model knows the trade-off.
-
-## Confirming it worked
-
-At a `pi --repl` prompt, run a cell:
-
-```python
-print(ls())           # list what's loaded
-print(help('summarize'))  # signature + full docstring details
-```
-
-If `summarize` shows up in `ls()` and `help`, it loaded. The `execute` tool's
-prompt guidance also lists it (same first-line summary) after the next session
-restart.