pi-readseek 0.3.22 → 0.3.24

package/package.json

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

package/src/coerce-obvious-int.ts

@@ -1,30 +1,41 @@
 const BASE10_INT_RE = /^-?\d+$/;
+const MIN_SAFE_INTEGER = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
 
 type CoercedIntResult =
   | { ok: true; value: number | undefined }
   | { ok: false; message: string };
 
+function formatReceived(value: unknown): string {
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return JSON.stringify(value) ?? String(value);
+}
+
+function invalidInteger(value: unknown, name: string): CoercedIntResult {
+  return {
+    ok: false,
+    message: `Invalid ${name}: expected a safe base-10 integer, received ${formatReceived(value)}.`,
+  };
+}
+
 export function coerceObviousBase10Int(value: unknown, name: string): CoercedIntResult {
   if (value === undefined) {
     return { ok: true, value: undefined };
   }
 
   if (typeof value === "number") {
-    if (Number.isInteger(value)) {
+    if (Number.isSafeInteger(value)) {
       return { ok: true, value };
     }
-    return {
-      ok: false,
-      message: `Invalid ${name}: expected a base-10 integer, received ${value}.`,
-    };
+    return invalidInteger(value, name);
   }
 
   if (typeof value === "string" && BASE10_INT_RE.test(value)) {
-    return { ok: true, value: Number.parseInt(value, 10) };
+    const parsed = BigInt(value);
+    if (parsed >= MIN_SAFE_INTEGER && parsed <= MAX_SAFE_INTEGER) {
+      return { ok: true, value: Number(parsed) };
+    }
   }
 
-  return {
-    ok: false,
-    message: `Invalid ${name}: expected a base-10 integer, received ${JSON.stringify(value)}.`,
-  };
+  return invalidInteger(value, name);
 }

package/src/edit-output.ts

@@ -19,6 +19,19 @@ export interface EditOutputResult {
   patch: string;
   readseekValue: ReturnType<typeof buildReadseekEditResult>;
 }
+
+const EDIT_OPERATION_NAMES = ["set_line", "replace_lines", "insert_after", "replace"] as const;
+
+type EditOperationName = (typeof EDIT_OPERATION_NAMES)[number];
+
+type EditOperationWithNewText = {
+  new_text: string;
+};
+
+function hasNewText(value: unknown): value is EditOperationWithNewText {
+  return typeof value === "object" && value !== null && typeof (value as { new_text?: unknown }).new_text === "string";
+}
+
 function getVisibleDiffStats(diff: string): { added: number; removed: number } {
   const stats = parseDiffStats(diff);
   if (stats.added > 0 || stats.removed > 0) return stats;
@@ -49,10 +62,12 @@ function extractNewTextValues(edits: unknown[] | undefined): string[] {
   const values: string[] = [];
   for (const edit of edits ?? []) {
     if (!edit || typeof edit !== "object") continue;
-    if ("set_line" in edit && typeof (edit as any).set_line?.new_text === "string") values.push((edit as any).set_line.new_text);
-    if ("replace_lines" in edit && typeof (edit as any).replace_lines?.new_text === "string") values.push((edit as any).replace_lines.new_text);
-    if ("insert_after" in edit && typeof (edit as any).insert_after?.new_text === "string") values.push((edit as any).insert_after.new_text);
-    if ("replace" in edit && typeof (edit as any).replace?.new_text === "string") values.push((edit as any).replace.new_text);
+
+    const operations = edit as Partial<Record<EditOperationName, unknown>>;
+    for (const operationName of EDIT_OPERATION_NAMES) {
+      const operation = operations[operationName];
+      if (hasNewText(operation)) values.push(operation.new_text);
+    }
   }
   return values;
 }
@@ -62,10 +77,13 @@ function formatWhitespaceOnlyWarning(semanticSummary: SemanticSummary | undefine
   return "⚠ Edit classified as whitespace-only — if you intended a behavior change, re-read to verify.";
 }
 function formatSemanticSuffix(semanticSummary: SemanticSummary | undefined): string {
-  const movedBlocks = semanticSummary?.movedBlocks ?? 0;
+  if (!semanticSummary) return "";
+
+  const movedBlocks = semanticSummary.movedBlocks ?? 0;
   if (movedBlocks <= 0) return "";
+
   const blockWord = movedBlocks === 1 ? "block" : "blocks";
-  return ` [semantic: ${semanticSummary!.classification}, ${movedBlocks} ${blockWord} moved]`;
+  return ` [semantic: ${semanticSummary.classification}, ${movedBlocks} ${blockWord} moved]`;
 }
 function formatReplaceHint(edits: unknown[] | undefined, noopEdits: unknown[]): string | undefined {
   if ((noopEdits ?? []).length > 0) return undefined;

package/src/edit.ts

@@ -20,9 +20,10 @@ import { resolveSyntaxValidateMode, type SyntaxValidateOptions } from "./syntax-
 import { replaceSymbol } from "./replace-symbol.js";
 import { buildEditPreviewKey, buildPendingEditPreviewData, resolvePendingDiffPreview, type PendingDiffPreviewResult } from "./pending-diff-preview.js";
 import { buildDiffData, type DiffBlockRange } from "./diff-data.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import { DiffPreviewComponent } from "./tui-diff-component.js";
 import type { FreshAnchorsPredicate } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 import { resolveEditDiffDisplay } from "./readseek-settings.js";
 
@@ -566,22 +567,17 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 
 
 export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "mutating" as const,
-		readOnly: false,
+	const tool = registerReadseekTool(pi, {
+		policy: "mutating",
 		pythonName: "edit",
-		defaultExposure: "not-safe-by-default" as const,
-	};
-	const tool = {
+		defaultExposure: "not-safe-by-default",
+	}, {
 		name: "edit",
 		label: "Edit",
 		description: EDIT_PROMPT_METADATA.description,
 		promptSnippet: EDIT_PROMPT_METADATA.promptSnippet,
 		promptGuidelines: EDIT_PROMPT_METADATA.promptGuidelines,
 		parameters: hashlineEditSchema,
-		ptc: toolConfig,
 		renderShell: "default" as const,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			return executeEdit({
@@ -645,7 +641,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			const { isPartial, isError, expanded: baseExpanded, width, context } = resolveRenderResultContext(options, rest);
 
 			if (isPartial) {
-				return new Text(clampLinesToWidth([summaryLine("pending edit")], width).join("\n"), 0, 0);
+				return renderPendingResult("pending edit", width);
 			}
 
 			// Extract data from result
@@ -698,8 +694,6 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			}
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
-	} satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-	pi.registerTool(tool);
+	});
 	return tool;
 }

package/src/grep-output.ts

@@ -47,6 +47,14 @@ export interface GrepOutputGroup {
   };
 }
 
+type ScopedGrepOutputGroup = GrepOutputGroup & {
+  scope: NonNullable<GrepOutputGroup["scope"]>;
+};
+
+function hasScope(group: GrepOutputGroup): group is ScopedGrepOutputGroup {
+  return group.scope !== undefined;
+}
+
 export interface BuildGrepOutputInput {
   summary: boolean;
   totalMatches: number;
@@ -100,13 +108,13 @@ function buildScopeMetadata(groups: GrepOutputGroup[], warnings: GrepScopeWarnin
   return {
     mode: "symbol" as const,
     groups: groups
-      .filter((group) => group.scope)
+      .filter(hasScope)
       .map((group) => ({
         path: group.absolutePath,
         displayPath: group.displayPath,
-        symbol: group.scope!.symbol,
+        symbol: group.scope.symbol,
         matchCount: group.matchCount,
-        matchLines: [...group.scope!.matchLines],
+        matchLines: [...group.scope.matchLines],
         lineAnchors: group.entries.flatMap((entry) => (entry.kind === "separator" ? [] : [entry.line.anchor])),
       })),
     warnings: [...warnings],
@@ -132,14 +140,16 @@ export function buildGrepOutput(input: BuildGrepOutputInput): GrepOutputResult {
     }
     text = blocks.join("\n");
   }
-  if ((input.passthroughLines?.length ?? 0) > 0) {
-    text += `\n\n${input.passthroughLines!.join("\n")}`;
+  const passthroughLines = input.passthroughLines ?? [];
+  if (passthroughLines.length > 0) {
+    text += `\n\n${passthroughLines.join("\n")}`;
   }
   if (input.limit !== undefined && input.totalMatches === input.limit) {
     text += `\n\n[Results truncated at ${input.limit} matches — refine pattern or increase limit]`;
   }
-  if (!input.summary && input.scopeMode === "symbol" && (input.scopeWarnings?.length ?? 0) > 0) {
-    text = `${input.scopeWarnings!.map((warning) => warning.message).join("\n\n")}\n\n${text}`;
+  const scopeWarnings = input.scopeWarnings ?? [];
+  if (!input.summary && input.scopeMode === "symbol" && scopeWarnings.length > 0) {
+    text = `${scopeWarnings.map((warning) => warning.message).join("\n\n")}\n\n${text}`;
   }
   const budget = resolveGrepOutputBudget();
   const truncated = truncateHead(text, {
@@ -161,7 +171,7 @@ export function buildGrepOutput(input: BuildGrepOutputInput): GrepOutputResult {
     })),
   };
   if (!input.summary && input.scopeMode === "symbol") {
-    readseekValue.scopes = buildScopeMetadata(input.groups, input.scopeWarnings ?? []);
+    readseekValue.scopes = buildScopeMetadata(input.groups, scopeWarnings);
   }
 
   return {

package/src/grep.ts

@@ -17,8 +17,9 @@ import { throwIfAborted } from "./runtime.js";
 import { Text } from "@earendil-works/pi-tui";
 import { formatGrepCallText, formatGrepResultText } from "./grep-render-helpers.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 const GREP_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/grep.md", import.meta.url),
@@ -313,6 +314,16 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 	let candidateUnparsedCount = 0;
 	const candidateLinePattern = /^.+(?::|-)\d+(?::|-)\s/;
 
+	const addSummaryMatch = (displayPath: string, absolutePath: string) => {
+		let group = groupsByPath.get(displayPath);
+		if (!group) {
+			group = { displayPath, absolutePath, matchCount: 0, entries: [] };
+			groupsByPath.set(displayPath, group);
+		}
+		group.matchCount++;
+		totalMatches++;
+	};
+
 	const addEntry = (displayPath: string, absolutePath: string, kind: "match" | "context", line: ReadseekLine) => {
 		let group = groupsByPath.get(displayPath);
 		if (!group) {
@@ -341,6 +352,12 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 		}
 		parsedCount++;
 		const absolute = toAbsolutePath(parsed.displayPath);
+		if (p.summary) {
+			if (parsed.kind === "match") {
+				addSummaryMatch(parsed.displayPath, absolute);
+			}
+			continue;
+		}
 		const fileLines = await getFileLines(absolute);
 		if (fileLines === undefined) continue;
 		// Bare-CR remapping: rg treats the entire bare-CR file as line 1, and the
@@ -379,6 +396,25 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 		});
 	}
 
+	if (p.summary && parsedCount === 0 && candidateUnparsedCount > 0) {
+		const passthroughDetails =
+			typeof result.details === "object" && result.details !== null
+				? (result.details as Record<string, unknown>)
+				: {};
+		return {
+			...result,
+			details: {
+				...passthroughDetails,
+				readseekValue: {
+					tool: "grep",
+					summary: true,
+					totalMatches: 0,
+					records: [],
+				},
+			},
+		};
+	}
+
 	if (parsedCount === 0 && candidateUnparsedCount > 0) {
 		const warning =
 			"[hashline grep passthrough] Unparsed grep format; returned original output.";
@@ -405,7 +441,7 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 		};
 	}
 
-	const summary = p.summary;
+	const summary = !!p.summary;
 	const effectiveLimit = typeof p.limit === "number" ? p.limit : 100;
 	const groups = [...groupsByPath.values()];
 	for (const group of groups) {
@@ -473,21 +509,15 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 }
 
 export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "read-only" as const,
-		readOnly: true,
+	const tool = registerReadseekTool(pi, {
+		policy: "read-only",
 		pythonName: "grep",
-		defaultExposure: "safe-by-default" as const,
-	};
-
-	const tool = {
+		defaultExposure: "safe-by-default",
+	}, {
 		name: "grep",
 		label: "grep",
 		description: GREP_PROMPT_METADATA.description,
 		parameters: grepSchema,
-		ptc: toolConfig,
 		promptSnippet: GREP_PROMPT_METADATA.promptSnippet,
 		promptGuidelines: options.searchGuideline
 			? [GREP_PROMPT_METADATA.promptGuidelines[0], options.searchGuideline]
@@ -523,16 +553,12 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
 			const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
-			if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending search")], width).join("\n"), 0, 0);
+			if (isPartial) return renderPendingResult("pending search", width);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
 
-			if (isError || result.isError) {
-				const firstLine = textContent.split("\n")[0] || "Error";
-				const body = expanded && textContent ? textContent : firstLine;
-				return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
-			}
+			if (isError || result.isError) return renderErrorResult(textContent, { expanded, width });
 
 			const readseekValue = (result.details as any)?.readseekValue as {
 				tool: "grep";
@@ -572,8 +598,6 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 			}
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
-	} satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-	pi.registerTool(tool);
+	});
 	return tool;
 }

