pi-repl-py 0.1.0 → 0.1.1

package/src/extension/tool-meta.ts

@@ -1,58 +1,15 @@
-/**
- * The `execute` tool's prompt surface.
- *
- * pi's default system prompt is used as-is; all REPL knowledge rides on the
- * tool via these fields, so index.ts stays thin.
- *
- *  - description   — working summary (schema card).
- *  - promptSnippet — one line in the default `Available tools`.
- *  - promptGuidelines — the function doctrine + tokens + safety.
- *
- * The function map is derived from the toolbox source via buildToolboxMap()
- * (function_description docstring + def-signature regex), so it always matches
- * what the kernel loads.
- */
+// --- tool-meta: thin surface assembling the execute tool's prompt from pure modules ---
+// --- the model contract lives in prompt.ts; only the toolbox wiring stays here ---
 
+import { buildPromptGuidelines, executePromptSnippet, executeToolDescription } from "./prompt.js";
 import { buildToolboxMap } from "./toolbox.js";
 
-export const EXECUTE_DESCRIPTION =
-	"Execute Python to a persistent evaluator: the session's working memory. " +
-	"Variables, imports, functions, and data survive across calls. There are no " +
-	"separate file or shell tools; read, write, edit, bash, and anything you build " +
-	"are Python functions you call inside a cell. A cell returns its final " +
-	"expression; anything else is printed. Build one reusable function per routine " +
-	"and call it by arguments, since a new def overwrites the previous one; don't " +
-	"narrate that machinery to the user. Runs in a project-local venv, so a command " +
-	"that starts python or pip must target that venv.";
+export const EXECUTE_DESCRIPTION = executeToolDescription;
+export const EXECUTE_PROMPT_SNIPPET = executePromptSnippet;
 
-export const EXECUTE_PROMPT_SNIPPET =
-	"Execute Python in a persistent evaluator whose variables, imports, and functions " +
-	"survive across calls; preloaded functions plus any you define and reuse as " +
-	"callable tools; ls() lists them, help(name) shows usage";
-
-/**
- * promptGuidelines for the execute tool. `toolboxDir` is optional; it defaults to
- * the shipped toolbox.
- */
+// --- build the guidelines from the toolbox, falling back when nothing is preloaded ---
 export function buildExecutePromptGuidelines(toolboxDir?: string): string[] {
 	const map = buildToolboxMap(toolboxDir);
 	const preloaded = map.length > 0 ? map : ["(none preloaded: define your own)"];
-	return [
-		"Preloaded functions available in every kernel:",
-		...preloaded,
-		"ls() prints what is loaded; help(name) shows a function's signature and notes. Use them instead of guessing.",
-		"Functions you define are reusable tools: one parameterized helper per task, call it by arguments. Never write a routine twice and never fork a duplicate; extend the existing `def` (a new `def` of the same name overwrites).",
-		"Before a multi-line cell, ask whether you will run that shape again with different inputs. If yes, define the function now so each later request is one call.",
-		"Good, defined once then called by arguments only:",
-		"def fetch_news(query, hl='en', gl='US', ceid='US:en', limit=15):\n    <fetch + parse to a list>\nfetch_news('Turkey')\nfetch_news('Nigeria', hl='en-NG')",
-		"Don't build a near-copy (avoid fetch_news and fetch_news_region); add the varying bits to the original `def` and let it supersede the old.",
-		"Other reusable shapes build the same way:",
-		"def find_files(pred, root='.'):\n    <walk root, filter by pred>\nfind_files('*.csv')\nfind_files('*.py', root='src')\ndef count_lines(paths): ... # compose: count_lines(find_files('*.csv'))",
-		"Use functions proportionally: build one when it will be reused, otherwise run it in a plain cell. Don't wrap a one-off and don't over-engineer.",
-		"Never narrate your mechanism to the user (don't say 'I defined a function' or 'I built a tool'). Do the job, then answer with the result.",
-		"Be token efficient: everything a cell prints is context for the rest of the turn. When reading or searching, print slices, matches, or counts rather than whole files, and keep large values in variables.",
-		"For whole-filesystem or large-dir scans, use the kernel's tools via bash, not a Python walk: find, du, fd, grep. Chain them (find -xdev -type f -size +100M | sort -rn | head; du -x | sort -h | tail) and prune descent by skipping node_modules, .git, caches, venvs. A Python os.walk + lstat loop pays a slow syscall per file and runs minutes to 10+ min on a big tree; reserve Python for analysing the results, not for enumerating the disk.",
-		"If the output starts with <rlm_engine_reset>, the kernel was rebuilt: only data is restored, your functions are gone. Recreate any helper you need and re-verify a variable before trusting it.",
-		"Don't install packages into the evaluator; the standard library is available. Run out-of-tree projects through their own environment.",
-	];
+	return buildPromptGuidelines(preloaded);
 }

