pi-repl-py 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.5.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,13 +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, replacing " +
-	"the default read, bash, edit, write, and search tools. Everything you define (variables, imports, and " +
-	"helpers preloaded into the workspace namespace) survives for reuse in later cells. A cell returns its " +
-	"final expression — bare final expressions are auto-printed, and output is trimmed at 1,000,000 " +
-	"characters per cell / 4,096 per line. Treat these as facts about how the workspace reports, not as " +
-	"limits to test: assign the values you want to keep so they stay in scope for later cells, and let a " +
-	"cell's return value be the proof of its work rather than re-stating that work in prose.";
+	"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)";
@@ -21,39 +17,36 @@ export const executePromptSnippet =
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
 		"## Your only workspace",
-		"`execute` is your workspace: a persistent Python session that is the only callable surface. What you define — variables, functions, data — survives across cells and turns, and the work is proven by the results each cell returns.",
+		"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.",
 		"",
-		"## Go deep in the cell; prove it by the result",
-		"Depth, the cell, not the transcript. Do the heavy reasoning in variables and filters; a cell's worth is shown by what it returns as a result, not by restating that result in prose. Every printed value enters the context — and equating length with value is the trap — so let the code's result, not a recap paragraph, be the evidence.",
+		"## 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.",
 		"",
-		"## The gather-filter-advance shape",
-		"Leave raw data in the workspace. Search results, reads, command output, file contents — whatever you fetch — land in variables, never in the transcript.",
+		"## 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.",
 		"",
-		"1. **Gather.** One cell assigns the whole: result = search(q), doc = load(path), out = run(...) — nothing printed, ends on the assignment.",
-		"2. **Advance.** The next cell prints only the fragment that decides the next step — titles only, a slice of content — and you pick from that sliver.",
-		"3. **Peel, don't re-fetch.** You already hold the whole; walk into the pieces you need without re-running it.",
-		"4. **Emit, then drop.** When the reasoning lands, print the conclusion; the rest stays in the variable, or is overwritten when done.",
+		"## 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'.",
 		"",
-		"Each printed value is the one that changes the next cell; the transcript stays thin, the work dense in variables.",
+		"## 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.",
 		"",
-		"Windows, not bans: reading something whole is fine when the task genuinely needs all of it — do that, then keep reasoning on it. The point is not to never read fully; it is to read by window by default and hold the whole, so you never re-fetch the same big thing twice.",
+		"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.",
 		"",
-		"## A cell is a small program",
-		"Compose whatever the step needs — filesystem, shell, search, transforms — in one cell, and end it on the return value the next step consumes. The cell itself (what ran) carries the meaning; the transcript carries only that returned value.",
+		"## 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.",
 		"",
-		"Name what recurs: when the same operation shows up twice, give it a name once — a function in the namespace — and call it. A defined function is work already proven; every call is a new return-value result, and you never re-print the steps that made 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.",
 		"",
-		"## Revise on observations",
-		"Revise prior actions or emit new actions upon new observations.", // CodeAct core
+		"## 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.",
 		"",
-		"## Probe, then build",
-		"Inspect where you are — a small slice — before committing; then build one step and let its returned result name the next. The proof of each step is the cell's result, not a summary of it.",
+		"## 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.",
 		"",
-		"## File and search work",
-		"Prefer a surgical old-text/new-text replacement over rewriting a file: read the region first, fix an exact unique anchor that appears once, replace exactly, then verify. Prefer many small verified edits over one big blind rewrite — a parse error mid-way can strand an anchor. Use complete writes only for new files or intentional full rewrites. After an edit errors or writes a partial result, read the file back from disk before reasoning about it. When walking directories, prune generated dirs and never print a raw tree.",
-		"",
-		"## Repository discipline",
-		"Make the smallest valid change, preserve conventions, verify afterward, and never invent files, APIs, conventions, or test results.",
+		"## 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
 			? [
@@ -64,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. Capture the result in a variable and read a slice, not dump the whole stdout into the transcript: use `rg`/`grep`/`find` 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.",
 		"",
-		"## The operating principle above the manual",
-		"The rules above are working forms of one principle: the work happens in the workspace — in cells and their results — and the transcript carries only what decides or concludes. When a case isn't spelled out, apply the principle over the example: wherever the work can live in the workspace instead of the transcript, keep it there, and let the returned result be the proof. The result is the certificate; the rest of the work stays out of the reply.",
+		"## 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.",
 	];
 }