package/src/hashline.ts

@@ -71,13 +71,16 @@ interface HashlineGlobalState {
 
 const HASHLINE_STATE_KEY = Symbol.for("pi-readseek.hashlineState.v1");
 
+type HashlineGlobalSlots = typeof globalThis & Record<symbol, HashlineGlobalState | undefined>;
+
 function getHashlineState(): HashlineGlobalState {
-	const globalObject = globalThis as any;
-	globalObject[HASHLINE_STATE_KEY] ??= {
+	const globalObject = globalThis as HashlineGlobalSlots;
+	const state = globalObject[HASHLINE_STATE_KEY] ?? {
 		h32Fn: null,
 		initPromise: null,
-	} satisfies HashlineGlobalState;
-	return globalObject[HASHLINE_STATE_KEY] as HashlineGlobalState;
+	};
+	globalObject[HASHLINE_STATE_KEY] = state;
+	return state;
 }
 
 export async function ensureHashInit(): Promise<void> {
@@ -123,6 +126,7 @@ export function parseLineRef(ref: string): { line: number; hash: string; content
 	const match = normalized.match(new RegExp(`^(\\d+):([0-9a-fA-F]{${HASH_LEN}})$`));
 	if (!match) throw new Error(`Invalid line reference "${ref}". Expected "LINE:HASH" (e.g. "5:abc").`);
 	const line = Number.parseInt(match[1], 10);
+	if (!Number.isSafeInteger(line)) throw new Error(`Line number must be a safe integer, got ${match[1]} in "${ref}".`);
 	if (line < 1) throw new Error(`Line number must be >= 1, got ${line} in "${ref}".`);
 	return { line, hash: match[2], content: contentAfterPipe };
 }

package/src/map-cache.ts

@@ -17,14 +17,17 @@ interface MapCacheGlobalState {
 
 const MAP_CACHE_STATE_KEY = Symbol.for("pi-readseek.mapCacheState.v1");
 
+type MapCacheGlobalSlots = typeof globalThis & Record<symbol, MapCacheGlobalState | undefined>;
+
 function getMapCacheState(): MapCacheGlobalState {
-	const globalObject = globalThis as any;
-	globalObject[MAP_CACHE_STATE_KEY] ??= {
+	const globalObject = globalThis as MapCacheGlobalSlots;
+	const state = globalObject[MAP_CACHE_STATE_KEY] ?? {
 		cache: new Map<string, CacheEntry>(),
 		inflight: new Map<string, Promise<FileMap | null>>(),
 		maxSize: MAP_CACHE_MAX_SIZE,
-	} satisfies MapCacheGlobalState;
-	return globalObject[MAP_CACHE_STATE_KEY] as MapCacheGlobalState;
+	};
+	globalObject[MAP_CACHE_STATE_KEY] = state;
+	return state;
 }
 
 function rememberInMemory(absPath: string, entry: CacheEntry): void {

package/src/read.ts

@@ -26,8 +26,9 @@ import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
 import { readseekRead } from "./readseek-client.js";
 import { Text } from "@earendil-works/pi-tui";
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 const READ_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/read.md", import.meta.url),
@@ -40,7 +41,7 @@ interface ReadParams {
 	limit?: number | string;
 	symbol?: string;
 	map?: boolean;
-	bundle?: "local";
+	bundle?: string;
 }
 
 interface ReadToolOptions {
@@ -56,6 +57,15 @@ export interface ExecuteReadOptions {
 	onSuccessfulRead?: FileAnchoredCallback;
 }
 
+function hasReadAnchors(result: AgentToolResult<any>): boolean {
+	const details = (result as { details?: unknown }).details;
+	if (!details || typeof details !== "object") return false;
+	const readseekValue = (details as { readseekValue?: unknown }).readseekValue;
+	if (!readseekValue || typeof readseekValue !== "object") return false;
+	const lines = (readseekValue as { lines?: unknown }).lines;
+	return Array.isArray(lines) && lines.length > 0;
+}
+
 export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolResult<any>> {
 	const { toolCallId, params, signal, onUpdate, cwd, onSuccessfulRead } = opts;
 	await ensureHashInit();
@@ -76,10 +86,16 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 		const message = `Invalid offset: expected a positive integer, received ${offset.value}.`;
 		return buildToolErrorResult("read", "invalid-offset", message, { path: rawParams.path });
 	}
+	const rawBundle = typeof rawParams.bundle === "string" ? rawParams.bundle.trim() : undefined;
+	const requestedMapViaBundle =
+		rawBundle === "map" ||
+		(rawBundle === "local" && rawParams.symbol === undefined && rawParams.map !== false);
 	const p = {
 		...rawParams,
 		offset: offset.value,
 		limit: limit.value,
+		map: rawParams.map === true || requestedMapViaBundle,
+		bundle: requestedMapViaBundle ? undefined : rawBundle,
 	};
 	if (rawParams.symbol !== undefined) {
 		const trimmedSymbol = typeof rawParams.symbol === "string" ? rawParams.symbol.trim() : "";
@@ -93,13 +109,17 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 	const absolutePath = resolveToCwd(rawPath, cwd);
 	const succeed = <T extends AgentToolResult<any>>(result: T): T => {
 		const isError = (result as { isError?: boolean }).isError;
-		if (!isError) {
+		if (!isError && hasReadAnchors(result)) {
 			onSuccessfulRead?.(absolutePath);
 		}
 		return result;
 	};
 
 	throwIfAborted(signal);
+	if (p.bundle !== undefined && p.bundle !== "local") {
+		const message = `Invalid bundle: expected "local", received ${JSON.stringify(p.bundle)}.`;
+		return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
+	}
 	if (p.symbol && (p.offset !== undefined || p.limit !== undefined)) {
 		const message = "Cannot combine symbol with offset/limit. Use one or the other.";
 		return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
@@ -404,16 +424,11 @@ function splitReadseekLines(text: string): string[] {
 }
 
 export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "read-only" as const,
-		readOnly: true,
+	const tool = registerReadseekTool(pi, {
+		policy: "read-only",
 		pythonName: "read",
-		defaultExposure: "safe-by-default" as const,
-	};
-
-	const tool = {
+		defaultExposure: "safe-by-default",
+	}, {
 		name: "read",
 		label: "Read",
 		description: READ_PROMPT_METADATA.description,
@@ -441,7 +456,6 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 				}),
 			),
 		}),
-		ptc: toolConfig,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			return executeRead({
 				toolCallId,
@@ -470,7 +484,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 		},
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
 			const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
-			if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending read")], width).join("\n"), 0, 0);
+			if (isPartial) return renderPendingResult("pending read", width);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
@@ -497,8 +511,6 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			if (expanded && textContent) text += "\n" + wrapReadHashlinesForWidth(textContent, width);
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
-	} satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-	pi.registerTool(tool);
+	});
 	return tool;
 }

package/src/readseek-client.ts

@@ -203,6 +203,28 @@ export function isReadseekAvailable(): boolean {
 	}
 }
 
+export interface ReadseekFailure {
+	code: "readseek-not-installed" | "readseek-execution-error";
+	message: string;
+	hint?: string;
+}
+
+/**
+ * Classify an error thrown while invoking readseek into the shared failure
+ * taxonomy: a missing binary or package (`readseek-not-installed`, with an
+ * install hint) versus any other execution error.
+ */
+export function classifyReadseekFailure(err: unknown): ReadseekFailure {
+	const message = String((err as { message?: unknown } | null)?.message || err);
+	const missing =
+		(err as { code?: unknown } | null)?.code === "ENOENT" ||
+		/Cannot find package|Cannot find module|no such file/i.test(message);
+	if (missing) {
+		return { code: "readseek-not-installed", message, hint: "Run npm install to install @jarkkojs/readseek." };
+	}
+	return { code: "readseek-execution-error", message };
+}
+
 function directoryExists(dirPath: string): boolean {
 	try {
 		return statSync(dirPath).isDirectory();
@@ -332,7 +354,7 @@ async function runReadseek(args: string[], options: RunReadseekOptions = {}): Pr
 }
 
 function requireNumber(value: unknown, field: string): number {
-	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`invalid readseek ${field}`);
+	if (typeof value !== "number" || !Number.isSafeInteger(value)) throw new Error(`invalid readseek ${field}: expected safe integer`);
 	return value;
 }
 

package/src/refs.ts

@@ -6,9 +6,10 @@ import { stat as fsStat } from "node:fs/promises";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildReadseekLineWithHash, buildToolErrorResult } from "./readseek-value.js";
 import { resolveToCwd } from "./path-utils.js";
