pi-tool-discipline 0.1.6 → 0.1.7

package/README.md

@@ -21,20 +21,22 @@ tool, not bash").
 
 Two mechanisms, applied automatically in every session:
 
-1. **Search-tool registration (root fix).** Registers tools named `grep`,
-   `find`, and `ls` (skipped if already registered). Their presence flips pi's
-   `hasGrep`/`hasFind`/`hasLs` check, so the conflicting bash guideline is
-   **never generated**. Each tool always has a working fs-based implementation
-   (`extensions/search.ts`); visibility is toggled per capability — hidden
-   while its FFF counterpart (`ffgrep`/`fffind`) is active, visible as a
-   fallback when pi-fff is not installed.
-2. **System-prompt injection (fallback + rules).** On every agent start,
-   appends an idempotent "Tool Discipline" section to the system prompt:
-   content search with `ffgrep`, path search with `fffind`, file reads with
-   `read` (offset/limit), no bash `grep`/`rg`/`find`/`ls`/`cat`/`sed`/`head`/
-   `tail`/`which` for searching, bash reserved for pipelines/git/npm/network,
-   `rg` (never `grep`) as the last resort. Also strips the default bash
-   guideline text in environments where the registration is disabled.
+1. **Activate search tools (root fix).** pi 0.84+ ships real `grep` / `find` /
+   `ls` built-in tool definitions but only activates `read`/`bash`/`edit`/
+   `write` by default. This extension activates the built-ins, so pi's
+   `hasGrep`/`hasFind`/`hasLs` check passes and the conflicting
+   `Use bash for file operations like ls, rg, find` guideline is **never
+   generated** — the model is never told to use bash for searching. On older
+   pi versions without these built-ins, fs-based fallbacks
+   (`extensions/search.ts`) are registered instead (visible only when
+   `ffgrep`/`fffind` from pi-fff are absent).
+2. **System-prompt injection (rules).** On every agent start, appends an
+   idempotent "Tool Discipline" section to the system prompt: content search
+   with `ffgrep`, path search with `fffind`, file reads with `read`
+   (offset/limit), no bash `grep`/`rg`/`find`/`ls`/`cat`/`sed`/`head`/`tail`/
+   `which` for searching, bash reserved for pipelines/git/npm/network, `rg`
+   (never `grep`) as the last resort. Also strips the bash guideline text as
+   a belt-and-suspenders fallback.
 
 ## Install
 
@@ -58,10 +60,16 @@ You can also inspect the system prompt: the string
 
 ## Security
 
-This extension runs with full system access like any pi extension. It only
-registers inert placeholder tools and appends text to the system prompt; it
-does not execute commands, read files, or touch network. Review the source in
-`extensions/index.ts` before installing.
+This extension runs with full system access like any pi extension. What it does:
+- Activates pi's built-in `grep`/`find`/`ls` tools (read-only file search).
+- Injects text into the system prompt (discipline rules).
+- On pi versions without built-in search tools, registers read-only fs-based
+  fallback implementations that read file contents under the searched path.
+
+It never writes files, executes commands, or touches the network. Note that
+any installed tool, including this one, can be invoked by the model; the
+fallback search tools only read. Review the source in `extensions/` before
+installing.
 
 ## License
 

package/extensions/index.ts

@@ -13,12 +13,14 @@
  *   rules that say to use the grep tool instead.
  *
  * How it works:
- *   A. Registers working search tools named `grep` / `find` / `ls` (skipped
- *      when already registered). Their presence flips pi's hasGrep/hasFind/
- *      hasLs check, so the conflicting bash guideline is never generated.
- *      Each tool is always functional (fs-based, see search.ts); visibility
- *      is toggled via promptSnippet — hidden while its FFF counterpart
- *      (ffgrep / fffind) is active, visible as a fallback when it is not.
+ *   A. Ensures `grep` / `find` / `ls` tools are ACTIVE in the session. pi 0.84+
+ *      ships real built-in definitions (createAllToolDefinitions) but only
+ *      activates read/bash/edit/write by default — this extension activates
+ *      the built-ins, so pi's hasGrep/hasFind/hasLs check passes and the
+ *      conflicting bash guideline is never generated, and the model always has
+ *      search tools. On older pi versions without the built-ins, fs-based
+ *      fallbacks (search.ts) are registered instead (visible only when the
+ *      FFF counterpart ffgrep/fffind is absent).
  *   B. On before_agent_start, appends the tool-discipline rules to the system
  *      prompt (idempotent) and strips the bash guideline text as a fallback.
  */
