pi-readseek 0.4.13 → 0.4.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.4.13",
+  "version": "0.4.14",
   "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.4.16",
+    "@jarkkojs/readseek": "^0.4.19",
     "diff": "^8.0.3",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.4",

package/src/read.ts

@@ -15,7 +15,6 @@ import { normalizeToLF, stripBom, hasBareCarriageReturn } from "./edit-diff.js";
 import { ensureHashInit, escapeControlCharsForDisplay } from "./hashline.js";
 import { buildReadSeekWarning, buildToolErrorResult, renderReadSeekLines, type ReadSeekLine, type ReadSeekWarning } from "./readseek-value.js";
 import { looksLikeBinary } from "./binary-detect.js";
-import { isSupportedImageBuffer } from "./image-detect.js";
 import { resolveToCwd } from "./path-utils.js";
 import { throwIfAborted } from "./runtime.js";
 import { getOrGenerateMap } from "./file-map.js";
@@ -26,7 +25,7 @@ import { buildReadOutput } from "./read-output.js";
 
 import { buildLocalBundle } from "./read-local-bundle.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
-import { readseekRead } from "./readseek-client.js";
+import { readseekRead, readseekDetect, type ReadSeekDetection } from "./readseek-client.js";
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
@@ -34,7 +33,7 @@ import { 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",
+	promptSnippet: "Read text files or images; text reads include hashline anchors and optional maps/symbol lookup, image reads include the attachment plus OCR text",
 });
 
 interface ReadParams {
@@ -138,15 +137,8 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 		const message = "Cannot combine map with symbol. Use one or the other.";
 		return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
 	}
-	// Delegate images to the built-in read tool
 	throwIfAborted(signal);
 	const ext = rawPath.split(".").pop()?.toLowerCase() ?? "";
-	if (["jpg", "jpeg", "png", "gif", "webp"].includes(ext)) {
-		const builtinRead = createReadTool(cwd);
-		return succeed(await builtinRead.execute(toolCallId, p, signal, onUpdate));
-	}
-
-	throwIfAborted(signal);
 	let rawBuffer: Buffer;
 	try {
 		rawBuffer = await fsReadFile(absolutePath);
@@ -168,11 +160,31 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 		return buildToolErrorResult("read", "fs-error", message, { path: rawParams.path, details: { fsCode: code, fsMessage: err?.message } });
 	}
 
-	if (isSupportedImageBuffer(rawBuffer)) {
-		const builtinRead = createReadTool(cwd);
-		return succeed(await builtinRead.execute(toolCallId, p, signal, onUpdate));
-	}
 	const hasBinaryContent = looksLikeBinary(rawBuffer);
+	if (hasBinaryContent) {
+		// Images are always binary; classify and OCR in a single readseek detect call.
+		let detection: ReadSeekDetection | undefined;
+		try {
+			detection = await readseekDetect(absolutePath, { ocr: true, signal });
+		} catch {
+			// detect unavailable — fall through to binary-as-text handling below
+		}
+		if (detection?.image) {
+			const builtinRead = createReadTool(cwd);
+			const builtinResult = await builtinRead.execute(toolCallId, p, signal, onUpdate);
+			const ocrText = detection.ocr?.text?.trim();
+			if (ocrText) {
+				return succeed({
+					...builtinResult,
+					content: [
+						...(builtinResult.content ?? []),
+						{ type: "text" as const, text: `OCR text extracted from image:\n${ocrText}` },
+					],
+				});
+			}
+			return succeed(builtinResult);
+		}
+	}
 	throwIfAborted(signal);
 	const rawText = rawBuffer.toString("utf-8");
 	const normalized = normalizeToLF(stripBom(rawText).text);

package/src/readseek-client.ts

@@ -108,6 +108,35 @@ export interface ReadSeekCheckOutput {
 	diagnostics: ReadSeekDiagnostic[];
 }
 