-import { isReadseekAvailable, readseekRefs, type ReadseekReference } from "./readseek-client.js";
+import { classifyReadseekFailure, readseekRefs, type ReadseekReference } from "./readseek-client.js";
 import { buildRefsOutput, type RefsOutputFile, type RefsOutputLine } from "./refs-output.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
@@ -29,10 +30,6 @@ const REFS_PROMPT_METADATA = defineToolPromptMetadata({
   promptSnippet: "Find references to an identifier with readseek and return edit-ready anchors",
 });
 
-export function isRefsAvailable(): boolean {
-  return isReadseekAvailable();
-}
-
 interface RefsToolOptions {
   onFileAnchored?: FileAnchoredCallback;
 }
@@ -127,28 +124,17 @@ export async function executeRefs(opts: ExecuteRefsOptions): Promise<any> {
       details: { readseekValue: builtOutput.readseekValue },
     };
   } catch (err: any) {
-    const message = String(err?.message || err);
-    const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
-    return buildToolErrorResult(
-      "refs",
-      missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
-      message,
-      missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
-    );
+    const failure = classifyReadseekFailure(err);
+    return buildToolErrorResult("refs", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
   }
 }
 
 export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}) {
-  const toolConfig = {
-    callable: true,
-    enabled: true,
-    policy: "read-only" as const,
-    readOnly: true,
+  const tool = registerReadseekTool(pi, {
+    policy: "read-only",
     pythonName: "refs",
-    defaultExposure: "opt-in" as const,
-  };
-
-  const tool = {
+    defaultExposure: "opt-in",
+  }, {
     name: "refs",
     label: "References",
     description: REFS_PROMPT_METADATA.description,
@@ -165,7 +151,6 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
       others: Type.Optional(Type.Boolean({ description: "In a Git repository, search untracked files" })),
       ignored: Type.Optional(Type.Boolean({ description: "With others=true, include ignored untracked files" })),
     }),
-    ptc: toolConfig,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       return executeRefs({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
     },
@@ -186,8 +171,6 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
         unitPlural: "references",
       });
     },
