pi-repl-py 0.3.0 → 0.5.0

package/index.ts

@@ -4,6 +4,7 @@ import { basename, join } from "node:path";
 import { homedir } from "node:os";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
+import { withSkillsBlock } from "./src/extension/skill-hook.js";
 import { EngineManager } from "./src/engine/index.js";
 import { ExecuteCellComponent, type ExecuteDetails, type ExecuteRenderState } from "./src/extension/render.js";
 import { EngineLifecycle } from "./src/extension/session-engine.js";
@@ -109,6 +110,16 @@ export default function (pi: ExtensionAPI) {
 		return { content: event.content, details: stashed.details, isError: true };
 	});
 
+	// --- pi gates skills on the read tool (absent in repl); re-emit them via withSkillsBlock. ---
+	pi.on("before_agent_start", (event) => {
+		if (!active()) return;
+		const systemPrompt = withSkillsBlock(
+			event.systemPrompt,
+			event.systemPromptOptions?.skills ?? [],
+		);
+		return systemPrompt === undefined ? undefined : { systemPrompt };
+	});
+
 	pi.registerTool<typeof executeSchema, ExecuteDetails, Partial<ExecuteRenderState>>({
 		name: "execute",
 		label: "execute",
@@ -140,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.3.0",
+	"version": "0.5.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/extension/prompt.ts

@@ -6,58 +6,71 @@
 // more signal; the machine reads every line every turn.
 
 export const executeToolDescription =
-	"You have one tool: a real `ipython` kernel that stays alive across cells and turns. " +
-	"This persistent Python workspace is your only surface — it does the work of bash, read, write, edit, " +
-	"search, and file handling, and everything you define (variables, imports, helpers loaded from " +
-	"`~/.pi/agent/pi-repl/helpers/`) survives for reuse in later cells. A cell returns its final expression; " +
-	"printed output is captured separately.";
+	"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.";
 
 export const executePromptSnippet =
-	"The persistent Python workspace is your only tool: keep artifacts in variables across cells for reuse, use the loaded helpers, prefer surgical reads/edits over full-file dumps and rewrites, and parse before you print so context stays lean.";
+	"Execute Python cells in a persistent ipython kernel (replaces read, bash, edit, write, and search; state survives across cells and turns)";
 
 // --- the workspace doctrine riding the execute tool ---
 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.",
+		"`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.",
 		"",
-		"## 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.",
+		"## 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.",
+		"",
+		"## 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.",
+		"",
+		"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.",
+		"",
+		"Each printed value is the one that changes the next cell; the transcript stays thin, the work dense in variables.",
+		"",
+		"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.",
 		"",
 		"## A cell is a small program",
-		"Compose filesystem access, shell commands, searches, transforms, checks, and edits in ordinary Python in the same step.",
+		"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.",
+		"",
+		"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.",
 		"",
 		"## Revise on observations",
 		"Revise prior actions or emit new actions upon new observations.", // CodeAct core
 		"",
 		"## 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.",
+		"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.",
 		"",
 		"## 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.",
+		"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.",
 		"",
-		"## 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.",
-		"",
 		...(preloaded.length
 			? [
 					"## Helpers",
-					"These helpers are given to you by the user to use directly (loaded from `~/.pi/agent/pi-repl/helpers/`). Descriptions appear below.",
+					"These helpers are already defined in the workspace namespace. Use them by name as you would any other loaded function, class, or variable. Their code already executed at kernel boot. Descriptions appear below.",
 					"",
 					...preloaded,
 					"",
 				]
 			: []),
 		"## 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.",
+		"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.",
 		"",
-		"## 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.",
+		"## 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.",
 	];
 }

package/src/extension/skill-hook.ts

@@ -0,0 +1,22 @@
+// --- skills cannot reach the prompt in --repl: pi gates <available_skills> on the read tool
+// (hasRead), which repl doesn't have. Re-emit them with pi's own formatter in pi's slot. ---
+import { formatSkillsForPrompt, type Skill } from "@mariozechner/pi-coding-agent";
+
+const CWD_MARKER = "\nCurrent working directory:"; // skills sit just before this, pi's last line
+const READ_LINE = "Use the read tool to load a skill's file when the task matches its description."; // canon line
+const EXECUTE_LINE = "Load a skill's SKILL.md file contents via execute (read the file with Python)."; // repl has no read
+
+/** The prompt with the skills block in pi's slot; undefined if nothing should change. */
+export function withSkillsBlock(
+	prompt: string,
+	skills: Skill[],
+	alreadyPresent = prompt.includes("<available_skills>"),
+): string | undefined {
+	if (skills.length === 0) return undefined;
+	let extra = formatSkillsForPrompt(skills);
+	if (!extra) return undefined;
+	if (alreadyPresent) return undefined;
+	extra = extra.replace(READ_LINE, EXECUTE_LINE);
+	const idx = prompt.indexOf(CWD_MARKER);
+	return idx === -1 ? prompt + extra : prompt.slice(0, idx) + extra + prompt.slice(idx);
+}