pi-readseek 0.5.6 → 0.5.8

package/index.ts

@@ -12,16 +12,31 @@ import { SessionAnchors } from "./src/session-anchors.js";
 import { readSeekBinaryAvailability } from "./src/readseek-client.js";
 import { resolveReadSeekJsonSettings, type ReadSeekSettingsWarning } from "./src/readseek-settings.js";
 
-const READSEEK_TOOL_NAMES = [
-	"readSeek_read",
-	"readSeek_edit",
-	"readSeek_grep",
-	"readSeek_search",
-	"readSeek_refs",
-	"readSeek_rename",
-	"readSeek_hover",
-	"readSeek_write",
-	"readSeek_def",
+/** Built-in tool names that pi-readseek can replace with a readSeek-backed implementation. */
+const REPLACEABLE_TOOLS = {
+	read: "readSeek_read",
+	edit: "readSeek_edit",
+	write: "readSeek_write",
+	grep: "readSeek_grep",
+} as const;
+
+type ReplacedBuiltIn = keyof typeof REPLACEABLE_TOOLS;
+
+/**
+ * Canonical list of readSeek tools in registration/activation order. Each
+ * replaceable entry carries the built-in name it swaps in when replaced; null
+ * entries are readSeek-only and never replaced.
+ */
+const READSEEK_TOOL_ENTRIES: ReadonlyArray<{ builtIn: ReplacedBuiltIn | null; readSeekName: string }> = [
+	{ builtIn: "read", readSeekName: "readSeek_read" },
+	{ builtIn: "edit", readSeekName: "readSeek_edit" },
+	{ builtIn: "grep", readSeekName: "readSeek_grep" },
+	{ builtIn: null, readSeekName: "readSeek_search" },
+	{ builtIn: null, readSeekName: "readSeek_refs" },
+	{ builtIn: null, readSeekName: "readSeek_rename" },
+	{ builtIn: null, readSeekName: "readSeek_hover" },
+	{ builtIn: "write", readSeekName: "readSeek_write" },
+	{ builtIn: null, readSeekName: "readSeek_def" },
 ];
 
 function formatSettingsWarning(warning: ReadSeekSettingsWarning): string {
@@ -33,19 +48,45 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 	const markAnchored = (absolutePath: string) => sessionAnchors.markAnchored(absolutePath);
 	const hasFreshAnchors = (absolutePath: string) => sessionAnchors.hasFreshAnchors(absolutePath);
 
-	registerReadTool(pi, { onSuccessfulRead: markAnchored });
-	registerEditTool(pi, { wasReadInSession: hasFreshAnchors });
-	registerGrepTool(pi, { onFileAnchored: markAnchored });
+	// Resolve replacedTools at load time so the readSeek implementation is
+	// registered under the built-in name (e.g. "edit") when replaced. Extension
+	// tool registrations override built-ins of the same name in pi's tool
+	// definition registry, so registering under "edit" makes calls to `edit`
+	// dispatch to the readSeek implementation.
+	const { settings } = resolveReadSeekJsonSettings();
+	const replacedBuiltIns = new Set<ReplacedBuiltIn>(
+		(settings.replacedTools ?? []) as ReplacedBuiltIn[],
+	);
+	// Only swap registration under the built-in name when the readSeek binary
+	// is available; otherwise keep readSeek_* names so pi's built-ins stay
+	// intact and usable.
+	const binaryAvailable = readSeekBinaryAvailability().available;
+	const swap = (builtIn: ReplacedBuiltIn, readSeekName: string) =>
+		binaryAvailable && replacedBuiltIns.has(builtIn) ? builtIn : readSeekName;
+
+	const readName = swap("read", "readSeek_read");
+	const editName = swap("edit", "readSeek_edit");
+	const writeName = swap("write", "readSeek_write");
+	const grepName = swap("grep", "readSeek_grep");
+	const toolAliases = {
+		readSeek_read: readName,
+		readSeek_edit: editName,
+		readSeek_grep: grepName,
+		readSeek_write: writeName,
+	};
+
+	registerReadTool(pi, { onSuccessfulRead: markAnchored, name: readName });
+	registerEditTool(pi, { wasReadInSession: hasFreshAnchors, name: editName, toolAliases });
+	registerGrepTool(pi, { onFileAnchored: markAnchored, name: grepName });
 	registerSgTool(pi, { onFileAnchored: markAnchored });
 	registerRefsTool(pi, { onFileAnchored: markAnchored });
 	registerRenameTool(pi);
 	registerHoverTool(pi);
 	registerDefTool(pi, { onFileAnchored: markAnchored });
-	registerWriteTool(pi, { onFileAnchored: markAnchored });
+	registerWriteTool(pi, { onFileAnchored: markAnchored, name: writeName });
 
 	pi.on("session_start", (_event, ctx) => {
-		const { settings, warnings } = resolveReadSeekJsonSettings();
-		const replacedTools = new Set<string>(settings.replacedTools ?? []);
+		const { warnings } = resolveReadSeekJsonSettings();
 		const problems = warnings.map(formatSettingsWarning);
 
 		const availability = readSeekBinaryAvailability();
@@ -60,8 +101,24 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 
 		if (!availability.available) return;
 
-		const activeTools = [...pi.getActiveTools(), ...READSEEK_TOOL_NAMES]
-			.filter((name) => !replacedTools.has(name));
+		// readSeek tools were registered at load under names chosen from the
+		// load-time replacedTools. Replaced built-ins are registered under the
+		// built-in name, so the built-in stays active (now readSeek-backed);
+		// their readSeek_* variant was never registered and is excluded.
+		const activeReadSeekNames = READSEEK_TOOL_ENTRIES.map((entry) =>
+			entry.builtIn && replacedBuiltIns.has(entry.builtIn) ? entry.builtIn : entry.readSeekName,
+		);
+		const inactiveReadSeekNames = new Set(
+			READSEEK_TOOL_ENTRIES.filter(
+				(entry): entry is { builtIn: ReplacedBuiltIn; readSeekName: string } =>
+					entry.builtIn !== null && replacedBuiltIns.has(entry.builtIn),
+			).map((entry) => entry.readSeekName),
+		);
+
+		const activeTools = [...pi.getActiveTools(), ...activeReadSeekNames].filter(
+			(name) => !inactiveReadSeekNames.has(name),
+		);
 		pi.setActiveTools([...new Set(activeTools)]);
 	});
-}
+
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {

package/src/def.ts

@@ -15,7 +15,7 @@ import type { FileAnchoredCallback } from "./tool-types.js";
 
 const DEF_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/def.md", import.meta.url),
-	promptSnippet: "Find structural symbol definitions with readseek",
+	promptSnippet: "Find structural definitions for a symbol",
 });
 
 type DefParams = {

package/src/edit.ts

@@ -69,10 +69,6 @@ const hashlineEditSchema = Type.Object(
 
 type HashlineParams = Static<typeof hashlineEditSchema>;
 
-const EDIT_PROMPT_METADATA = defineToolPromptMetadata({
-	promptUrl: new URL("../prompts/edit.md", import.meta.url),
-	promptSnippet: "Edit files using hash-verified anchors from readSeek_read/readSeek_grep/readSeek_search/readSeek_write",
-});
 
 function buildEditError(
 	path: string,
@@ -110,6 +106,8 @@ function mapEditFileError(err: any, filePath: string, _displayPath: string, _pha
 export interface EditToolOptions {
 	wasReadInSession?: FreshAnchorsPredicate;
 	syntaxValidate?: SyntaxValidateOptions["syntaxValidate"];
+	name?: string;
+	toolAliases?: Readonly<Record<string, string>>;
 }
 
 export interface ExecuteEditOptions {
@@ -564,12 +562,19 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 
 
 export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}) {
+	const name = options.name ?? "readSeek_edit";
+	const promptMetadata = defineToolPromptMetadata({
+		promptUrl: new URL("../prompts/edit.md", import.meta.url),
+		promptSnippet: "Edit with fresh hash-verified anchors",
+		registeredName: name,
+		toolAliases: options.toolAliases,
+	});
 	const tool = registerReadSeekTool(pi, {
-		name: "readSeek_edit",
+		name,
 		label: "Edit",
-		description: EDIT_PROMPT_METADATA.description,
-		promptSnippet: EDIT_PROMPT_METADATA.promptSnippet,
-		promptGuidelines: EDIT_PROMPT_METADATA.promptGuidelines,
+		description: promptMetadata.description,
+		promptSnippet: promptMetadata.promptSnippet,
+		promptGuidelines: promptMetadata.promptGuidelines,
 		parameters: hashlineEditSchema,
 		renderShell: "default" as const,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/src/grep.ts

@@ -24,10 +24,6 @@ import type { FileAnchoredCallback } from "./tool-types.js";
 import { optionalIntOrString, registerReadSeekTool } from "./register-tool.js";
 import { searchPathParam } from "./readseek-params.js";
 
-const GREP_PROMPT_METADATA = defineToolPromptMetadata({
-	promptUrl: new URL("../prompts/grep.md", import.meta.url),
-	promptSnippet: "Search file contents and return edit-ready hashline anchors",
-});
 
 const grepSchema = Type.Object({
 	pattern: Type.String({ description: "Pattern to search" }),
@@ -169,6 +165,7 @@ function escapeForRegex(s: string): string {
 
 interface GrepToolOptions {
 	onFileAnchored?: FileAnchoredCallback;
+	name?: string;
 }
 
 export interface ExecuteGrepOptions {
@@ -513,13 +510,19 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 }
 
 export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}) {
+	const name = options.name ?? "readSeek_grep";
+	const promptMetadata = defineToolPromptMetadata({
+		promptUrl: new URL("../prompts/grep.md", import.meta.url),
+		promptSnippet: "Search file text with edit-ready anchors",
+		registeredName: name,
+	});
 	const tool = registerReadSeekTool(pi, {
-		name: "readSeek_grep",
+		name,
 		label: "grep",
-		description: GREP_PROMPT_METADATA.description,
+		description: promptMetadata.description,
 		parameters: grepSchema,
-		promptSnippet: GREP_PROMPT_METADATA.promptSnippet,
-		promptGuidelines: GREP_PROMPT_METADATA.promptGuidelines,
+		promptSnippet: promptMetadata.promptSnippet,
+		promptGuidelines: promptMetadata.promptGuidelines,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			return executeGrep({
 				toolCallId,

package/src/hover.ts

@@ -15,7 +15,7 @@ import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult,
 
 const HOVER_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/hover.md", import.meta.url),
-	promptSnippet: "Identify the identifier and enclosing symbol at a cursor position",
+	promptSnippet: "Identify a cursor token and enclosing symbol",
 });
 
 const hoverSchema = Type.Object({

package/src/read.ts

@@ -33,10 +33,6 @@ import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult,
 import type { FileAnchoredCallback } from "./tool-types.js";
 import { filePathParam, mapParam, optionalIntOrString, registerReadSeekTool } from "./register-tool.js";
 
-const READ_PROMPT_METADATA = defineToolPromptMetadata({
-	promptUrl: new URL("../prompts/read.md", import.meta.url),
-	promptSnippet: "Read text files or images; text reads include hashline anchors and optional maps/symbol lookup, image reads include the attachment plus OCR text, an image caption, and detected objects",
-});
 
 interface ReadParams {
 	path: string;
@@ -49,6 +45,7 @@ interface ReadParams {
 
 interface ReadToolOptions {
 	onSuccessfulRead?: FileAnchoredCallback;
+	name?: string;
 }
 
 export interface ExecuteReadOptions {
@@ -459,12 +456,18 @@ function splitReadSeekLines(text: string): string[] {
 }
 
 export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}) {
+	const name = options.name ?? "readSeek_read";
+	const promptMetadata = defineToolPromptMetadata({
+		promptUrl: new URL("../prompts/read.md", import.meta.url),
+		promptSnippet: "Read files or images with anchors, maps, symbols, and OCR",
+		registeredName: name,
+	});
 	const tool = registerReadSeekTool(pi, {
-		name: "readSeek_read",
+		name,
 		label: "Read",
-		description: READ_PROMPT_METADATA.description,
-		promptSnippet: READ_PROMPT_METADATA.promptSnippet,
-		promptGuidelines: READ_PROMPT_METADATA.promptGuidelines,
+		description: promptMetadata.description,
+		promptSnippet: promptMetadata.promptSnippet,
+		promptGuidelines: promptMetadata.promptGuidelines,
 		parameters: Type.Object({
 			path: filePathParam(),
 			offset: optionalIntOrString("Start line (1-indexed)"),

package/src/refs.ts

@@ -27,7 +27,7 @@ type RefsParams = {
 
 const REFS_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/refs.md", import.meta.url),
-  promptSnippet: "Find references to an identifier with readseek and return edit-ready anchors",
+  promptSnippet: "Find identifier references with enclosing symbols",
 });
 
 interface RefsToolOptions {

package/src/rename.ts

@@ -13,7 +13,7 @@ import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult,
 
 const RENAME_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/rename.md", import.meta.url),
-	promptSnippet: "Rename an identifier with binding-accurate readseek rename",
+	promptSnippet: "Rename a binding accurately from its cursor",
 });
 
 const renameSchema = Type.Object({

package/src/sg.ts

@@ -49,7 +49,7 @@ export function mergeRanges(ranges: SgRange[]): SgRange[] {
 
 const SG_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/sg.md", import.meta.url),
-  promptSnippet: "Search code structurally with readseek and return edit-ready anchors",
+  promptSnippet: "Search code by AST pattern with edit-ready anchors",
 });
 
 interface SgToolOptions {

package/src/tool-prompt-metadata.ts

@@ -12,24 +12,42 @@ const COMPACT_DESCRIPTIONS: Record<string, string> = {
   "refs.md": "Find references to an identifier and return anchored usages with enclosing symbols.",
 };
 
+const REPLACEABLE_TOOL_GUIDELINES: Record<string, { readSeekName: string; builtInName: string; benefit: string }> = {
+  "read.md": {
+    readSeekName: "readSeek_read",
+    builtInName: "read",
+    benefit: "it provides LINE:HASH anchors for safe edits.",
+  },
+  "edit.md": {
+    readSeekName: "readSeek_edit",
+    builtInName: "edit",
+    benefit: "it verifies fresh LINE:HASH anchors.",
+  },
+  "grep.md": {
+    readSeekName: "readSeek_grep",
+    builtInName: "grep",
+    benefit: "it returns edit-ready anchors.",
+  },
+  "write.md": {
+    readSeekName: "readSeek_write",
+    builtInName: "write",
+    benefit: "it returns LINE:HASH anchors.",
+  },
+};
+
 const COMPACT_GUIDELINES: Record<string, string[]> = {
   "read.md": [
-    "Use readSeek_read for file contents, images/screenshots, ranges, symbols, and edit anchors.",
-    "Use map or symbol mode before pulling large code files into context.",
-    "Use readSeek_read for images; it returns the image attachment plus OCR text, a caption, and detected objects, so you don't need separate OCR tools.",
+    "Use readSeek_read map or symbol mode before pulling large code files into context.",
+    "Use readSeek_read for images; it returns the image attachment plus OCR text, a caption, and detected objects.",
   ],
   "edit.md": [
-    "Use readSeek_edit with fresh LINE:HASH anchors for existing files.",
-    "Prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical.",
+    "With readSeek_edit, prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical.",
   ],
   "grep.md": [
-    "Use readSeek_grep for text search and edit-ready matching anchors.",
     "Use readSeek_grep summary mode for broad count/file discovery before narrowing.",
   ],
-
   "write.md": [
-    "Use readSeek_write to create files or intentionally overwrite whole files.",
-    "Use readSeek_edit rather than readSeek_write for small changes or appends to existing files.",
+    "Use anchored edits rather than readSeek_write for small changes or appends to existing files.",
   ],
   "sg.md": [
     "Use readSeek_search for AST-shaped code patterns.",
@@ -62,16 +80,41 @@ function promptFileName(promptUrl: URL): string {
   return promptUrl.pathname.split("/").pop() ?? "";
 }
 
+function rewriteToolAliases(value: string, toolAliases: Readonly<Record<string, string>> | undefined): string {
+  if (!toolAliases) return value;
+  return Object.entries(toolAliases).reduce(
+    (rewritten, [canonicalName, registeredName]) => rewritten.replaceAll(canonicalName, registeredName),
+    value,
+  );
+}
+
 export function defineToolPromptMetadata(options: {
   promptUrl: URL;
   promptSnippet: string;
+  registeredName?: string;
+  toolAliases?: Readonly<Record<string, string>>;
 }): ToolPromptMetadata {
   const prompt = loadPrompt(options.promptUrl);
   const fileName = promptFileName(options.promptUrl);
   const compactDescription = COMPACT_DESCRIPTIONS[fileName];
+  const replaceable = REPLACEABLE_TOOL_GUIDELINES[fileName];
+  const registeredName = options.registeredName ?? replaceable?.readSeekName;
+  const preferenceGuideline = replaceable && registeredName
+    ? registeredName === replaceable.readSeekName
+      ? `Prefer ${registeredName} over ${replaceable.builtInName} when both are available; ${replaceable.benefit}`
+      : `Use ${registeredName}; ${replaceable.benefit}`
+    : undefined;
   return {
-    description: compactDescription ?? firstPromptParagraph(prompt),
-    promptSnippet: options.promptSnippet,
-    promptGuidelines: COMPACT_GUIDELINES[fileName] ?? [],
+    description: rewriteToolAliases(compactDescription ?? firstPromptParagraph(prompt), options.toolAliases),
+    promptSnippet: rewriteToolAliases(options.promptSnippet, options.toolAliases),
+    promptGuidelines: [
+      ...(preferenceGuideline ? [preferenceGuideline] : []),
+      ...(COMPACT_GUIDELINES[fileName] ?? []).map((guideline) =>
+        rewriteToolAliases(
+          registeredName && replaceable ? guideline.replaceAll(replaceable.readSeekName, registeredName) : guideline,
+          options.toolAliases,
+        ),
+      ),
+    ],
   };
 }

package/src/write.ts

@@ -66,10 +66,6 @@ function pendingWritePreviewParts(summary: string, preview: PendingDiffPreviewRe
   return { lines: [summary, headerLine], diffData: expanded ? diffData : undefined };
 }
 
-const WRITE_PROMPT_METADATA = defineToolPromptMetadata({
-  promptUrl: new URL("../prompts/write.md", import.meta.url),
-  promptSnippet: "Create or overwrite a complete file and return edit anchors",
-});
 
 type WriteDiffFields = {
   diff?: string;
@@ -123,6 +119,7 @@ function generateWriteDiff(previousContent: string, nextContent: string): { diff
 
 export interface WriteToolOptions {
   onFileAnchored?: FileAnchoredCallback;
+  name?: string;
 }
 
 function buildWriteFsErrorResult(err: any, absolutePath: string) {
@@ -241,12 +238,18 @@ export async function executeWrite(opts: {
 }
 
 export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions = {}) {
+  const name = options.name ?? "readSeek_write";
+  const promptMetadata = defineToolPromptMetadata({
+    promptUrl: new URL("../prompts/write.md", import.meta.url),
+    promptSnippet: "Create or overwrite a file with edit anchors",
+    registeredName: name,
+  });
   const tool = registerReadSeekTool(pi, {
-    name: "readSeek_write",
+    name,
     label: "write",
-    description: WRITE_PROMPT_METADATA.description,
-    promptSnippet: WRITE_PROMPT_METADATA.promptSnippet,
-    promptGuidelines: WRITE_PROMPT_METADATA.promptGuidelines,
+    description: promptMetadata.description,
+    promptSnippet: promptMetadata.promptSnippet,
+    promptGuidelines: promptMetadata.promptGuidelines,
     parameters: Type.Object({
       path: filePathParam(),
       content: Type.String({ description: "File content" }),