-  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-  pi.registerTool(tool);
+  });
   return tool;
 }

package/src/register-tool.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type ReadseekToolPolicy = "read-only" | "mutating";
+
+export type ReadseekToolExposure = "safe-by-default" | "opt-in" | "not-safe-by-default";
+
+/**
+ * Per-tool fields of the pi tool config (`ptc`) that genuinely differ between
+ * readseek tools. The remaining fields are constant or derived.
+ */
+export interface ReadseekToolConfig {
+  policy: ReadseekToolPolicy;
+  pythonName: string;
+  defaultExposure: ReadseekToolExposure;
+}
+
+export interface ReadseekToolPtc extends ReadseekToolConfig {
+  callable: true;
+  enabled: true;
+  readOnly: boolean;
+}
+
+type ToolSpec = Parameters<ExtensionAPI["registerTool"]>[0];
+
+/**
+ * Attach the standard `ptc` envelope to a tool definition and register it.
+ *
+ * `callable` and `enabled` are always true and `readOnly` is derived from
+ * `policy`, so callers supply only the fields that vary between tools.
+ */
+export function registerReadseekTool<T extends ToolSpec>(
+  pi: ExtensionAPI,
+  config: ReadseekToolConfig,
+  tool: T,
+): T & { ptc: ReadseekToolPtc } {
+  const ptc: ReadseekToolPtc = {
+    callable: true,
+    enabled: true,
+    policy: config.policy,
+    readOnly: config.policy === "read-only",
+    pythonName: config.pythonName,
+    defaultExposure: config.defaultExposure,
+  };
+  const registered = { ...tool, ptc };
+  pi.registerTool(registered);
+  return registered;
+}