+export interface ReadSeekImageInfo {
+	format: string;
+	width: number;
+	height: number;
+	animated: boolean;
+}
+
+export interface ReadSeekOcrLine {
+	text: string;
+	bbox: [number, number, number, number];
+}
+
+export interface ReadSeekOcrText {
+	text: string;
+	lines: ReadSeekOcrLine[];
+}
+
+export interface ReadSeekDetection {
+	file: string;
+	language: string;
+	engine: string | null;
+	supported: boolean;
+	binary: boolean;
+	mime: string | null;
+	syntax: string | null;
+	image: ReadSeekImageInfo | null;
+	ocr?: ReadSeekOcrText;
+}
+
 interface ReadSeekSearchOptions {
 	language?: string;
 	cached?: boolean;
@@ -363,6 +392,11 @@ function requireString(value: unknown, field: string): string {
 	return value;
 }
 
+function requireBoolean(value: unknown, field: string): boolean {
+	if (typeof value !== "boolean") throw new Error(`invalid readseek ${field}: expected boolean`);
+	return value;
+}
+
 function parseReadOutput(value: unknown): ReadSeekReadOutput {
 	if (!value || typeof value !== "object") throw new Error("invalid readseek read output");
 	const output = value as Record<string, unknown>;
@@ -520,6 +554,11 @@ function optionalString(value: unknown, field: string): string | undefined {
 	return requireString(value, field);
 }
 
+function nullableString(value: unknown, field: string): string | null {
+	if (value === undefined || value === null) return null;
+	return requireString(value, field);
+}
+
 function parseRefsOutput(value: unknown): ReadSeekRefsOutput {
 	if (!value || typeof value !== "object") throw new Error("invalid readseek refs output");
 	const output = value as Record<string, unknown>;
@@ -594,3 +633,61 @@ export async function readseekCheck(
 		await runReadSeek(["check", "--stdin", filePath], { signal: options.signal, stdin: content }),
 	);
 }
+
+function parseImageInfo(value: unknown): ReadSeekImageInfo | null {
+	if (value === undefined || value === null) return null;
+	if (typeof value !== "object") throw new Error("invalid readseek detect image");
+	const image = value as Record<string, unknown>;
+	return {
+		format: requireString(image.format, "image.format"),
+		width: requireNumber(image.width, "image.width"),
+		height: requireNumber(image.height, "image.height"),
+		animated: requireBoolean(image.animated, "image.animated"),
+	};
+}
+
+function parseOcrText(value: unknown): ReadSeekOcrText | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "object") throw new Error("invalid readseek detect ocr");
+	const ocr = value as Record<string, unknown>;
+	if (!Array.isArray(ocr.lines)) throw new Error("invalid readseek detect ocr.lines");
+	return {
+		text: requireString(ocr.text, "ocr.text"),
+		lines: ocr.lines.map((line) => {
+			if (!line || typeof line !== "object") throw new Error("invalid readseek detect ocr line");
+			const item = line as Record<string, unknown>;
+			const bbox = item.bbox;
+			if (!Array.isArray(bbox) || bbox.length !== 4) throw new Error("invalid readseek detect ocr bbox");
+			return {
+				text: requireString(item.text, "ocr.line.text"),
+				bbox: bbox.map((n, i) => requireNumber(n, `ocr.line.bbox[${i}]`)) as [number, number, number, number],
+			};
+		}),
+	};
+}
+
+function parseDetectOutput(value: unknown): ReadSeekDetection {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek detect output");
+	const output = value as Record<string, unknown>;
+	return {
+		file: requireString(output.file, "file"),
+		language: requireString(output.language, "language"),
+		engine: nullableString(output.engine, "engine"),
+		supported: requireBoolean(output.supported, "supported"),
+		binary: requireBoolean(output.binary, "binary"),
+		mime: nullableString(output.mime, "mime"),
+		syntax: nullableString(output.syntax, "syntax"),
+		image: parseImageInfo(output.image),
+		ocr: parseOcrText(output.ocr),
+	};
+}
+
+export async function readseekDetect(
+	filePath: string,
+	options: { ocr?: boolean; signal?: AbortSignal } = {},
+): Promise<ReadSeekDetection> {
+	const args = ["detect"];
+	if (options.ocr) args.push("--ocr");
+	args.push(filePath);
+	return parseDetectOutput(await runReadSeek(args, { signal: options.signal }));
+}

