pi-repl-py 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.2.2",
+	"version": "0.2.3",
 	"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/extension/prompt.ts

@@ -1,76 +1,70 @@
 // --- prompt: the execute tool's model-facing contract (pure, no pi/helper dep) ---
+//
+// Verbatim clauses from CodeAct (arXiv 2402.01030) and RLM (arXiv 2512.24601)
+// are trimmed to what pi-repl actually has — no sub-LLMs, no recursion, no
+// context variable — and the rest is stripped for lean context. Less prose,
+// more signal; the machine reads every line every turn.
 
 export const executeToolDescription =
 	"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.";
+	"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 " +
+	"captured separately.";
 
 export const executePromptSnippet =
-	"Use the Python workspace: keep state in variables, batch independent reads/searches in one cell, " +
-	"edit files safely, and iterate in small cells.";
+	"Work in the workspace: keep artifacts in variables, compose related actions in Python, print only what " +
+	"the next step needs, and revise from what you observe.";
 
 // --- the workspace doctrine riding the execute tool ---
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
-		"## 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.",
+		"## 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.",
 		"",
-		"## The loop is generate → execute → observe → iterate",
-		"Write a cell, run it, observe the result, then write the next cell. Build solutions incrementally.",
+		"## Work in the workspace, not the transcript",
+		"Load files, command results, search hits, 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 needed for the next decision; keep the full artifact in a variable.",
 		"",
-		"## State persists",
-		"Variables, imports, and functions survive across cells and turns. Assign read/search results to " +
-			"named variables and reuse them.",
+		"## A cell is a small program",
+		"Compose filesystem access, shell commands, searches, transforms, checks, and edits in ordinary Python " +
+			"when they belong to the same step.",
 		"",
-		"## Chain big tasks into verifiable steps",
-		"Break ambitious requests into independently checkable steps. Confirm assumptions before writing " +
-			"code that depends on them.",
+		"## Revise on observations",
+		"Revise prior actions or emit new actions upon new observations.", // CodeAct core
 		"",
-		"## 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.",
+		"## 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.",
 		"",
-		"## 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.",
+		"## Batch and print sparingly",
+		"Batch as much independent work as reasonably possible into one call. Keep large values in variables; " +
+			"print slices, counts, and summaries.",
 		"",
 		...(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('_')]`.",
+					"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('_')]`.",
 					"",
 					...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.",
+		"## Shell and search",
+		"`subprocess.run(..., timeout=...)` when you need a result — always set a `timeout`, the evaluator does not " +
+			"kill a silent cell. Use `rg`/`grep`/`find` via `subprocess.run` for deep searches, not Python loops.",
 		"",
 		"## 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.",
+			"dependencies into the evaluator. 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.",
+		"If output begins with `<repl_engine_reset>`, the kernel was rebuilt from the last snapshot. Re-verify a " +
+			"revived variable before reusing it — especially in a shell command. Functions, classes, and live handles " +
+			"are not snapshotted and must be redefined.",
 	];
 }