pi-repl-py 0.2.5 → 0.2.7

package/README.md

@@ -1,4 +1,4 @@
-# pi-repl
+# pi-repl-py
 
 A [pi](https://pi.dev) extension that gives the agent a single `execute` tool backed by a
 **persistent Python evaluator**: a real `ipython` kernel that keeps variables, functions, imports,
@@ -32,7 +32,15 @@ A plain `pi` session is untouched; the extension is dormant until `--repl` is pa
 
 ## Installing as a pi package
 
-`npm install` runs a `postinstall` that creates the Python venv the evaluator needs, at a stable
+Install the package from npm or directly from GitHub:
+
+```bash
+pi install npm:pi-repl-py
+# or
+pi install github:k3-2o/pi-repl-py
+```
+
+The install runs a `postinstall` that creates the Python venv the evaluator needs, at a stable
 per-user path (`~/.pi/agent/pi-repl/venv`). If `python3` or the network is missing, it prints a
 clear notice. How the interpreter is resolved is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 

package/docs/ARCHITECTURE.md

@@ -87,10 +87,12 @@ finished draining on iopub. A cell settles only when **both** the `execute_reply
 matching iopub `status idle` (published after every byte of output) have arrived. Settling
 on the reply alone would drop output that was still in flight.
 
-**Output is capped per channel.** Each channel accumulates output against a character budget
-(`maxOutputChars`). Overflow is checked within each message. A single 10 MB print trips the
-cap immediately instead of waiting for a later message to exhaust the budget. The host appends
-an explicit truncation marker so the model knows output was cut.
+**Output is capped per channel and per line.** Each channel accumulates output against a character
+budget (`maxOutputChars`), checked within each message, so overflow trips the moment a message
+exceeds the budget rather than when it churns on. Each individual line is also capped at a generous
+length (4096 chars), so a single genuinely oversized line cannot own the whole budget — while
+legitimately long REPL output (JSON, reprs, errors) still passes through whole. Both truncations
+are announced with explicit markers so the model knows output was cut.
 
 **Cancellation is real.** An abort sends an `interrupt_request` on the control channel,
 which raises a genuine `KeyboardInterrupt` in the running cell; the namespace survives. As a

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.2.5",
+	"version": "0.2.7",
 	"type": "module",
 	"description": "A pi extension with a single tool: execute, running a TypeScript host with a persistent Python (ipykernel) evaluator and a user-configurable toolbox of functions.",
 	"keywords": [

package/src/engine/index.ts

@@ -26,6 +26,10 @@ function resolvePythonPath(cwd: string | undefined): string {
 }
 
 const DEFAULT_MAX_OUTPUT_CHARS = 65536;
+/** Per-line cap: one genuinely oversized line must not own the channel budget, while legitimately long
+ * REPL output (JSON, reprs, errors) still fits under the cap in one piece. Generous enough that only
+ * pathological giant lines are trimmed, unlike pi's grep where the line cap keeps matches terse. */
+export const MAX_OUTPUT_LINE_CHARS = 4096;
 const ABORT_GRACE_MS = 500;
 const DEFAULT_SNAPSHOT_DEBOUNCE_MS = 1500;
 
@@ -98,6 +102,18 @@ function truncateWithMarker(text: string, maxChars: number, wasTruncated: boolea
 	return `${text.slice(0, maxChars)}\n[... output truncated at ${maxChars} chars ...]`;
 }
 
+/** Cap each individual line, so one giant line cannot own the whole channel budget (like grep's line cap). */
+export function capLinesForContext(text: string): { text: string; trimmed: boolean } {
+	const lines = text.split("\n");
+	let trimmed = false;
+	const mapped = lines.map((line) => {
+		if (line.length <= MAX_OUTPUT_LINE_CHARS) return line;
+		trimmed = true;
+		return line.slice(0, MAX_OUTPUT_LINE_CHARS);
+	});
+	return { text: mapped.join("\n"), trimmed };
+}
+
 export class EngineManager {
 	private readonly options: EngineOptions;
 	private kernel?: KernelClient;
@@ -233,11 +249,18 @@ export class EngineManager {
 				});
 				if (r.status === "ok") this.scheduleSnapshot();
 				const status: ExecuteResult["status"] = opts.signal?.aborted ? "aborted" : r.status;
-				const truncate = (text: string, truncated: boolean) => truncateWithMarker(text, maxChars, truncated);
+				// Channel cap (truncateWithMarker), then per-line cap; both append a marker so truncation is explicit.
+				const finalize = (text: string, channelTruncated: boolean): string => {
+					let out = truncateWithMarker(text, maxChars, channelTruncated);
+					const line = capLinesForContext(out);
+					if (line.trimmed) out = `${line.text}\n[... some lines exceeded ${MAX_OUTPUT_LINE_CHARS} chars ...]`;
+					else out = line.text;
+					return out;
+				};
 				return {
-					stdout: truncate(r.stdout, r.truncated?.stdout ?? false),
-					stderr: truncate(r.stderr, r.truncated?.stderr ?? false),
-					result: r.result !== undefined ? truncate(String(r.result), String(r.result).length > maxChars) : undefined,
+					stdout: finalize(r.stdout, r.truncated?.stdout ?? false),
+					stderr: finalize(r.stderr, r.truncated?.stderr ?? false),
+					result: r.result !== undefined ? finalize(String(r.result), String(r.result).length > maxChars) : undefined,
 					error: r.error,
 					status,
 					durationMs: Date.now() - started,

package/src/extension/prompt.ts

@@ -9,8 +9,7 @@ export const executeToolDescription =
 	"You have one tool: a persistent Python workspace backed by a real `ipython` kernel. " +
 	"Variables, imports, and definitions survive across cells and turns — it is your working memory and action " +
 	"language. " +
-	"Helpers in `~/.pi/agent/pi-repl/helpers/` load at boot; list them with " +
-	"`[k for k in globals() if not k.startswith('_')]`. A cell returns its final expression; printed output is " +
+	"Helpers in `~/.pi/agent/pi-repl/helpers/` load at boot. A cell returns its final expression; printed output is " +
 	"captured separately.";
 
 export const executePromptSnippet =
@@ -40,7 +39,24 @@ export function buildPromptGuidelines(preloaded: string[]): string[] {
 		"Inspect what is present — count, print a few lines, list what is loaded — before committing. Build one " +
 			"step, run it, and use its output to choose the next.",
 		"",
+		"## Precise file and search work",
+		"Search narrowly and inspect only the lines you need. Do not dump whole files or repeat unchanged context. " +
+			"When walking directories, prune generated and hidden dirs — node_modules, .git, .venv, dist, __pycache__ — " +
+			"in the walk filter; never print a raw tree. " +
+			"For existing files, prefer a surgical old-text/new-text replacement over rewriting the file. Read the " +
+			"target region first, make the smallest unique replacement, then verify the changed region and file validity. " +
+			"Use complete writes only for new files or intentional full rewrites. Never leave a bare final expression: " +
+			"IPython displays it automatically; assign results and explicitly print only what you need.",
+		"",
+		"## Repository discipline",
+		"Inspect before changing. Preserve project conventions and unrelated content. Make the smallest valid change, " +
+			"verify it afterward, and never invent files, APIs, conventions, or test results.",
+		"",
 		"## Batch and print sparingly",
+		"Every printed value enters the conversation and consumes context. Treat output as expensive: do not print " +
+			"raw, recursive, or unbounded results. Explore and filter in variables first, then print only the small, " +
+			"bounded observation needed to make the next decision. Never dump an artifact and rely on truncation to " +
+			"control it. Quality of output is paramount.",
 		"Batch as much independent work as reasonably possible into one call. Keep large values in variables; " +
 			"print slices, counts, and summaries.",
 		"",
@@ -48,7 +64,7 @@ export function buildPromptGuidelines(preloaded: string[]): string[] {
 			? [
 					"## Helpers",
 					"User helpers load from `~/.pi/agent/pi-repl/helpers/` as workspace definitions. Their descriptions " +
-						"appear below. List what is loaded with `[k for k in globals() if not k.startswith('_')]`.",
+						"appear below.",
 					"",
 					...preloaded,
 					"",