pi-tool-discipline 0.1.4 → 0.1.6

package/README.md

@@ -21,18 +21,20 @@ tool, not bash").
 
 Two mechanisms, applied automatically in every session:
 
-1. **Placeholder tools (root fix).** Registers placeholder tools named
-   `grep`, `find`, and `ls` (skipped if already registered). They carry no
-   prompt snippet, so they never appear in the model's tool list and are never
-   callable in practice. Their mere presence flips pi's `hasGrep`/`hasFind`/
-   `hasLs` check, so the conflicting bash guideline is **never generated**.
+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.
-   Also strips the default bash guideline text in environments where the
-   placeholder registration is disabled.
+   `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.
 
 ## Install
 

package/extensions/index.ts

@@ -13,24 +13,28 @@
  *   rules that say to use the grep tool instead.
  *
  * How it works:
- *   A. Registers placeholder tools named `grep` / `find` / `ls` (skipped when
- *      already registered). They carry no promptSnippet, so they never appear
- *      in the model's tool list and are never actually callable in practice.
- *      Their presence flips pi's hasGrep/hasFind/hasLs check, so the
- *      conflicting bash guideline is never generated.
+ *   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.
  *   B. On before_agent_start, appends the tool-discipline rules to the system
- *      prompt (idempotent) and strips the bash guideline text as a fallback
- *      for environments where the placeholder registration is disabled.
+ *      prompt (idempotent) and strips the bash guideline text as a fallback.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { grepFiles, findFiles, listDir, grepSchema, findSchema, lsSchema } from "./search.js";
 
 const MARK = "<!-- pi-tool-discipline:v1 -->";
 
-/** Placeholder tool names that flip pi's hasGrep/hasFind/hasLs checks. */
+/** Tool names that flip pi's hasGrep/hasFind/hasLs checks. */
 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).
@@ -44,19 +48,49 @@ const BASH_GUIDELINES = [
 const DISCIPLINE = `
 ## Tool Discipline (pi-tool-discipline)
 
-Tool priority for search (always use the highest available):
+Search tool priority:
 
-- Content search: ffgrep (tool) > rg (bash) > grep (bash)
-- Path search: fffind (tool) > find (bash)
+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.
+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\`).`;
 
-Rules:
+interface FallbackTool {
+	label: string;
+	description: string;
+	snippet: string;
+	parameters: ReturnType<typeof Type.Object>;
+	execute: (params: any, cwd: string) => string;
+}
 
-- Search and read files ONLY with dedicated tools, never with bash commands.
-- ffgrep/fffind work with absolute paths outside the workspace (separate index), and ffgrep supports regex, path and exclude filters. If a search seems to miss something, adjust its parameters (path, exclude, regex, caseSensitive) — do NOT fall back to bash \`grep\`/\`rg\`/\`find\`/\`ls\`.
-- Read files with \`read\` (use \`offset\`/\`limit\` for large files); never use bash \`cat\`/\`head\`/\`tail\`/\`sed\` to read.
-- Do NOT use the bash tool for \`grep\`/\`rg\`/\`find\`/\`ls\`/\`cat\`/\`sed\`/\`head\`/\`tail\`/\`which\` searches or file reads.
-- Bash stays allowed only when dedicated tools cannot do the job: pipelines, git, npm, running programs, network requests, file mutations.
-- If bash searching is truly unavoidable, prefer \`rg\` over \`grep\`.`;
+const FALLBACK_TOOLS: Record<string, FallbackTool> = {
+	grep: {
+		label: "grep (fallback)",
+		description:
+			"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 }),
+	},
+	find: {
+		label: "find (fallback)",
+		description:
+			"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 }),
+	},
+	ls: {
+		label: "ls (fallback)",
+		description:
+			"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 }),
+	},
+};
 
 function stripBashGuidelines(prompt: string): string {
 	let out = prompt;
@@ -67,35 +101,56 @@ function stripBashGuidelines(prompt: string): string {
 }
 
 export default function toolDiscipline(pi: ExtensionAPI) {
-	// A. Register placeholder search tools so pi stops generating the bash guideline.
+	// A. Register search-tool names so pi stops generating the bash guideline.
 	// 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", () => {
-		const existing = new Set(pi.getAllTools().map((t) => t.name));
-		for (const name of PLACEHOLDER_NAMES) {
-			if (existing.has(name)) continue; // already present — the check already passes
+	pi.on("session_start", (event, ctx) => {
+		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");
+		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
+			const fallback = FALLBACK_TOOLS[name];
 			pi.registerTool({
-			name,
-			label: `${name} (placeholder)`,
-			description:
-				`Placeholder tool registered by pi-tool-discipline so pi knows a ${name} tool exists ` +
-				`and does not inject its default "use bash for file operations" guideline. ` +
-				`Do not call this tool — use ffgrep for content search and fffind for path search instead.`,
-			parameters: Type.Object({}),
-			async execute() {
-				return {
-					content: [
-						{
-							type: "text",
-							text: "This placeholder tool has no implementation. Use ffgrep for content search and fffind for path search instead.",
-						},
-					],
-					details: { placeholder: true },
-				};
-			},
-		});
-	}
+				name,
+				label: fallback.label,
+				description: fallback.description,
+				promptSnippet: fffActive ? undefined : fallback.snippet,
+				promptGuidelines: [
+					"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);
+					return {
+						content: [{ type: "text", text }],
+						details: { fallback: true },
+					};
+				},
+			});
+			registeredAny = true;
+		};
+		registerSearchTool("grep", hasFfgrep);
+		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.
+		if (registeredAny) (pi as unknown as { refreshTools: () => void }).refreshTools();
 	});
 
 	// B. Inject the discipline into the system prompt (idempotent per turn).