@@ -105,23 +107,29 @@ export default function toolDiscipline(pi: ExtensionAPI) {
 	// Done in session_start: action methods (getAllTools/registerTool) are not
 	// available during extension loading, and tools registered here are
 	// refreshed into the session (and system prompt) immediately.
-	pi.on("session_start", (event, ctx) => {
+	pi.on("session_start", () => {
 		const all = new Set(pi.getAllTools().map((t) => t.name));
-		// Use ACTIVE tools (respects --exclude-tools / allowed lists), not the
-		// full registry: getAllTools() still reports excluded tools.
 		const active = new Set(pi.getActiveTools());
-		// Decide per capability so partial FFF availability (e.g. only ffgrep
-		// active) still leaves a real fallback for the missing side.
 		const hasFfgrep = active.has("ffgrep");
 		const hasFffind = active.has("fffind");
+
+		// 1) Activate built-in grep/find/ls when they exist (pi 0.84+ ships real
+		//    definitions via createAllToolDefinitions but only activates
+		//    read/bash/edit/write by default). Activating them flips
+		//    hasGrep/hasFind/hasLs so the bash guideline is never generated, and
+		//    gives the model real built-in search tools.
+		const toActivate = PLACEHOLDER_NAMES.filter((name) => all.has(name) && !active.has(name));
+		if (toActivate.length > 0) {
+			// setActiveTools rebuilds the system prompt immediately.
+			pi.setActiveTools([...active, ...toActivate]);
+		}
+
+		// 2) Older pi without built-in grep/find/ls: register working fs-based
+		//    fallbacks (search.ts). Visibility is per-capability: hidden while
+		//    the FFF counterpart is active, visible when it is not.
 		let registeredAny = false;
-		// All three names always get a WORKING implementation (no inert
-		// placeholders — a refreshed tool can be called by the model, so an
-		// empty implementation would be a trap). Visibility toggles via
-		// promptSnippet: hidden when the FFF counterpart is active, visible
-		// (with a fallback hint) when it is not.
 		const registerSearchTool = (name: string, fffActive: boolean) => {
-			if (all.has(name)) return; // already registered by another extension
+			if (all.has(name)) return; // built-in exists — handled above
 			const fallback = FALLBACK_TOOLS[name];
 			pi.registerTool({
 				name,
@@ -146,10 +154,9 @@ export default function toolDiscipline(pi: ExtensionAPI) {
 		registerSearchTool("find", hasFffind);
 		registerSearchTool("ls", hasFffind);
 		// Tools registered in session_start do not enter selectedTools until the
-		// registry is refreshed. Without this, pi keeps injecting the bash
-		// guideline (verified empirically on pi 0.84.4). refreshTools exists at
-		// runtime (ExtensionActions) but is not declared on ExtensionAPI's type.
-		// Known limitation: with peer version "*", other pi versions may differ.
+		// registry is refreshed. refreshTools exists at runtime (ExtensionActions)
+		// but is not declared on ExtensionAPI's type. Known limitation: with peer
+		// version "*", other pi versions may differ.
 		if (registeredAny) (pi as unknown as { refreshTools: () => void }).refreshTools();
 	});
 
@@ -161,7 +168,7 @@ export default function toolDiscipline(pi: ExtensionAPI) {
 		return { systemPrompt: `${prompt}\n${MARK}\n${DISCIPLINE}` };
 	});
 
-	// Status command: /tool-discipline — verify tool registration and injection.
+	// Status command: /tool-discipline — verify tool activation and injection.
 	pi.registerCommand("tool-discipline", {
 		description: "Show pi-tool-discipline status (tools + injected guideline)",
 		handler: async (_args, ctx) => {
@@ -169,13 +176,13 @@ export default function toolDiscipline(pi: ExtensionAPI) {
 			const active = new Set(pi.getActiveTools());
 			const fff = FFF_TOOLS.filter((name) => active.has(name));
 			const registered = PLACEHOLDER_NAMES.filter((n) => all.has(n));
-			const visible = PLACEHOLDER_NAMES.filter((n) => active.has(n));
+			const activeTools = PLACEHOLDER_NAMES.filter((n) => active.has(n));
 			const injected = ctx.getSystemPrompt().includes(MARK);
 			ctx.ui.notify(
 				`pi-tool-discipline\n` +
 					`fff active: ${fff.length > 0 ? fff.join(", ") : "(none)"}\n` +
-					`grep/find/ls registered: ${registered.length > 0 ? registered.join(", ") : "(none)"}\n` +
-					`visible to model: ${visible.length > 0 ? visible.join(", ") : "(none)"}\n` +
+					`grep/find/ls defined: ${registered.length > 0 ? registered.join(", ") : "(none)"}\n` +
+					`grep/find/ls active: ${activeTools.length > 0 ? activeTools.join(", ") : "(none)"}\n` +
 					`discipline injected: ${injected ? "yes" : "no"}`,
 				"info",
 			);

package/extensions/search.ts

@@ -8,8 +8,10 @@ import { Type } from "typebox";
 
 const SKIP_DIRS = new Set(["node_modules", ".git", ".hg", ".svn"]);
 const MAX_FILES = 2000;
+const MAX_VISITED = 5000; // total entries touched, bounds slow/odd trees
 const MAX_FILE_BYTES = 1024 * 1024; // content search skips files larger than 1 MiB
 const MAX_OUTPUT_BYTES = 50 * 1024;
+const TRUNCATE_MARKER = "\n[output truncated]";
 
 interface FileMatch {
 	file: string;
@@ -18,11 +20,14 @@ interface FileMatch {
 }
 
 /**
- * Collect files under dir (depth-limited, symlink-safe, bounded).
+ * Collect regular files under dir (depth-limited, symlink-safe, bounded).
+ * Only isFile() entries are collected — FIFOs, devices, sockets can block a
+ * synchronous read. Synchronous by design (fallback tools, low frequency);
+ * the walk is bounded by MAX_FILES/MAX_VISITED so it cannot hang forever.
  * Does NOT filter by size — path search must find large files too.
  */
-function walk(dir: string, out: string[], depth = 0): void {
-	if (depth > 12) return;
+function walk(dir: string, out: string[], state: { visited: number }, depth = 0): void {
+	if (depth > 12 || state.visited >= MAX_VISITED) return;
 	let entries: string[];
 	try {
 		entries = readdirSync(dir);
@@ -30,28 +35,30 @@ function walk(dir: string, out: string[], depth = 0): void {
 		return;
 	}
 	for (const entry of entries) {
-		if (out.length >= MAX_FILES) return; // enforce limit inside the loop
+		if (out.length >= MAX_FILES || state.visited >= MAX_VISITED) return; // in-loop bound
 		if (entry.startsWith(".") || SKIP_DIRS.has(entry)) continue;
 		const p = join(dir, entry);
+		state.visited++;
 		try {
 			const lst = lstatSync(p);
 			if (lst.isSymbolicLink()) continue; // never follow symlinks
-			if (lst.isDirectory()) walk(p, out, depth + 1);
-			else out.push(p);
+			if (lst.isDirectory()) walk(p, out, state, depth + 1);
+			else if (lst.isFile()) out.push(p); // regular files only
 		} catch {
 			// unreadable entries are skipped
 		}
 	}
 }
 
-/** Truncate by BYTE length (not UTF-16 chars), keeping complete lines. */
+/** Truncate by BYTE length, keep complete lines, reserve space for the marker. */
 function truncate(text: string, maxBytes = MAX_OUTPUT_BYTES): string {
 	const buf = Buffer.from(text, "utf8");
-	if (buf.length <= maxBytes) return text;
-	const cut = buf.subarray(0, maxBytes).toString("utf8");
+	const budget = maxBytes - Buffer.byteLength(TRUNCATE_MARKER);
+	if (buf.length <= budget) return text;
+	const cut = buf.subarray(0, budget).toString("utf8");
 	const lastNewline = cut.lastIndexOf("\n");
-	const base = lastNewline > 0 ? cut.slice(0, lastNewline) : cut;
-	return `${base}\n[output truncated]`;
+	if (lastNewline <= 0) return TRUNCATE_MARKER.trim(); // nothing complete fits
+	return `${cut.slice(0, lastNewline)}\n${TRUNCATE_MARKER}`;
 }
 
 export function grepFiles(opts: {
@@ -65,7 +72,7 @@ export function grepFiles(opts: {
 	const pattern = opts.caseSensitive ? opts.pattern : opts.pattern.toLowerCase();
 	const limit = opts.maxResults ?? 100;
 	const files: string[] = [];
-	walk(root, files);
+	walk(root, files, { visited: 0 });
 	const matches: FileMatch[] = [];
 	for (const file of files) {
 		if (matches.length >= limit) break;
@@ -98,7 +105,7 @@ export function grepFiles(opts: {
 export function findFiles(opts: { pattern?: string; path?: string; maxResults?: number; cwd: string }): string {
 	const root = resolve(opts.cwd, opts.path || ".");
 	const files: string[] = [];
-	walk(root, files);
+	walk(root, files, { visited: 0 });
 	const needle = opts.pattern?.toLowerCase();
 	// Match against the RELATIVE path so a pattern matching an ancestor
 	// directory does not hit every file, and rendered output stays relative.
@@ -121,13 +128,13 @@ export const grepSchema = Type.Object({
 	pattern: Type.String({ description: "Text to search for in file contents" }),
 	path: Type.Optional(Type.String({ description: "Directory to search (defaults to cwd)" })),
 	caseSensitive: Type.Optional(Type.Boolean({ description: "Case-sensitive match (default false)" })),
-	maxResults: Type.Optional(Type.Number({ description: "Max matches (default 100)" })),
+	maxResults: Type.Optional(Type.Integer({ minimum: 1, description: "Max matches (default 100)" })),
 });
 
 export const findSchema = Type.Object({
 	pattern: Type.Optional(Type.String({ description: "Substring to match in file path or name (empty lists all)" })),
 	path: Type.Optional(Type.String({ description: "Directory to search (defaults to cwd)" })),
-	maxResults: Type.Optional(Type.Number({ description: "Max results (default 100)" })),
+	maxResults: Type.Optional(Type.Integer({ minimum: 1, description: "Max results (default 100)" })),
 });
 
 export const lsSchema = Type.Object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tool-discipline",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "pi extension: enforce ffgrep/fffind-first search discipline and neutralize the default bash file-operation guideline",
   "type": "module",
   "license": "MIT",