pi-tool-discipline 0.1.7 → 0.1.9

package/README.md

@@ -28,8 +28,9 @@ Two mechanisms, applied automatically in every session:
    `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).
+   (`extensions/search.ts`) are registered instead, with their text snippet
+   suppressed while `ffgrep`/`fffind` from pi-fff are active (the registered
+   tool schema remains present either way).
 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`
@@ -46,8 +47,9 @@ pi install npm:pi-tool-discipline
 pi -e npm:pi-tool-discipline
 ```
 
-Requires `@ff-labs/pi-fff` (or any other extension providing `ffgrep`/`fffind`)
-for the discipline to point at real search tools.
+Requires nothing extra. With `@ff-labs/pi-fff` installed, the model prefers
+`ffgrep`/`fffind`; without it, Pi's built-in `grep`/`find`/`ls` tools (activated
+by this extension, or fs-based fallbacks on older pi versions) are used.
 
 ## Verify
 
@@ -66,10 +68,15 @@ This extension runs with full system access like any pi extension. What it does:
 - 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.
+**Disclosure:** pi's built-in `grep`/`find` tools execute the `rg`/`fd`
+binaries, and pi may auto-download those binaries from GitHub on first use
+(`ensureTool`). This extension itself does not execute commands, write files,
+or touch the network — that claim covers only its own fs-based fallback
+implementations, not the pi built-ins it activates.
+
+The fallback search tools only read. Note that any installed tool, including
+this one, can be invoked by the model. Review the source in `extensions/`
+before installing.
 
 ## License
 

package/extensions/index.ts

@@ -28,6 +28,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { grepFiles, findFiles, listDir, grepSchema, findSchema, lsSchema } from "./search.js";
+import { stripBashGuidelines } from "./strip.js";
 
 const MARK = "<!-- pi-tool-discipline:v1 -->";
 
@@ -37,24 +38,14 @@ const PLACEHOLDER_NAMES = ["grep", "find", "ls"] as const;
 /** FFF search tools that indicate pi-fff (or equivalent) is installed. */
 const FFF_TOOLS = ["ffgrep", "fffind"];
 
-/**
- * The exact guidelines pi's builder injects when no search tool is active.
- * Stripped from the system prompt as a fallback (plan B).
- */
-const BASH_GUIDELINES = [
-	"Use bash for file operations like ls, rg, find",
-	"Use bash or PowerShell for file operations like listing, searching, and finding files",
-	"Use PowerShell for file operations like listing, searching, and finding files",
-];
-
 const DISCIPLINE = `
 ## Tool Discipline (pi-tool-discipline)
 
 Search tool priority:
 
 1. ffgrep / fffind (from @ff-labs/pi-fff) — always preferred. They work with absolute paths outside the workspace and support regex / path / exclude filters.
-2. Without pi-fff, use the grep / find / ls TOOLS (fallbacks provided by this extension). If a search seems to miss something, adjust its parameters (path, caseSensitive, maxResults) — never fall back to bash's grep or find.
-3. Never run bash \`grep\` or \`find\`. Never use bash \`ls\`/\`cat\`/\`head\`/\`tail\`/\`sed\`/\`which\` directly for searching or reading — use ffgrep / fffind / read (or the grep/find/ls fallback tools) instead.
+2. Without pi-fff, use the grep / find / ls TOOLS (Pi built-ins on pi 0.84+, fs fallbacks on older versions). Fill their parameters according to each tool's declared schema — built-in grep uses ignoreCase/limit, built-in find uses a glob pattern. Never fall back to bash's grep or find.
+3. Never run bash \`grep\` or \`find\`. Never use bash \`ls\`/\`cat\`/\`head\`/\`tail\`/\`sed\`/\`which\` directly for searching or reading — use ffgrep / fffind / read (or the grep/find/ls tools) instead.
 4. Read files with \`read\` (offset/limit for large files).
 5. Bash stays allowed only when dedicated tools cannot do the job: pipelines, git, npm, running programs, network requests, file mutations.
 6. If bash searching is truly unavoidable, use \`rg\` (never \`grep\`).`;
