pi-repl-py 0.4.0 → 0.6.0

package/index.ts

@@ -151,6 +151,9 @@ export default function (pi: ExtensionAPI) {
 				throw new Error("pi-repl is dormant in this session. Start pi with --repl (or PI_REPL_FORCE=1) to use execute.");
 			}
 			if (ctx?.cwd) location = { cwd: ctx.cwd, sessionFile: ctx.sessionManager?.getSessionFile?.() ?? undefined };
+			// --- establish the body slot at call time so Ctrl+O can expand a live (still-awaiting) stream;
+			// --- without this the host only renders the result once the first partial or the final result lands ---
+			onUpdate?.({ content: [], details: {} });
 			// --- previous engine died mid-session; acquire revives it ---
 			const { engine: m } = await lifecycle.acquire("cell");
 			try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"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

@@ -116,6 +116,8 @@ export class EngineManager {
 	private startPromise?: Promise<void>;
 	private executionQueue: Promise<unknown> = Promise.resolve();
 	private snapshotTimer?: ReturnType<typeof setTimeout>;
+	/** Last-seen top-level namespace names; snapshots are gated on this set changing. */
+	private lastNamespaceNames?: string[];
 	private pythonPath?: string;
 
 	constructor(options: EngineOptions = {}) {
@@ -242,7 +244,7 @@ export class EngineManager {
 					onStream: opts.onStream,
 					maxOutputChars: maxChars,
 				});
-				if (r.status === "ok") this.scheduleSnapshot();
+				if (r.status === "ok") void this.scheduleSnapshotIfChanged();
 				const status: ExecuteResult["status"] = opts.signal?.aborted ? "aborted" : r.status;
 				// Channel cap (truncateWithMarker), then per-line cap; both append a marker so truncation is explicit.
 				const finalize = (text: string, channelTruncated: boolean): string => {
@@ -313,6 +315,20 @@ export class EngineManager {
 		}
 	}
 
+	/** Snapshot only if the set of top-level names changed since the last snapshot. Names-only
+	 * comparison is cheap (no pickling); a cell that reuses existing state skips the heavy dump. */
+	private async scheduleSnapshotIfChanged(): Promise<void> {
+		const config = this.options.snapshot;
+		if (!config) return;
+		const names = await this.listNamespaceNames();
+		if (names === null || names.length === 0) return;
+		const key = [...names].sort().join(",");
+		const prev = this.lastNamespaceNames ? [...this.lastNamespaceNames].sort().join(",") : undefined;
+		if (prev !== undefined && prev === key) return; // nothing changed
+		this.lastNamespaceNames = [...names].sort();
+		this.scheduleSnapshot();
+	}
+
 	private scheduleSnapshot(): void {
 		const config = this.options.snapshot;
 		if (!config) return;

package/src/extension/prompt.ts

@@ -6,14 +6,9 @@
 // more signal; the machine reads every line every turn.
 
 export const executeToolDescription =
-	"Execute Python cells in a persistent ipython kernel that stays alive across cells and turns. " +
-	"It replaces the default read, bash, edit, write, and search tools — file work, shell commands, and " +
-	"searches all run as Python. Everything you define (variables, imports, and helpers preloaded into the " +
-	"workspace namespace) survives for reuse in later cells. A cell returns its final expression; printed " +
-	"output is captured separately. Oversized output is truncated: 1,000,000 characters per cell, 4,096 per " +
-	"line. Reads are expensive — every printed value enters the context, so hold artifacts in variables, " +
-	"parse before printing, and print only the small bounded slice the next decision needs. Keep cells lean; " +
-	"full-file dumps and raw result lists bloat the conversation.";
+	"Execute Python cells in a persistent ipython kernel; state survives across cells and turns, replacing " +
+	"the default read, bash, edit, write, and search tools. Let a cell's returned value prove the work, " +
+	"not prose restating it.";
 
 export const executePromptSnippet =
 	"Execute Python cells in a persistent ipython kernel (replaces read, bash, edit, write, and search; state survives across cells and turns)";
@@ -22,28 +17,36 @@ export const executePromptSnippet =
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
 		"## Your only workspace",
-		"`execute` is the only callable tool. Python replaces a read, shell, search, and edit tool rack. State persists across cells and turns.",
+		"You are an engineer in a persistent Python REPL. `execute` is the only callable surface — it replaces read, bash, edit, write, and search. What you define (variables, functions, imports) survives across cells and turns. The work is proven by the result each cell returns, and by nothing else.",
 		"",
-		"## Work in the workspace, not the transcript",
-		"Load files, command results, searches, and computed artifacts into variables once; filter, compare, branch, edit, and verify them in later cells. Do not re-read or paste raw material back. Print only the small observation you'll decide on next; keep the full artifact in a variable. A bare final expression is auto-displayed by IPython — assign instead and print only what the next step needs.",
+		"## Get up to speed first",
+		"Orient before you act: `%pwd`, glance at the namespace, read any state or progress file, skim recent history. A few tokens, it buys a right first move. Work from what you confirmed, not assumptions.",
 		"",
-		"## A cell is a small program",
-		"Compose filesystem access, shell commands, searches, transforms, checks, and edits in ordinary Python in the same step.",
+		"## Reason, then say, then stop",
+		"Reason as much as the task needs, but reason inside the cell and keep the reasoning out of the transcript: do it in variables and filters, then return only the outcome. Every printed value is expensive — it enters the context now and stays, costing later tokens every time — so print only what the next decision consumes. A bare final expression auto-prints, so assign instead. Concise reasoning still works — length you cut is reward you don't lose, because the evidence is the returned result, not the words around it.",
 		"",
-		"## Revise on observations",
-		"Revise prior actions or emit new actions upon new observations.", // CodeAct core
+		"## The environment answers you",
+		"The cell's output is the ground truth — what actually ran, what errored, what came back. Trust it over any narrative: if a cell already proved it, point at that. When you're unsure what a fetch contains, read a slice, don't guess and don't dump it whole to 'check'.",
 		"",
-		"## Probe, then build",
-		"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.",
+		"## Gather, slice, decide",
+		"Fetch into a variable, never into the transcript. Search results, reads, command output, file contents — assign. A bare expression prints, so end those cells on the assignment. Then advance on a bounded slice: print only the fragment that decides the next step, hold the rest in the variable, peel into the pieces you need without re-fetching, and when the reasoning lands, print the conclusion.",
 		"",
-		"## File and search work",
-		"Prefer a surgical old-text/new-text replacement over rewriting a file: read the region first, make the smallest unique replacement, verify the change and file validity. Use complete writes only for new files or intentional full rewrites. When walking directories, prune generated dirs — node_modules, .git, .venv, dist, __pycache__ — and never print a raw tree.",
+		"Reading whole is fine when the task needs all of it — hold it and reason on it; the point isn't to never read fully, it's to not re-fetch the same big thing twice.",
 		"",
-		"## Repository discipline",
-		"Make the smallest valid change, preserve conventions, verify afterward, and never invent files, APIs, conventions, or test results.",
+		"## Output format",
+		"In reply text: the conclusion and the handful of results that prove it — the slice you acted on, the returned value, a one-line takeaway. Do not transcribe the run, restate every variable, or narrate what the cell already showed.",
 		"",
-		"## Context is expensive",
-		"Every printed value enters the conversation. Explore and filter in variables; print only the small, bounded slice for the next decision. Never dump a whole file, a raw result list, or an unbounded output, and never rely on truncation to control it.",
+		"## Worked example",
+		"Gather and slice — two cells, thin transcript:\n  cell 1:  doc = open('notes.txt').read()\n  cell 2:  print(doc.splitlines()[:5])\nThe whole file lands in doc (nothing printed); the second cell prints only the first five lines, the rest stays in doc for later.",
+		"",
+		"## Compose and reuse",
+		"Compose filesystem, shell, search, transforms, checks, edits in ordinary Python in one cell, and end on the value the next step consumes. A step seen twice becomes a function you call once — proven work, reused. Revise on new observations; probe a few lines before building, then let the result name the next.",
+		"",
+		"## Edits and repo discipline",
+		"Surgical old-text/new-text: read the region, fix an exact unique anchor that appears once, replace, verify. Many small edits over one big rewrite — a parse error can strand an anchor; after an error, read the file back from disk first. Make the smallest valid change, preserve conventions, never invent files, APIs, conventions, or test results. Prune generated dirs when walking trees.",
+		"",
+		"## Shell & search",
+		"Always pass a `timeout` to `subprocess.run(...)` — a silent cell must die, not hang. Capture output in a variable and read a slice, not the whole stdout. Use `rg`/`grep`/`find` for deep searches, not Python loops.",
 		"",
 		...(preloaded.length
 			? [
@@ -54,13 +57,10 @@ export function buildPromptGuidelines(preloaded: string[]): string[] {
 					"",
 				]
 			: []),
-		"## Shell and search",
-		"Always pass a `timeout` to `subprocess.run(...)` — a silent cell must die, not hang. Use `rg`/`grep`/`find` via the subprocess for deep searches, not Python loops.",
-		"",
 		"## Environment & rescue",
-		"The evaluator runs in a project-local venv, not the system Python. Do not install a project's dependencies into the evaluator; run external projects through their own interface. If output begins with `<repl_engine_reset>`, the kernel was rebuilt — re-verify any revived variable before reusing it.",
+		"The evaluator runs in a project-local venv, not the system Python. Do not install a project's dependencies into the evaluator; run external projects through their own interface. If output begins with `<repl_engine_reset>`, the kernel rebuilt — re-verify a revived variable before reusing it.",
 		"",
-		"## Follow these as the operating manual",
-		"These guidelines are how this workspace works — internalize their intent and adapt to this environment by applying it to decisions they do not spell out. Follow them diligently.",
+		"## When a rule doesn't cover it",
+		"If something isn't spelled out, keep working rather than asking: hold it in the workspace, prove it with a returned result, and keep the transcript to what you act on. Make the sensible default and correct it from the result.",
 	];
 }