package/src/tool-prompt-metadata.ts

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
 
 const COMPACT_DESCRIPTIONS: Record<string, string> = {
-  "read.md": "Read text files/images by path; text has LINE:HASH anchors, images return attachments.",
+  "read.md": "Read text files/images by path; text has LINE:HASH anchors, images return the attachment plus OCR-extracted text.",
   "edit.md": "Edit existing text files using fresh LINE:HASH anchors from read, grep, search, or write.",
   "grep.md": "Search file contents; non-summary results include LINE:HASH anchors for edits.",
 
@@ -16,7 +16,7 @@ const COMPACT_GUIDELINES: Record<string, string[]> = {
   "read.md": [
     "Use read for file contents, images/screenshots, ranges, symbols, and edit anchors.",
     "Use map or symbol mode before pulling large code files into context.",
-    "Use read for images; it returns attachments, so avoid OCR tools unless explicitly needed.",
+    "Use read for images; it returns the image attachment plus OCR-extracted text, so you don't need separate OCR tools.",
   ],
   "edit.md": [
     "Use edit with fresh LINE:HASH anchors for existing files.",

package/src/image-detect.ts

@@ -1,47 +0,0 @@
-const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
-
-function startsWithBytes(buffer: Buffer, bytes: number[]): boolean {
-	return buffer.length >= bytes.length && bytes.every((byte, index) => buffer[index] === byte);
-}
-
-function startsWithAscii(buffer: Buffer, offset: number, text: string): boolean {
-	if (buffer.length < offset + text.length) return false;
-	for (let index = 0; index < text.length; index++) {
-		if (buffer[offset + index] !== text.charCodeAt(index)) return false;
-	}
-	return true;
-}
-
-function readUint32BE(buffer: Buffer, offset: number): number {
-	return (
-		((buffer[offset] ?? 0) * 0x1000000) +
-		((buffer[offset + 1] ?? 0) << 16) +
-		((buffer[offset + 2] ?? 0) << 8) +
-		(buffer[offset + 3] ?? 0)
-	);
-}
-
-function isPng(buffer: Buffer): boolean {
-	return buffer.length >= 16 && readUint32BE(buffer, PNG_SIGNATURE.length) === 13 && startsWithAscii(buffer, 12, "IHDR");
-}
-
-function isAnimatedPng(buffer: Buffer): boolean {
-	let offset = PNG_SIGNATURE.length;
-	while (offset + 8 <= buffer.length) {
-		const chunkLength = readUint32BE(buffer, offset);
-		const chunkTypeOffset = offset + 4;
-		if (startsWithAscii(buffer, chunkTypeOffset, "acTL")) return true;
-		if (startsWithAscii(buffer, chunkTypeOffset, "IDAT")) return false;
-		const nextOffset = offset + 8 + chunkLength + 4;
-		if (nextOffset <= offset || nextOffset > buffer.length) return false;
-		offset = nextOffset;
-	}
-	return false;
-}
-
-export function isSupportedImageBuffer(buffer: Buffer): boolean {
-	if (startsWithBytes(buffer, [0xff, 0xd8, 0xff])) return buffer[3] !== 0xf7;
-	if (startsWithBytes(buffer, PNG_SIGNATURE)) return isPng(buffer) && !isAnimatedPng(buffer);
-	if (startsWithAscii(buffer, 0, "GIF")) return true;
-	return startsWithAscii(buffer, 0, "RIFF") && startsWithAscii(buffer, 8, "WEBP");
-}