pi-readseek 0.6.13 → 0.7.1

package/README.md

@@ -5,6 +5,10 @@ editing, anchored grep, structural maps, symbol navigation, and structural searc
 Pi's built-in tools remain unchanged by default. `replacedTools` can register the
 corresponding ReadSeek implementations under built-in names.
 
+When the ReadSeek binary is available, the extension adds model guidance that
+prefers its anchored read, edit, write, rename, and syntax-check workflow while
+leaving Pi's built-ins available as fallbacks.
+
 ## Installation
 
 ```sh
@@ -18,15 +22,19 @@ binary automatically on supported platforms.
 
 - `readSeek_read`: reads text with `LINE:HASH` anchors; when image modes are
   enabled, images and PDFs can be returned as base64 or analyzed locally.
+  PDF reads select one page by default and accept an explicit page.
 - `readSeek_edit`: edits existing text files using fresh `LINE:HASH` anchors.
 - `readSeek_grep`: searches text and returns edit-ready anchors.
 - `readSeek_search`: searches code by structural AST pattern.
 - `readSeek_refs`: finds identifier references with enclosing symbols.
-- `readSeek_rename`: plans or applies binding-aware renames; workspace matches are
-  name-based where binding support is unavailable.
+- `readSeek_rename`: applies a binding-aware verified rename by default;
+  `apply: false` returns a dry-run plan. Workspace matches are name-based where
+  binding support is unavailable.
 - `readSeek_hover`: identifies the cursor token and enclosing symbol.
 - `readSeek_def`: finds structural symbol definitions.
 - `readSeek_check`: checks a source file for parser errors and missing syntax.
+- `readSeek_view`: creates or reuses a PDF index, returns its overview, or
+  narrows it by page, node, kind, or depth.
 - `readSeek_write`: creates or overwrites whole files and returns anchors.
 
 ## Settings

package/index.ts

@@ -9,6 +9,7 @@ import { registerHoverTool } from "./src/hover.js";
 import { registerWriteTool } from "./src/write.js";
 import { registerDefTool } from "./src/def.js";
 import { registerCheckTool } from "./src/check.js";
+import { registerViewTool } from "./src/view.js";
 import { SessionAnchors } from "./src/session-anchors.js";
 import { readSeekBinaryAvailability } from "./src/readseek-client.js";
 import { resolveReadSeekJsonSettings, type ReadSeekSettingsWarning } from "./src/readseek-settings.js";
@@ -39,12 +40,23 @@ const READSEEK_TOOL_ENTRIES: ReadonlyArray<{ builtIn: ReplacedBuiltIn | null; re
 	{ builtIn: "write", readSeekName: "readSeek_write" },
 	{ builtIn: null, readSeekName: "readSeek_def" },
 	{ builtIn: null, readSeekName: "readSeek_check" },
+	{ builtIn: null, readSeekName: "readSeek_view" },
 ];
 
 function formatSettingsWarning(warning: ReadSeekSettingsWarning): string {
 	return `${warning.message} (${warning.source})`;
 }
 
+function editingPolicy(readName: string, editName: string, writeName: string): string {
+	return [
+		"ReadSeek editing policy:",
+		`- Prefer ${readName} when preparing to edit existing text; its LINE:HASH anchors are required by ${editName}.`,
+		`- Prefer ${editName} for existing text files, ${writeName} for whole-file creation or replacement, and readSeek_rename for symbol renames.`,
+		"- Do not use Pi's built-in edit or write when the corresponding ReadSeek tool is available.",
+		"- Use readSeek_check after source edits for a quick syntax check.",
+	].join("\n");
+}
+
 export default function piReadSeekExtension(pi: ExtensionAPI): void {
 	const sessionAnchors = new SessionAnchors();
 	const markAnchored = (absolutePath: string) => sessionAnchors.markAnchored(absolutePath);
@@ -87,8 +99,14 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 	registerHoverTool(pi);
 	registerDefTool(pi, { onFileAnchored: markAnchored });
 	registerCheckTool(pi);
+	registerViewTool(pi);
 	registerWriteTool(pi, { onFileAnchored: markAnchored, name: writeName });
 
+	pi.on("before_agent_start", (event) => {
+		if (!binaryAvailable) return;
+		return { systemPrompt: `${event.systemPrompt}\n\n${editingPolicy(readName, editName, writeName)}` };
+	});
+
 	pi.on("session_start", (_event, ctx) => {
 		sessionAnchors.clear();
 		const { warnings } = resolveReadSeekJsonSettings();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.6.13",
+  "version": "0.7.1",
   "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.6.13",
+    "@jarkkojs/readseek": "^0.7.1",
     "diff": "^8.0.3",
     "xxhash-wasm": "^1.1.0"
   },

package/prompts/read.md

@@ -15,8 +15,9 @@ Read anchored text by range, map, or symbol, and process images or PDFs with an
 - `symbol` — `Name`, `Class.method`, or `Name@<line>`; incompatible with `offset` / `limit`.
 - `bundle` — only `"local"`; requires `symbol` and excludes `map`.
 - `image` — an exposed image/PDF mode; unavailable when `imageMode` is `"off"`.
+- `page` — one-based PDF page; defaults to page 1 and cannot be combined with `offset` / `limit`.
 
-Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}. Omitting `image` skips images and PDFs; when `imageMode` is `"off"`, visual files are always skipped.
+Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}. PDF reads return one page by default. Omitting `image` skips images and PDFs; when `imageMode` is `"off"`, visual files are always skipped.
 
 Truncated full-file reads append a map when available. Use its ranges for follow-up reads.
 

package/prompts/view.md

@@ -0,0 +1,14 @@
+View the structure or selected content of an indexed PDF. Start with the default overview, then narrow by page or node instead of reading the whole document.
+
+## Parameters
+
+- `path` — PDF document to view.
+- `node` — optional node ID to use as the view root.
+- `page` — optional one-based source page.
+- `kind` — optional node kind filter.
+- `depth` — optional maximum depth below selected roots.
+- `outline` — return outline nodes only.
+
+## Output
+
+Returns a bounded text projection with stable node IDs and source page references.

package/src/read.ts

@@ -32,11 +32,11 @@ import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult,
 import type { FileAnchoredCallback } from "./tool-types.js";
 import { filePathParam, mapParam, optionalIntOrString, registerReadSeekTool } from "./register-tool.js";
 
-
 interface ReadParams {
 	path: string;
 	offset?: number | string;
 	limit?: number | string;
+	page?: number | string;
 	symbol?: string;
 	map?: boolean;
 	bundle?: string;
@@ -101,6 +101,12 @@ function formatPdfAnalysis(pdf: ReadSeekPdfOutput): string {
 	return sections.filter(Boolean).join("\n\n");
 }
 
+function truncateDocumentText(text: string): string {
+	const truncation = truncateHead(text, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+	if (!truncation.truncated) return truncation.content;
+	return `${truncation.content}\n[… document output truncated; use readSeek_view with page or node selectors]`;
+}
+
 function skippedVisualFile(path: string): AgentToolResult<any> {
 	return {
 		content: [{ type: "text", text: `[Skipped image/PDF: ${path}; no image mode selected]` }],
@@ -128,6 +134,15 @@ 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 page = coerceObviousBase10Int(rawParams.page, "page");
+	if (!page.ok) {
+		return buildToolErrorResult("read", "invalid-page", page.message, { path: rawParams.path });
+	}
+	if (page.value !== undefined && page.value < 1) {
+		const message = `Invalid page: expected a positive integer, received ${page.value}.`;
+		return buildToolErrorResult("read", "invalid-page", message, { path: rawParams.path });
+	}
 	const rawBundle = typeof rawParams.bundle === "string" ? rawParams.bundle.trim() : undefined;
 	const requestedMapViaBundle =
 		rawBundle === "map" ||
@@ -136,6 +151,7 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 		...rawParams,
 		offset: offset.value,
 		limit: limit.value,
+		page: page.value,
 		map: rawParams.map === true || requestedMapViaBundle,
 		bundle: requestedMapViaBundle ? undefined : rawBundle,
 	};
@@ -207,6 +223,15 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 			});
 		}
 		if (detection.kind === "image" || detection.type === "application/pdf") {
+			if (p.offset !== undefined || p.limit !== undefined) {
+				const message = "Cannot combine offset/limit with image or PDF reads.";
+				return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
+			}
+			if (detection.kind !== "pdf" && p.page !== undefined) {
+				const message = "The page parameter applies to PDFs only.";
+				return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
+			}
+			const pdfPage = detection.kind === "pdf" ? (p.page ?? 1) : undefined;
 			const imageMode = resolveReadSeekImageMode();
 			if (imageMode === "off" || p.image === undefined) {
 				return skippedVisualFile(rawParams.path);
@@ -219,8 +244,8 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 			if (p.image === "none") {
 				try {
 					if (detection.kind === "pdf") {
-						const pdf = await readSeekPdf(absolutePath, p.image, { signal });
-						const content: AgentToolResult<any>["content"] = [{ type: "text", text: pdf.markdown }];
+						const pdf = await readSeekPdf(absolutePath, p.image, { page: pdfPage, signal });
+						const content: AgentToolResult<any>["content"] = [{ type: "text", text: truncateDocumentText(pdf.markdown) }];
 						for (const image of pdf.images) {
 							if (image.encoding !== "base64" || image.data === undefined) continue;
 							content.push({ type: "text", text: `[PDF page ${image.page} image]` });
@@ -243,9 +268,9 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 
 			try {
 				if (detection.kind === "pdf") {
-					const pdf = await readSeekPdf(absolutePath, p.image, { signal });
+					const pdf = await readSeekPdf(absolutePath, p.image, { page: pdfPage, signal });
 					return succeed({
-						content: [{ type: "text" as const, text: formatPdfAnalysis(pdf) }],
+						content: [{ type: "text" as const, text: truncateDocumentText(formatPdfAnalysis(pdf)) }],
 						details: {},
 					});
 				}
@@ -269,6 +294,10 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 			});
 		}
 	}
+	if (p.page !== undefined) {
+		const message = "The page parameter applies to PDFs only.";
+		return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
+	}
 	throwIfAborted(signal);
 	const rawText = rawBuffer.toString("utf-8");
 	const normalized = normalizeToLF(stripBom(rawText).text);
@@ -548,6 +577,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			path: filePathParam(),
 			offset: optionalIntOrString("Start line (1-indexed)"),
 			limit: optionalIntOrString("Maximum lines to return"),
+			page: optionalIntOrString("One-based PDF page; defaults to 1"),
 			symbol: Type.Optional(Type.String({ description: "Symbol name to read" })),
 			map: mapParam(),
 			bundle: Type.Optional(

package/src/readseek-client.ts

@@ -481,6 +481,25 @@ async function runReadSeek(args: string[], options: RunReadSeekOptions = {}): Pr
 	return JSON.parse(stdout) as unknown;
 }
 
+export interface ReadSeekViewOptions {
+	node?: string;
+	page?: number;
+	kind?: string;
+	depth?: number;
+	outline?: boolean;
+	signal?: AbortSignal;
+}
+
+export async function readSeekView(filePath: string, options: ReadSeekViewOptions = {}): Promise<string> {
+	const args = ["view", filePath];
+	if (options.node !== undefined) args.push("--node", options.node);
+	if (options.page !== undefined) args.push("--page", String(options.page));
+	if (options.kind !== undefined) args.push("--kind", options.kind);
+	if (options.depth !== undefined) args.push("--depth", String(options.depth));
+	if (options.outline) args.push("--outline");
+	return runReadSeekRaw(args, { signal: options.signal });
+}
+
 let visionInvocationTail = Promise.resolve();
 
 /**
@@ -951,10 +970,12 @@ function parsePdfOutput(value: unknown): ReadSeekPdfOutput {
 export async function readSeekPdf(
 	filePath: string,
 	mode: "none" | ReadSeekImageMode,
-	options: { signal?: AbortSignal } = {},
+	options: { page?: number; signal?: AbortSignal } = {},
 ): Promise<ReadSeekPdfOutput> {
 	const run = mode === "none" ? runReadSeek : runReadSeekVision;
-	return parsePdfOutput(await run(["read", "--image", mode, filePath], { signal: options.signal }));
+	const args = ["read", "--image", mode, filePath];
+	if (options.page !== undefined) args.push("--page", String(options.page));
+	return parsePdfOutput(await run(args, { signal: options.signal }));
 }
 
 // --- Rename ---

package/src/view.ts

@@ -0,0 +1,158 @@
+import type { ExtensionAPI, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+
+import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
+import { resolveToCwd } from "./path-utils.js";
+import { classifyReadSeekFailure, readSeekView } from "./readseek-client.js";
+import { buildToolErrorResult } from "./readseek-value.js";
+import { filePathParam, optionalIntOrString, registerReadSeekTool } from "./register-tool.js";
+import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
+import {
+  clampLineToWidth,
+  clampLinesToWidth,
+  linkToolPath,
+  renderErrorResult,
+  renderPendingResult,
+  resolveRenderResultContext,
+  summaryLine,
+} from "./tui-render-utils.js";
+
+const NODE_KINDS = [
+  "artifact",
+  "footer",
+  "header",
+  "heading",
+  "marginal_label",
+  "page",
+  "page_number",
+  "paragraph",
+  "section",
+  "structural_section",
+] as const;
+
+const VIEW_PROMPT_METADATA = defineToolPromptMetadata({
+  promptUrl: new URL("../prompts/view.md", import.meta.url),
+  promptSnippet: "View the structure or selected content of an indexed PDF",
+});
+
+interface ViewParams {
+  path: string;
+  node?: string;
+  page?: number | string;
+  kind?: (typeof NODE_KINDS)[number];
+  depth?: number | string;
+  outline?: boolean;
+}
+
+export async function executeView(opts: {
+  params: unknown;
+  signal: AbortSignal | undefined;
+  cwd: string;
+}): Promise<any> {
+  const { params, signal, cwd } = opts;
+  const input = params as ViewParams;
+  const page = coerceObviousBase10Int(input.page, "page");
+  if (!page.ok || (page.value !== undefined && page.value < 1)) {
+    const message = page.ok
+      ? `Invalid page: expected a positive integer, received ${page.value}.`
+      : page.message;
+    return buildToolErrorResult("view", "invalid-page", message, { path: input.path });
+  }
+  const depth = coerceObviousBase10Int(input.depth, "depth");
+  if (!depth.ok || (depth.value !== undefined && depth.value < 0)) {
+    const message = depth.ok
+      ? `Invalid depth: expected a non-negative integer, received ${depth.value}.`
+      : depth.message;
+    return buildToolErrorResult("view", "invalid-depth", message, { path: input.path });
+  }
+  const node = input.node?.trim();
+  if (input.node !== undefined && !node) {
+    return buildToolErrorResult("view", "invalid-node", "Invalid node: expected a non-empty ID.", {
+      path: input.path,
+    });
+  }
+
+  const filePath = resolveToCwd(input.path, cwd);
+  try {
+    const output = await readSeekView(filePath, {
+      node,
+      page: page.value,
+      kind: input.kind,
+      depth: depth.value,
+      outline: input.outline,
+      signal,
+    });
+    const truncation = truncateHead(output, {
+      maxLines: DEFAULT_MAX_LINES,
+      maxBytes: DEFAULT_MAX_BYTES,
+    });
+    const notice = truncation.truncated
+      ? "\n[… document view truncated; narrow it with page, node, kind, or depth]"
+      : "";
+    return {
+      content: [{ type: "text", text: `${truncation.content}${notice}` }],
+      details: {
+        readSeekValue: {
+          tool: "view",
+          path: filePath,
+          truncated: truncation.truncated,
+        },
+      },
+    };
+  } catch (error) {
+    const failure = classifyReadSeekFailure(error);
+    return buildToolErrorResult("view", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
+  }
+}
+
+export function registerViewTool(pi: ExtensionAPI) {
+  return registerReadSeekTool(pi, {
+    name: "readSeek_view",
+    label: "View",
+    description: VIEW_PROMPT_METADATA.description,
+    promptSnippet: VIEW_PROMPT_METADATA.promptSnippet,
+    promptGuidelines: VIEW_PROMPT_METADATA.promptGuidelines,
+    parameters: Type.Object({
+      path: filePathParam(),
+      node: Type.Optional(Type.String({ description: "Node ID to use as the view root" })),
+      page: optionalIntOrString("One-based source page"),
+      kind: Type.Optional(Type.Union(NODE_KINDS.map((kind) => Type.Literal(kind)), {
+        description: "Node kind filter",
+      })),
+      depth: optionalIntOrString("Maximum depth below the selected roots"),
+      outline: Type.Optional(Type.Boolean({ description: "Return outline nodes only" })),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      return executeView({ params, signal, cwd: ctx.cwd });
+    },
+    renderCall(args: any, theme: any, ...rest: any[]) {
+      const context = rest[0] ?? {};
+      const cwd = context.cwd ?? process.cwd();
+      const displayPath = typeof args?.path === "string" ? args.path : "?";
+      const text = `${theme.fg("toolTitle", theme.bold("view"))} ${linkToolPath(theme.fg("accent", displayPath), displayPath, cwd)}`;
+      return new Text(clampLineToWidth(text, context.width), 0, 0);
+    },
+    renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
+      const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
+      if (isPartial) return renderPendingResult("pending view", width, theme);
+      const textContent = result.content?.[0]?.type === "text" ? result.content[0].text : "";
+      if (isError || result.isError) {
+        return renderErrorResult(textContent, { expanded, width, fallback: "view failed", theme });
+      }
+      const lines = textContent.split("\n").filter(Boolean).length;
+      let text = summaryLine(`loaded ${lines} document ${lines === 1 ? "line" : "lines"}`, {
+        hidden: !!textContent && !expanded,
+        theme,
+        style: "success",
+      });
+      if (expanded && textContent) text += `\n${textContent}`;
+      return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
+    },
+  });
+}