pi-readseek 0.5.0 → 0.5.1

package/README.md

@@ -38,17 +38,18 @@ npm install --save-dev @jarkkojs/readseek
 
 `pi-readseek` reads optional JSON settings from:
 
-- `~/.pi/agent/readseek/settings.json` — Global
-- `.pi/readseek/settings.json` — Project
+- `~/.pi/agent/settings.json` — Global
+- `.pi/settings.json` — Project
 
-Project settings override global settings. All settings live in a single
-`readseek` section and are optional (defaults shown):
+Project settings override global settings. The `readseek` section lives inside pi's
+shared `settings.json`, alongside other extensions' sections. All settings are
+optional (defaults shown):
 
 ```json
 {
   "readseek": {
     "excludeTools": [],
-    "ocrMode": "force",
+    "imageMode": "force",
     "syntaxValidation": "warn",
     "timeoutMs": 120000,
     "grep": {
@@ -62,7 +63,7 @@ Project settings override global settings. All settings live in a single
 - **excludeTools:** active tool names to hide after activating `readSeek_*`
   tools. For a readseek-only file surface, use `["read", "edit", "write",
   "grep"]`.
-- **ocrMode:** image OCR/caption/object analysis in `readSeek_read`: `"force"`
+- **imageMode:** image OCR/caption/object analysis in `readSeek_read`: `"force"`
   (or its alias `"on"`) always runs it, `"off"` returns only the image
   attachment, and `"auto"` runs it only when the active model does not support
   native image input.

package/package.json

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

package/prompts/read.md

@@ -1,4 +1,4 @@
-Read files through readseek. Text output uses `LINE:HASH|content` anchors that can be copied directly into `readSeek_edit`; supported images return attachments and may append OCR/caption/object text depending on `readseek.ocrMode`. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
+Read files through readseek. Text output uses `LINE:HASH|content` anchors that can be copied directly into `readSeek_edit`; supported images return attachments and may append OCR/caption/object text depending on `readseek.imageMode`. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
 
 ## Choose the right read
 

package/src/read.ts

@@ -28,14 +28,14 @@ import { buildLocalBundle } from "./read-local-bundle.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
 import { readSeekRead, readSeekDetect, readSeekImage, type ReadSeekDetection } from "./readseek-client.js";
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
-import { resolveReadSeekOcrMode } from "./readseek-settings.js";
+import { resolveReadSeekImageMode } from "./readseek-settings.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidthCached } from "./tui-render-utils.js";
 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",
+	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 {
@@ -58,7 +58,7 @@ export interface ExecuteReadOptions {
 	onUpdate: any;
 	cwd: string;
 	onSuccessfulRead?: FileAnchoredCallback;
-	/** Whether the active model accepts image input natively. Used when OCR mode is auto. */
+	/** Whether the active model accepts image input natively. Used when imageMode is auto. */
 	modelSupportsImages?: boolean;
 }
 
@@ -177,11 +177,10 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 		if (detection?.kind === "image") {
 			const builtinRead = createReadTool(cwd);
 			const builtinResult = await builtinRead.execute(toolCallId, p, signal, onUpdate);
-			const ocrMode = resolveReadSeekOcrMode();
-			const shouldRunVision = ocrMode === "force" || (ocrMode === "auto" && !opts.modelSupportsImages);
+			const imageMode = resolveReadSeekImageMode();
+			const shouldRunVision = imageMode === "force" || (imageMode === "auto" && !opts.modelSupportsImages);
 			if (!shouldRunVision) return succeed(builtinResult);
 
-			let ocrFailed = false;
 			try {
 				const ocrDetection = await readSeekImage(absolutePath, ["ocr", "caption", "objects"], { signal });
 				const imageAnalysis = formatImageAnalysis(ocrDetection);
@@ -195,14 +194,11 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 					});
 				}
 			} catch {
-				ocrFailed = true;
-			}
-			if (ocrFailed) {
 				return succeed({
 					...builtinResult,
 					content: [
 						...(builtinResult.content ?? []),
-						{ type: "text" as const, text: "[Warning: local image analysis (OCR) unavailable — showing image attachment only]" },
+						{ type: "text" as const, text: "[Warning: local image analysis unavailable — showing image attachment only]" },
 					],
 				});
 			}

package/src/readseek-settings.ts

@@ -2,7 +2,7 @@ import { readFileSync, statSync, type Stats } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-export type ReadSeekOcrMode = "force" | "off" | "auto";
+export type ReadSeekImageAnalysisMode = "force" | "off" | "auto";
 export type ReadSeekSyntaxValidationMode = "warn" | "block" | "off";
 
 interface ReadSeekGrepSettings {
@@ -12,7 +12,7 @@ interface ReadSeekGrepSettings {
 
 interface ReadSeekJsonSettings {
   excludeTools?: string[];
-  ocrMode?: ReadSeekOcrMode;
+  imageMode?: ReadSeekImageAnalysisMode;
   syntaxValidation?: ReadSeekSyntaxValidationMode;
   timeoutMs?: number;
   grep?: ReadSeekGrepSettings;
@@ -29,15 +29,15 @@ export interface ReadSeekSettingsResult {
   warnings: ReadSeekSettingsWarning[];
 }
 
-const READSEEK_KEYS = ["excludeTools", "ocrMode", "syntaxValidation", "timeoutMs", "grep"];
+const READSEEK_KEYS = ["excludeTools", "imageMode", "syntaxValidation", "timeoutMs", "grep"];
 const READSEEK_GREP_KEYS = ["maxLines", "maxBytes"];
 
-function defaultGlobalSettingsPath(): string {
-  return join(homedir(), ".pi/agent/readseek/settings.json");
+function globalSettingsPath(): string {
+  return join(homedir(), ".pi/agent/settings.json");
 }
 
-function defaultProjectSettingsPath(): string {
-  return join(process.cwd(), ".pi/readseek/settings.json");
+function projectSettingsPath(): string {
+  return join(process.cwd(), ".pi/settings.json");
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -91,16 +91,16 @@ function readEnum<T extends string>(
   return undefined;
 }
 
-function readOcrMode(
+function readImageMode(
   raw: Record<string, unknown>,
   source: string,
   warnings: ReadSeekSettingsWarning[],
-): ReadSeekOcrMode | undefined {
-  if (!("ocrMode" in raw)) return undefined;
-  const val = raw.ocrMode;
+): ReadSeekImageAnalysisMode | undefined {
+  if (!("imageMode" in raw)) return undefined;
+  const val = raw.imageMode;
   if (val === "on") return "force";
   if (val === "force" || val === "off" || val === "auto") return val;
-  warnings.push(invalid(source, "readseek.ocrMode"));
+  warnings.push(invalid(source, "readseek.imageMode"));
   return undefined;
 }
 
@@ -153,8 +153,8 @@ function validateSettings(raw: unknown, source: string): ReadSeekSettingsResult
   const excludeTools = readStringArray(section, "excludeTools", "readseek.excludeTools", source, warnings);
   if (excludeTools !== undefined) settings.excludeTools = excludeTools;
 
-  const ocrMode = readOcrMode(section, source, warnings);
-  if (ocrMode !== undefined) settings.ocrMode = ocrMode;
+  const imageMode = readImageMode(section, source, warnings);
+  if (imageMode !== undefined) settings.imageMode = imageMode;
 
   const syntaxValidation = readEnum(
     section,
@@ -232,16 +232,16 @@ function mergeSettings(base: ReadSeekJsonSettings, override: ReadSeekJsonSetting
 }
 
 export function resolveReadSeekJsonSettings(): ReadSeekSettingsResult {
-  const globalResult = readSettingsFile(defaultGlobalSettingsPath());
-  const projectResult = readSettingsFile(defaultProjectSettingsPath());
+  const globalResult = readSettingsFile(globalSettingsPath());
+  const projectResult = readSettingsFile(projectSettingsPath());
   return {
     settings: mergeSettings(globalResult.settings, projectResult.settings),
     warnings: [...globalResult.warnings, ...projectResult.warnings],
   };
 }
 
-export function resolveReadSeekOcrMode(): ReadSeekOcrMode {
-  return resolveReadSeekJsonSettings().settings.ocrMode ?? "force";
+export function resolveReadSeekImageMode(): ReadSeekImageAnalysisMode {
+  return resolveReadSeekJsonSettings().settings.imageMode ?? "force";
 }
 
 export function resolveReadSeekSyntaxValidation(): ReadSeekSyntaxValidationMode | undefined {

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 the attachment plus OCR-extracted text.",
+  "read.md": "Read text files/images by path; text has LINE:HASH anchors, images return the attachment plus OCR text, a caption, and detected objects.",
   "edit.md": "Edit existing text files using fresh LINE:HASH anchors from readSeek_read, readSeek_grep, readSeek_search, or readSeek_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 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-extracted text, so you don't need separate OCR tools.",
+    "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.",
   ],
   "edit.md": [
     "Use readSeek_edit with fresh LINE:HASH anchors for existing files.",