pi-readseek 0.5.7 → 0.5.9

package/index.ts

@@ -68,9 +68,15 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 	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 });
+	registerEditTool(pi, { wasReadInSession: hasFreshAnchors, name: editName, toolAliases });
 	registerGrepTool(pi, { onFileAnchored: markAnchored, name: grepName });
 	registerSgTool(pi, { onFileAnchored: markAnchored });
 	registerRefsTool(pi, { onFileAnchored: markAnchored });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {
@@ -39,7 +39,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.5.1",
+    "@jarkkojs/readseek": "^0.5.2",
     "diff": "^8.0.3",
     "xxhash-wasm": "^1.1.0"
   },

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,
@@ -111,6 +107,7 @@ export interface EditToolOptions {
 	wasReadInSession?: FreshAnchorsPredicate;
 	syntaxValidate?: SyntaxValidateOptions["syntaxValidate"];
 	name?: string;
+	toolAliases?: Readonly<Record<string, string>>;
 }
 
 export interface ExecuteEditOptions {
@@ -565,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: options.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" }),
@@ -514,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: options.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;
@@ -460,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: options.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;
@@ -242,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: options.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" }),