@@ -64,7 +55,7 @@ interface FallbackTool {
 	description: string;
 	snippet: string;
 	parameters: ReturnType<typeof Type.Object>;
-	execute: (params: any, cwd: string) => string;
+	execute: (params: any, cwd: string, signal?: AbortSignal) => Promise<string>;
 }
 
 const FALLBACK_TOOLS: Record<string, FallbackTool> = {
@@ -74,7 +65,7 @@ const FALLBACK_TOOLS: Record<string, FallbackTool> = {
 			"Search file contents for a text pattern. Fallback for environments without ffgrep; prefer ffgrep when available.",
 		snippet: "Search file contents (fallback when ffgrep is unavailable)",
 		parameters: grepSchema,
-		execute: (params, cwd) => grepFiles({ ...params, cwd }),
+		execute: async (params, cwd, signal) => grepFiles({ ...params, cwd, signal }),
 	},
 	find: {
 		label: "find (fallback)",
@@ -82,7 +73,7 @@ const FALLBACK_TOOLS: Record<string, FallbackTool> = {
 			"Find files by path/name substring. Fallback for environments without fffind; prefer fffind when available.",
 		snippet: "Find files by path/name (fallback when fffind is unavailable)",
 		parameters: findSchema,
-		execute: (params, cwd) => findFiles({ ...params, cwd }),
+		execute: async (params, cwd, signal) => findFiles({ ...params, cwd, signal }),
 	},
 	ls: {
 		label: "ls (fallback)",
@@ -90,18 +81,10 @@ const FALLBACK_TOOLS: Record<string, FallbackTool> = {
 			"List directory entries. Fallback for environments without fffind; prefer fffind when available.",
 		snippet: "List directory entries (fallback when fffind is unavailable)",
 		parameters: lsSchema,
-		execute: (params, cwd) => listDir({ ...params, cwd }),
+		execute: async (params, cwd, signal) => listDir({ ...params, cwd, signal }),
 	},
 };
 
-function stripBashGuidelines(prompt: string): string {
-	let out = prompt;
-	for (const guideline of BASH_GUIDELINES) {
-		out = out.replaceAll(guideline, "Use ffgrep/fffind for file operations like ls, rg, find");
-	}
-	return out;
-}
-
 export default function toolDiscipline(pi: ExtensionAPI) {
 	// A. Register search-tool names so pi stops generating the bash guideline.
 	// Done in session_start: action methods (getAllTools/registerTool) are not
@@ -140,8 +123,8 @@ export default function toolDiscipline(pi: ExtensionAPI) {
 					"Use ffgrep/fffind when they are available; grep/find/ls are fallbacks only for environments without pi-fff.",
 				],
 				parameters: fallback.parameters,
-				async execute(_toolCallId, params, _signal, _onUpdate, execCtx) {
-					const text = fallback.execute(params ?? {}, execCtx.cwd);
+				async execute(_toolCallId, params, signal, _onUpdate, execCtx) {
+					const text = await fallback.execute(params ?? {}, execCtx.cwd, signal);
 					return {
 						content: [{ type: "text", text }],
 						details: { fallback: true },

package/extensions/search.ts

@@ -1,8 +1,8 @@
 /**
  * Fallback search implementations for environments without @ff-labs/pi-fff.
- * Pure Node fs-based; no shell, no external deps.
+ * Pure Node fs-based (async, abort-aware); no shell, no external deps.
  */
-import { readdirSync, readFileSync, statSync, lstatSync } from "fs";
+import { readdir, readFile, stat, lstat } from "fs/promises";
 import { join, resolve, relative } from "path";
 import { Type } from "typebox";
 
@@ -12,6 +12,16 @@ 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]";
+const CAPPED_MARKER = "\n[search capped — traversal stopped early]";
+
+/** Cancellation error, matching pi built-in tools ("Operation aborted"). */
+function abortError(): Error {
+	return new Error("Operation aborted");
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+	if (signal?.aborted) throw abortError();
+}
 
 interface FileMatch {
 	file: string;
@@ -19,76 +29,121 @@ interface FileMatch {
 	text: string;
 }
 
+interface WalkState {
+	visited: number;
+	capped: boolean;
+	rootError?: string;
+}
+
 /**
- * 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.
+ * Collect regular files under dir (depth-limited, symlink-safe, bounded,
+ * abort-aware). Only isFile() entries are collected — FIFOs, devices, sockets
+ * would block a read. Individual OS filesystem requests may still be
+ * uninterruptible, but the signal is checked before/after every operation.
+ * A failure to read the REQUESTED ROOT (depth 0) is recorded in rootError;
+ * nested unreadable entries are skipped.
  */
-function walk(dir: string, out: string[], state: { visited: number }, depth = 0): void {
-	if (depth > 12 || state.visited >= MAX_VISITED) return;
+async function walk(dir: string, out: string[], state: WalkState, signal?: AbortSignal, depth = 0): Promise<void> {
+	throwIfAborted(signal);
+	if (depth > 12 || state.visited >= MAX_VISITED) {
+		state.capped = true;
+		return;
+	}
 	let entries: string[];
 	try {
-		entries = readdirSync(dir);
-	} catch {
+		entries = await readdir(dir);
+	} catch (error: any) {
+		if (depth === 0) state.rootError = error?.message ?? String(error);
 		return;
 	}
+	throwIfAborted(signal);
 	for (const entry of entries) {
-		if (out.length >= MAX_FILES || state.visited >= MAX_VISITED) return; // in-loop bound
+		if (out.length >= MAX_FILES || state.visited >= MAX_VISITED) {
+			state.capped = true;
+			return; // in-loop bound
+		}
 		if (entry.startsWith(".") || SKIP_DIRS.has(entry)) continue;
 		const p = join(dir, entry);
 		state.visited++;
 		try {
-			const lst = lstatSync(p);
+			const lst = await lstat(p);
+			throwIfAborted(signal);
 			if (lst.isSymbolicLink()) continue; // never follow symlinks
-			if (lst.isDirectory()) walk(p, out, state, depth + 1);
+			if (lst.isDirectory()) await walk(p, out, state, signal, depth + 1);
 			else if (lst.isFile()) out.push(p); // regular files only
-		} catch {
+		} catch (error: any) {
+			if (error?.message === "Operation aborted") throw error;
 			// unreadable entries are skipped
 		}
 	}
 }
 
-/** Truncate by BYTE length, keep complete lines, reserve space for the marker. */
-function truncate(text: string, maxBytes = MAX_OUTPUT_BYTES): string {
+/**
+ * Truncate by BYTE length, keep complete lines, reserve space for all markers.
+ * Returns the original text unchanged when it fits within maxBytes.
+ */
+function truncate(text: string, maxBytes = MAX_OUTPUT_BYTES, extraMarkerBytes = 0): string {
 	const buf = Buffer.from(text, "utf8");
-	const budget = maxBytes - Buffer.byteLength(TRUNCATE_MARKER);
-	if (buf.length <= budget) return text;
+	if (buf.length <= maxBytes) return text;
+	const budget = maxBytes - Buffer.byteLength(TRUNCATE_MARKER) - extraMarkerBytes;
+	if (budget <= 0) return TRUNCATE_MARKER.trim();
 	const cut = buf.subarray(0, budget).toString("utf8");
 	const lastNewline = cut.lastIndexOf("\n");
 	if (lastNewline <= 0) return TRUNCATE_MARKER.trim(); // nothing complete fits
 	return `${cut.slice(0, lastNewline)}\n${TRUNCATE_MARKER}`;
 }
 
-export function grepFiles(opts: {
+async function resolveRoot(cwd: string, sub?: string): Promise<string | null> {
+	const root = resolve(cwd, sub || ".");
+	try {
+		const st = await stat(root);
+		return st.isDirectory() ? root : null;
+	} catch {
+		return null;
+	}
+}
+
+function walkFiles(root: string, signal?: AbortSignal): Promise<{ files: string[]; state: WalkState }> {
+	const files: string[] = [];
+	const state: WalkState = { visited: 0, capped: false };
+	return walk(root, files, state, signal).then(() => ({ files, state }));
+}
+
+export async function grepFiles(opts: {
 	pattern: string;
 	path?: string;
 	caseSensitive?: boolean;
 	maxResults?: number;
 	cwd: string;
-}): string {
-	const root = resolve(opts.cwd, opts.path || ".");
+	signal?: AbortSignal;
+}): Promise<string> {
+	throwIfAborted(opts.signal);
+	const root = await resolveRoot(opts.cwd, opts.path);
+	if (!root) return `Error: search path not found: ${resolve(opts.cwd, opts.path || ".")}`;
 	const pattern = opts.caseSensitive ? opts.pattern : opts.pattern.toLowerCase();
 	const limit = opts.maxResults ?? 100;
-	const files: string[] = [];
-	walk(root, files, { visited: 0 });
+	const { files, state } = await walkFiles(root, opts.signal);
+	if (state.rootError) return `Error: cannot read search root ${root}: ${state.rootError}`;
 	const matches: FileMatch[] = [];
 	for (const file of files) {
+		throwIfAborted(opts.signal);
 		if (matches.length >= limit) break;
 		try {
-			if (statSync(file).size > MAX_FILE_BYTES) continue; // cap only before reading content
+			if ((await stat(file)).size > MAX_FILE_BYTES) continue; // cap only before reading content
 		} catch {
 			continue;
 		}
+		throwIfAborted(opts.signal);
 		let content: string;
 		try {
-			content = readFileSync(file, "utf8");
+			content = await readFile(file, "utf8");
 		} catch {
 			continue;
 		}
+		throwIfAborted(opts.signal);
 		const lines = content.split("\n");
 		for (let i = 0; i < lines.length; i++) {
+			throwIfAborted(opts.signal);
 			const haystack = opts.caseSensitive ? lines[i] : lines[i].toLowerCase();
 			if (haystack.includes(pattern)) {
 				matches.push({ file: relative(root, file), line: i + 1, text: lines[i].trim().slice(0, 200) });
@@ -96,31 +151,58 @@ export function grepFiles(opts: {
 			}
 		}
 	}
-	if (matches.length === 0) return "No matches found";
+	if (matches.length === 0) return state.capped ? `No matches found${CAPPED_MARKER}` : "No matches found";
 	let out = "";
 	for (const m of matches) out += `${m.file}:${m.line}: ${m.text}\n`;
-	return truncate(out);
+	out = truncate(out, MAX_OUTPUT_BYTES, state.capped ? Buffer.byteLength(CAPPED_MARKER) : 0);
+	if (state.capped) out += CAPPED_MARKER;
+	return out;
 }
 
-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, { visited: 0 });
+export async function findFiles(opts: {
+	pattern?: string;
+	path?: string;
+	maxResults?: number;
+	cwd: string;
+	signal?: AbortSignal;
+}): Promise<string> {
+	throwIfAborted(opts.signal);
+	const root = await resolveRoot(opts.cwd, opts.path);
+	if (!root) return `Error: search path not found: ${resolve(opts.cwd, opts.path || ".")}`;
+	const { files, state } = await walkFiles(root, opts.signal);
+	if (state.rootError) return `Error: cannot read search root ${root}: ${state.rootError}`;
 	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.
-	const rel = files.map((f) => relative(root, f));
-	const hits = needle ? rel.filter((r) => r.toLowerCase().includes(needle)) : rel;
-	if (hits.length === 0) return "No matching files found";
-	return truncate(hits.slice(0, opts.maxResults ?? 100).join("\n"));
+	const rel: string[] = [];
+	for (const f of files) {
+		throwIfAborted(opts.signal);
+		rel.push(relative(root, f));
+	}
+	const hits: string[] = [];
+	for (const r of rel) {
+		throwIfAborted(opts.signal);
+		if (!needle || r.toLowerCase().includes(needle)) hits.push(r);
+		if (hits.length >= (opts.maxResults ?? 100)) break;
+	}
+	if (hits.length === 0) return state.capped ? `No matching files found${CAPPED_MARKER}` : "No matching files found";
+	let out = truncate(hits.join("\n"), MAX_OUTPUT_BYTES, state.capped ? Buffer.byteLength(CAPPED_MARKER) : 0);
+	if (state.capped) out += CAPPED_MARKER;
+	return out;
 }
 
-export function listDir(opts: { path?: string; cwd: string }): string {
-	const dir = resolve(opts.cwd, opts.path || ".");
+export async function listDir(opts: { path?: string; cwd: string; signal?: AbortSignal }): Promise<string> {
+	throwIfAborted(opts.signal);
+	const root = await resolveRoot(opts.cwd, opts.path);
+	if (!root) return `Error: directory not found: ${resolve(opts.cwd, opts.path || ".")}`;
 	try {
-		return truncate(readdirSync(dir).join("\n"));
+		const entries = await readdir(root);
+		throwIfAborted(opts.signal);
+		if (entries.length === 0) return "(empty directory)";
+		return truncate(entries.join("\n"));
 	} catch (error: any) {
-		return `Error listing ${dir}: ${error.message}`;
+		if (error?.message === "Operation aborted") throw error;
+		return `Error listing ${root}: ${error.message}`;
 	}
 }
 

package/extensions/strip.ts

@@ -0,0 +1,23 @@
+/**
+ * Whole-line stripping of pi's generated bash file-operation guidelines.
+ * Kept dependency-free so it is testable outside the pi runtime.
+ */
+
+/**
+ * Strip only the exact generated guideline bullets, line-anchored (whole-line,
+ * global), so quoted references inside project instructions or custom prompts
+ * are not rewritten. Activation normally prevents pi from generating these
+ * anyway; this is a belt-and-suspenders fallback.
+ */
+export function stripBashGuidelines(prompt: string): string {
+	return prompt
+		.replace(/^- Use bash for file operations like ls, rg, find(?=\r?$)/gm, "- Use ffgrep/fffind for file operations like ls, rg, find")
+		.replace(
+			/^- Use bash or PowerShell for file operations like listing, searching, and finding files(?=\r?$)/gm,
+			"- Use ffgrep/fffind for file operations like listing, searching, and finding files",
+		)
+		.replace(
+			/^- Use PowerShell for file operations like listing, searching, and finding files(?=\r?$)/gm,
+			"- Use ffgrep/fffind for file operations like listing, searching, and finding files",
+		);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tool-discipline",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "pi extension: enforce ffgrep/fffind-first search discipline and neutralize the default bash file-operation guideline",
   "type": "module",
   "license": "MIT",
@@ -37,16 +37,17 @@
     "access": "public"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types test/fallback.test.mjs"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@sinclair/typebox": "*"
+    "typebox": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@sinclair/typebox": "*",
     "@types/node": "^22.0.0",
+    "typebox": "*",
     "typescript": "^5.0.0"
   }
 }