package/src/sg.ts

@@ -6,9 +6,10 @@ import { stat as fsStat } from "node:fs/promises";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildReadseekLineWithHash, buildToolErrorResult, type ReadseekLine } from "./readseek-value.js";
 import { resolveToCwd } from "./path-utils.js";
-import { isReadseekAvailable, readseekSearch, type ReadseekHashline, type ReadseekSearchFileOutput } from "./readseek-client.js";
+import { classifyReadseekFailure, isReadseekAvailable, readseekSearch, type ReadseekHashline, type ReadseekSearchFileOutput } from "./readseek-client.js";
 import { buildSgOutput } from "./sg-output.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
@@ -193,28 +194,17 @@ export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
       },
     };
   } catch (err: any) {
-    const message = String(err?.message || err);
-    const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
-    return buildToolErrorResult(
-      "search",
-      missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
-      message,
-      missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
-    );
+    const failure = classifyReadseekFailure(err);
+    return buildToolErrorResult("search", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
   }
 }
 
 export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
-  const toolConfig = {
-    callable: true,
-    enabled: true,
-    policy: "read-only" as const,
-    readOnly: true,
+  const tool = registerReadseekTool(pi, {
+    policy: "read-only",
     pythonName: "search",
-    defaultExposure: "opt-in" as const,
-  };
-
-  const tool = {
+    defaultExposure: "opt-in",
+  }, {
     name: "search",
     label: "Structural Search",
     description: SG_PROMPT_METADATA.description,
@@ -228,7 +218,6 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
       others: Type.Optional(Type.Boolean({ description: "In a Git repository, search untracked files" })),
       ignored: Type.Optional(Type.Boolean({ description: "With others=true, include ignored untracked files" })),
     }),
-    ptc: toolConfig,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       return executeSg({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
     },
@@ -249,8 +238,6 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
         unitPlural: "matches",
       });
     },