@@ -106,16 +161,21 @@ export default function toolDiscipline(pi: ExtensionAPI) {
 		return { systemPrompt: `${prompt}\n${MARK}\n${DISCIPLINE}` };
 	});
 
-	// Status command: /tool-discipline — verify placeholder tools and injection.
+	// Status command: /tool-discipline — verify tool registration and injection.
 	pi.registerCommand("tool-discipline", {
-		description: "Show pi-tool-discipline status (placeholder tools + injected guideline)",
+		description: "Show pi-tool-discipline status (tools + injected guideline)",
 		handler: async (_args, ctx) => {
-			const tools = pi.getAllTools().map((t) => t.name);
-			const placeholders = PLACEHOLDER_NAMES.filter((n) => tools.includes(n));
+			const all = new Set(pi.getAllTools().map((t) => t.name));
+			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 injected = ctx.getSystemPrompt().includes(MARK);
 			ctx.ui.notify(
 				`pi-tool-discipline\n` +
-					`placeholder tools: ${placeholders.length > 0 ? placeholders.join(", ") : "(none)"}\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` +
 					`discipline injected: ${injected ? "yes" : "no"}`,
 				"info",
 			);

package/extensions/search.ts

@@ -0,0 +1,135 @@
+/**
+ * Fallback search implementations for environments without @ff-labs/pi-fff.
+ * Pure Node fs-based; no shell, no external deps.
+ */
+import { readdirSync, readFileSync, statSync, lstatSync } from "fs";
+import { join, resolve, relative } from "path";
+import { Type } from "typebox";
+
+const SKIP_DIRS = new Set(["node_modules", ".git", ".hg", ".svn"]);
+const MAX_FILES = 2000;
+const MAX_FILE_BYTES = 1024 * 1024; // content search skips files larger than 1 MiB
+const MAX_OUTPUT_BYTES = 50 * 1024;
+
+interface FileMatch {
+	file: string;
+	line: number;
+	text: string;
+}
+
+/**
+ * Collect files under dir (depth-limited, symlink-safe, bounded).
+ * 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;
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (out.length >= MAX_FILES) return; // enforce limit inside the loop
+		if (entry.startsWith(".") || SKIP_DIRS.has(entry)) continue;
+		const p = join(dir, entry);
+		try {
+			const lst = lstatSync(p);
+			if (lst.isSymbolicLink()) continue; // never follow symlinks
+			if (lst.isDirectory()) walk(p, out, depth + 1);
+			else out.push(p);
+		} catch {
+			// unreadable entries are skipped
+		}
+	}
+}
+
+/** Truncate by BYTE length (not UTF-16 chars), keeping complete lines. */
+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 lastNewline = cut.lastIndexOf("\n");
+	const base = lastNewline > 0 ? cut.slice(0, lastNewline) : cut;
+	return `${base}\n[output truncated]`;
+}
+
+export function grepFiles(opts: {
+	pattern: string;
+	path?: string;
+	caseSensitive?: boolean;
+	maxResults?: number;
+	cwd: string;
+}): string {
+	const root = 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);
+	const matches: FileMatch[] = [];
+	for (const file of files) {
+		if (matches.length >= limit) break;
+		try {
+			if (statSync(file).size > MAX_FILE_BYTES) continue; // cap only before reading content
+		} catch {
+			continue;
+		}
+		let content: string;
+		try {
+			content = readFileSync(file, "utf8");
+		} catch {
+			continue;
+		}
+		const lines = content.split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			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) });
+				if (matches.length >= limit) break;
+			}
+		}
+	}
+	if (matches.length === 0) return "No matches found";
+	let out = "";
+	for (const m of matches) out += `${m.file}:${m.line}: ${m.text}\n`;
+	return truncate(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);
+	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"));
+}
+
+export function listDir(opts: { path?: string; cwd: string }): string {
+	const dir = resolve(opts.cwd, opts.path || ".");
+	try {
+		return truncate(readdirSync(dir).join("\n"));
+	} catch (error: any) {
+		return `Error listing ${dir}: ${error.message}`;
+	}
+}
+
+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)" })),
+});
+
+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)" })),
+});
+
+export const lsSchema = Type.Object({
+	path: Type.Optional(Type.String({ description: "Directory to list (defaults to cwd)" })),
+});

package/package.json

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