package/src/extension/toolbox.ts

@@ -9,6 +9,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 
 interface ToolEntry {
@@ -41,34 +42,57 @@ function defaultToolboxDir(): string {
 	return join(import.meta.dirname, "..", "..", "src", "engine", "toolbox");
 }
 
-/** Load {function_name → source} for each non-underscore *.py in `dir`. */
+/** Expand a leading `~` to the user's home, matching the guest's expanduser. */
+function expandTilde(p: string): string {
+	const home = homedir();
+	if (p === "~" || p === "~/") return home;
+	if (p.startsWith("~/") || p.startsWith("~\\")) return join(home, p.slice(2));
+	return p;
+}
+
+/** Resolve a toolbox dir the way the config intends (expand ~, missing → shipped default). */
+function toolboxDir(dir: string | undefined): string {
+	return dir && dir.trim().length > 0 ? expandTilde(dir.trim()) : defaultToolboxDir();
+}
+
+/** Load {function_name → entry} for each non-underscore *.py in `dir`. */
 function loadToolboxEntries(dir: string | undefined): ToolEntry[] {
-	const d = dir && dir.length > 0 ? dir : defaultToolboxDir();
+	const d = toolboxDir(dir);
 	if (!existsSync(d)) return [];
 	const entries: ToolEntry[] = [];
 	for (const file of readdirSync(d).sort()) {
 		if (!file.endsWith(".py")) continue;
 		const name = file.slice(0, -3);
 		if (!/^[A-Za-z_]\w*$/.test(name)) continue;
-		// An underscore-prefixed file is not loaded into the kernel (see guest.py),
-		// so it must never be advertised either.
+		// --- underscore-prefixed files are neither loaded nor advertised ---
 		if (name.startsWith("_")) continue;
 		try {
 			const source = readFileSync(join(d, file), "utf8");
 			const call = parseDefCall(source);
 			if (!call) continue;
 			entries.push({ name, call, description: parseDescription(source) });
-		} catch {
-			continue;
-		}
+		} catch {}
 	}
 	return entries;
 }
 
 /**
- * The markdown-style function map: one `- call: description` line per function,
- * ready to drop into the prompt guidelines.
+ * The shipped built-in function set, always present (the canonical toolbox).
+ */
+function builtInEntries(): ToolEntry[] {
+	return loadToolboxEntries(undefined);
+}
+
+/**
+ * The effective function map: the shipped built-ins are supreme (always
+ * present); the config `toolboxDir`, if set, adds any extra function and, when
+ * a name collides, overrides the built-in one. `~` is resolved like the guest.
  */
 export function buildToolboxMap(dir: string | undefined): string[] {
-	return loadToolboxEntries(dir).map((t) => (t.description ? `- ${t.call}: ${t.description}` : `- ${t.call}`));
+	const byName = new Map<string, ToolEntry>();
+	for (const e of builtInEntries()) byName.set(e.name, e);
+	if (dir && dir.trim().length > 0 && toolboxDir(dir) !== defaultToolboxDir()) {
+		for (const e of loadToolboxEntries(dir)) byName.set(e.name, e);
+	}
+	return [...byName.values()].map((t) => (t.description ? `- ${t.call}: ${t.description}` : `- ${t.call}`));
 }