-  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-  pi.registerTool(tool);
+  });
   return tool;
 }

package/src/tui-render-utils.ts

@@ -156,6 +156,27 @@ export function wrapReadHashlinesForWidth(text: string, width: number | undefine
   return output.join("\n");
 }
 
+/**
+ * Render the `isPartial` placeholder line shared by every tool's `renderResult`.
+ */
+export function renderPendingResult(pendingLabel: string, width: number | undefined): Text {
+  return new Text(clampLinesToWidth([summaryLine(pendingLabel)], width).join("\n"), 0, 0);
+}
+
+/**
+ * Render a tool result error: the first line of `textContent`, or its full body
+ * when expanded, prefixed and clamped to width. Tools pass their own `fallback`
+ * for the empty-content case.
+ */
+export function renderErrorResult(
+  textContent: string,
+  options: { expanded: boolean; width: number | undefined; fallback?: string },
+): Text {
+  const firstLine = textContent.split("\n")[0] || (options.fallback ?? "Error");
+  const body = options.expanded && textContent ? textContent : firstLine;
+  return new Text(clampLinesToWidth(summaryLine(body).split("\n"), options.width).join("\n"), 0, 0);
+}
+
 export interface AnchoredFilesLabels {
   pendingLabel: string;
   emptyLabel: string;
@@ -178,15 +199,11 @@ export function renderAnchoredFilesResult(
 ): Text {
   const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
-  if (isPartial) return new Text(clampLinesToWidth([summaryLine(labels.pendingLabel)], width).join("\n"), 0, 0);
+  if (isPartial) return renderPendingResult(labels.pendingLabel, width);
 
   const content = result.content?.[0];
   const textContent = content?.type === "text" ? content.text : "";
-  if (isError || result.isError) {
-    const firstLine = textContent.split("\n")[0] || "Error";
-    const body = expanded && textContent ? textContent : firstLine;
-    return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
-  }
+  if (isError || result.isError) return renderErrorResult(textContent, { expanded, width });
 
   const readseekValue = (result.details as any)?.readseekValue as
     | { files: Array<{ path: string; lines: any[] }> }

package/src/write.ts

@@ -14,9 +14,10 @@ import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildPendingWritePreviewData, buildWritePreviewKey, resolvePendingDiffPreview, type PendingDiffPreviewResult } from "./pending-diff-preview.js";
 import { generateCompactOrFullDiff, normalizeToLF, hasBareCarriageReturn } from "./edit-diff.js";
 import { buildDiffData, type DiffData } from "./diff-data.js";
-import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, linkToolPath, renderToolLabel, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, linkToolPath, renderErrorResult, renderToolLabel, summaryLine } from "./tui-render-utils.js";
 import { DiffPreviewComponent } from "./tui-diff-component.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 const WRITE_PENDING_PREVIEW_STATE_KEY = "hashline-write-pending-preview";
 
@@ -169,6 +170,30 @@ function mapFsWriteError(err: any, path: string): MappedFsError {
   };
 }
 
+function buildWriteFsErrorResult(err: any, absolutePath: string) {
+  const mapped = mapFsWriteError(err, absolutePath);
+  return {
+    content: [{ type: "text" as const, text: mapped.message }],
+    isError: true,
+    details: {
+      readseekValue: {
+        tool: "write" as const,
+        path: absolutePath,
+        lines: [] as ReadseekLine[],
+        warnings: [] as ReadseekWarning[],
+        ok: false,
+        error: buildReadseekError(
+          mapped.code,
+          mapped.message,
+          undefined,
+          mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
+        ),
+      },
+      warnings: [] as string[],
+    },
+  };
+}
+
 export async function executeWrite(opts: {
   path: string;
   content: string;
@@ -301,21 +326,16 @@ export async function executeWrite(opts: {
 }
 
 export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions = {}) {
-  const toolConfig = {
-    callable: true,
-    enabled: true,
-    policy: "mutating" as const,
-    readOnly: false,
+  const tool = registerReadseekTool(pi, {
+    policy: "mutating",
     pythonName: "write",
-    defaultExposure: "not-safe-by-default" as const,
-  };
-  const tool = {
+    defaultExposure: "not-safe-by-default",
+  }, {
     name: "write",
     label: "write",
     description: WRITE_PROMPT_METADATA.description,
     promptSnippet: WRITE_PROMPT_METADATA.promptSnippet,
     promptGuidelines: WRITE_PROMPT_METADATA.promptGuidelines,
-    ptc: toolConfig,
     parameters: Type.Object({
       path: Type.String({ description: "File path" }),
       content: Type.String({ description: "File content" }),
@@ -325,112 +345,72 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       const cwd = ctx?.cwd ?? process.cwd();
       const absolutePath = resolveToCwd(params.path, cwd);
       try {
-      return await withFileMutationQueue(absolutePath, async () => {
-      let result: WriteResult;
-      try {
-        result = await executeWrite({
-          path: absolutePath,
-          content: params.content,
-          map: params.map,
-          cwd,
-        });
-      } catch (err: any) {
-        const mapped = mapFsWriteError(err, absolutePath);
-        return {
-          content: [{ type: "text" as const, text: mapped.message }],
-          isError: true,
-          details: {
-            readseekValue: {
-              tool: "write" as const,
+        return await withFileMutationQueue(absolutePath, async () => {
+          let result: WriteResult;
+          try {
+            result = await executeWrite({
               path: absolutePath,
-              lines: [] as ReadseekLine[],
-              warnings: [] as ReadseekWarning[],
-              ok: false,
-              error: buildReadseekError(
-                mapped.code,
-                mapped.message,
-                undefined,
-                mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
-              ),
-            },
-            warnings: [] as string[],
-          },
-        };
-      }
+              content: params.content,
+              map: params.map,
+              cwd,
+            });
+          } catch (err: any) {
+            return buildWriteFsErrorResult(err, absolutePath);
+          }
 
-      if (result.readseekValue.lines.length > 0) {
-        options.onFileAnchored?.(absolutePath);
-      }
+          if (result.readseekValue.lines.length > 0) {
+            options.onFileAnchored?.(absolutePath);
+          }
 
-      // Lift binary-content signal into a fatal readseekValue.error envelope so
-      // downstream consumers get the same taxonomy shape as every other tool.
-      // The existing ReadseekWarning entry is preserved on readseekValue.warnings for
-      // backward compatibility (see AC 12 — warnings namespace alignment).
-      const binaryWarning = result.readseekValue.warnings.find((w) => w.code === "binary-content");
-      if (binaryWarning) {
-        return {
-          content: [{ type: "text" as const, text: result.text }],
-          isError: true,
-          details: {
-            readseekValue: {
-              ...result.readseekValue,
-              ok: false,
-              error: buildReadseekError("binary-content", binaryWarning.message),
-            },
-            warnings: result.warnings,
-          },
-        };
-      }
+          // Lift binary-content signal into a fatal readseekValue.error envelope so
+          // downstream consumers get the same taxonomy shape as every other tool.
+          // The existing ReadseekWarning entry is preserved on readseekValue.warnings for
+          // backward compatibility (see AC 12 — warnings namespace alignment).
+          const binaryWarning = result.readseekValue.warnings.find((w) => w.code === "binary-content");
+          if (binaryWarning) {
+            return {
+              content: [{ type: "text" as const, text: result.text }],
+              isError: true,
+              details: {
+                readseekValue: {
+                  ...result.readseekValue,
+                  ok: false,
+                  error: buildReadseekError("binary-content", binaryWarning.message),
+                },
+                warnings: result.warnings,
+              },
+            };
+          }
 
-      const bareCrWarning = result.readseekValue.warnings.find((w) => w.code === "bare-cr");
-      if (bareCrWarning) {
-        return {
-          content: [{ type: "text" as const, text: result.text }],
-          isError: true,
-          details: {
-            readseekValue: {
-              ...result.readseekValue,
-              ok: false,
-              error: buildReadseekError("bare-cr", bareCrWarning.message),
-            },
-            warnings: result.warnings,
-          },
-        };
-      }
+          const bareCrWarning = result.readseekValue.warnings.find((w) => w.code === "bare-cr");
+          if (bareCrWarning) {
+            return {
+              content: [{ type: "text" as const, text: result.text }],
+              isError: true,
+              details: {
+                readseekValue: {
+                  ...result.readseekValue,
+                  ok: false,
+                  error: buildReadseekError("bare-cr", bareCrWarning.message),
+                },
+                warnings: result.warnings,
+              },
+            };
+          }
 
-      return {
-        content: [{ type: "text" as const, text: result.text }],
-        details: {
-          ...(result.diff !== undefined ? { diff: result.diff } : {}),
-          ...(result.diffData !== undefined ? { diffData: result.diffData } : {}),
-          ...(result.writeState ? { writeState: result.writeState } : {}),
-          readseekValue: result.readseekValue,
-          warnings: result.warnings,
-        },
-      };
-      });
-      } catch (err: any) {
-        const mapped = mapFsWriteError(err, absolutePath);
-        return {
-          content: [{ type: "text" as const, text: mapped.message }],
-          isError: true,
-          details: {
-            readseekValue: {
-              tool: "write" as const,
-              path: absolutePath,
-              lines: [] as ReadseekLine[],
-              warnings: [] as ReadseekWarning[],
-              ok: false,
-              error: buildReadseekError(
-                mapped.code,
-                mapped.message,
-                undefined,
-                mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
-              ),
+          return {
+            content: [{ type: "text" as const, text: result.text }],
+            details: {
+              ...(result.diff !== undefined ? { diff: result.diff } : {}),
+              ...(result.diffData !== undefined ? { diffData: result.diffData } : {}),
+              ...(result.writeState ? { writeState: result.writeState } : {}),
+              readseekValue: result.readseekValue,
+              warnings: result.warnings,
             },
-            warnings: [] as string[],
-          },
-        };
+          };
+        });
+      } catch (err: any) {
+        return buildWriteFsErrorResult(err, absolutePath);
       }
     },
     renderCall(args: any, theme: any, context: any = {}) {
@@ -478,9 +458,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       const details = result.details ?? {};
       const output = result.content?.[0]?.type === "text" ? result.content[0].text : "";
       if (result.isError || details.readseekValue?.ok === false) {
-        const firstLine = output.split("\n")[0] || "write failed";
-        const body = expanded && output ? output : firstLine;
-        return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
+        return renderErrorResult(output, { expanded, width, fallback: "write failed" });
       }
       const diffData = details.diffData;
       const state = details.writeState === "overwritten" ? "overwritten" : "created";
@@ -510,7 +488,6 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       }
       return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
     },
-  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-  pi.registerTool(tool);
+  });
   return tool;
 }