pi-readseek 0.8.15 → 0.8.17

package/README.md

@@ -56,9 +56,13 @@ Add an optional `readseek` section to `~/.pi/agent/settings.json` (global) or
 
 - `replacedTools`: built-in tools backed by ReadSeek. Valid values are `"read"`,
   `"edit"`, `"write"`, and `"grep"`.
-- `imageMode`: `"auto"` exposes `none`, `all`, `ocr`, `caption`, and `objects`;
-  `"on"` omits `none`; `"off"` skips images and PDFs. Omitting `image` also skips
-  visual files.
+- `imageMode`: controls standalone images and images embedded in PDFs. `"auto"`
+  exposes `none`, `all`, `ocr`, `caption`, and `objects`. When the active model
+  accepts images, `"auto"` silently passes prepared images to the model instead
+  of running local analysis. `"on"` always runs the selected local analysis and
+  omits `none`; `"off"` skips standalone and embedded images. PDF text is always
+  read regardless of `imageMode`. Omitting `image` skips standalone images and,
+  unless native vision is available in `"auto"` mode, PDF embedded images.
 - `syntaxValidation`: syntax-regression handling for `readSeek_edit`. `"warn"`
   writes with a warning, `"block"` aborts, and `"off"` disables the check.
 - `timeoutMs`: ReadSeek command timeout in milliseconds.

package/dist/index.ts

@@ -3251,6 +3251,16 @@ ${details.join(`
 
 `);
 }
+function preparedPdfContent(pdf) {
+  const 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]` });
+    content.push({ type: "image", data: image.data, mimeType: image.mime });
+  }
+  return content;
+}
 function truncateDocumentText(text) {
   const truncation = truncateHead2(text, { maxLines: DEFAULT_MAX_LINES3, maxBytes: DEFAULT_MAX_BYTES3 });
   if (!truncation.truncated)
@@ -3258,9 +3268,9 @@ function truncateDocumentText(text) {
   return `${truncation.content}
 [… document output truncated; use readSeek_view with page or node selectors]`;
 }
-function skippedVisualFile(path2) {
+function skippedImageFile(path2) {
   return {
-    content: [{ type: "text", text: `[Skipped image/PDF: ${path2}; no image mode selected]` }],
+    content: [{ type: "text", text: `[Skipped image: ${path2}; no image mode selected]` }],
     details: {}
   };
 }
@@ -3361,7 +3371,7 @@ async function executeRead(opts) {
         path: rawParams.path
       });
     }
-    if (detection.kind === "image" || detection.type === "application/pdf") {
+    if (detection.kind === "image" || detection.kind === "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 });
@@ -3370,49 +3380,55 @@ async function executeRead(opts) {
         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);
-      }
+      const useNativeVision = imageMode === "auto" && opts.modelSupportsImages === true;
       if (imageMode === "on" && p.image === "none") {
         return buildToolErrorResult("read", "invalid-params-combo", 'image="none" is only available when imageMode is "auto".', {
           path: rawParams.path
         });
       }
-      if (p.image === "none") {
+      if (detection.kind === "pdf") {
+        let pdfImageMode = "none";
+        if (imageMode !== "off" && p.image !== undefined && p.image !== "none" && !useNativeVision) {
+          pdfImageMode = p.image;
+        }
         try {
-          if (detection.kind === "pdf") {
-            const pdf = await readSeekPdf(absolutePath, p.image, { page: pdfPage, signal });
-            const content = [{ type: "text", text: truncateDocumentText(pdf.markdown) }];
-            for (const image2 of pdf.images) {
-              if (image2.encoding !== "base64" || image2.data === undefined)
-                continue;
-              content.push({ type: "text", text: `[PDF page ${image2.page} image]` });
-              content.push({ type: "image", data: image2.data, mimeType: image2.mime });
-            }
-            return succeed({ content, details: {} });
+          const pdf = await readSeekPdf(absolutePath, pdfImageMode, { page: p.page ?? 1, signal });
+          if (pdfImageMode !== "none") {
+            return succeed({
+              content: [{ type: "text", text: truncateDocumentText(formatPdfAnalysis(pdf)) }],
+              details: {}
+            });
           }
-          const image = await readSeekPreparedImage(absolutePath, { signal });
           return succeed({
-            content: [{ type: "image", data: image.data, mimeType: image.mime }],
+            content: useNativeVision ? preparedPdfContent(pdf) : [{ type: "text", text: truncateDocumentText(pdf.markdown) }],
             details: {}
           });
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          return buildToolErrorResult("read", "read-error", `Image preprocessing unavailable: ${message}`, {
+          return buildToolErrorResult("read", "read-error", `PDF reading unavailable: ${message}`, {
             path: rawParams.path
           });
         }
       }
-      try {
-        if (detection.kind === "pdf") {
-          const pdf = await readSeekPdf(absolutePath, p.image, { page: pdfPage, signal });
+      if (imageMode === "off" || p.image === undefined) {
+        return skippedImageFile(rawParams.path);
+      }
+      if (useNativeVision || p.image === "none") {
+        try {
+          const image = await readSeekPreparedImage(absolutePath, { signal });
           return succeed({
-            content: [{ type: "text", text: truncateDocumentText(formatPdfAnalysis(pdf)) }],
+            content: [{ type: "image", data: image.data, mimeType: image.mime }],
             details: {}
           });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          return buildToolErrorResult("read", "read-error", `Image preprocessing unavailable: ${message}`, {
+            path: rawParams.path
+          });
         }
+      }
+      try {
         const analysis = await readSeekImage(absolutePath, [p.image], { signal });
         const imageAnalysis = formatImageAnalysis(analysis, p.image);
         if (imageAnalysis) {
@@ -3423,8 +3439,7 @@ async function executeRead(opts) {
         }
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        const label = detection.kind === "pdf" ? "PDF" : "Image";
-        return buildToolErrorResult("read", "read-error", `${label} analysis unavailable: ${message}`, {
+        return buildToolErrorResult("read", "read-error", `Image analysis unavailable: ${message}`, {
           path: rawParams.path
         });
       }
@@ -3663,11 +3678,11 @@ function registerReadTool(pi, options = {}) {
   const tool = registerReadSeekTool(pi, {
     name,
     label: "Read",
-    description: imageMode === "off" ? 'Read anchored text by range, map, or symbol; image and PDF files are skipped because imageMode is "off".' : promptMetadata.description,
+    description: imageMode === "off" ? 'Read anchored text by range, map, or symbol; standalone images are skipped because imageMode is "off", while PDFs are read as text.' : promptMetadata.description,
     promptSnippet: promptMetadata.promptSnippet,
     promptGuidelines: [
       ...promptMetadata.promptGuidelines,
-      imageMode === "off" ? "The image parameter is unavailable; image and PDF files are always skipped." : `For an image or PDF, explicitly choose image: ${imageModes.join(", ")}; omitting image skips the file.`
+      imageMode === "off" ? "The image parameter is unavailable; standalone images and PDF embedded images are skipped, while PDFs are read as text." : `For an image, explicitly choose image: ${imageModes.join(", ")}; omitting image skips standalone images. PDFs are always read as text, and image controls embedded images.${imageMode === "auto" ? " Native image-capable models bypass local analysis and receive standalone and PDF embedded images directly." : ""}`
     ],
     parameters: Type2.Object({
       path: filePathParam(),
@@ -3681,7 +3696,7 @@ function registerReadTool(pi, options = {}) {
       })),
       ...imageMode === "off" ? {} : {
         image: Type2.Optional(Type2.Union(imageModes.map((mode) => Type2.Literal(mode)), {
-          description: `Image/PDF mode: ${imageModes.join(", ")}. Must be selected explicitly.`
+          description: `Standalone image/PDF embedded-image mode: ${imageModes.join(", ")}. Must be selected explicitly for standalone images.`
         }))
       }
     }),
@@ -3692,7 +3707,8 @@ function registerReadTool(pi, options = {}) {
         signal,
         onUpdate,
         cwd: ctx.cwd,
-        onSuccessfulRead: options.onSuccessfulRead
+        onSuccessfulRead: options.onSuccessfulRead,
+        modelSupportsImages: ctx.model?.input.includes("image") ?? false
       });
     },
     renderCall(args, theme, ...rest) {
@@ -3726,13 +3742,19 @@ function registerReadTool(pi, options = {}) {
       const readSeekValue = result.details?.readSeekValue;
       if (!readSeekValue) {
         const lines = textContent.split(`
-`).filter(Boolean).length || textContent.split(`
-`).length;
-        return new Text2(summaryLine(`loaded ${lines} ${lines === 1 ? "line" : "lines"}`, {
+`).filter(Boolean).length;
+        let text2 = summaryLine(`loaded ${lines} ${lines === 1 ? "line" : "lines"}`, {
           hidden: !!textContent && !expanded,
           theme,
           style: "success"
-        }), 0, 0);
+        });
+        if (expanded && textContent) {
+          text2 += `
+${textContent}`;
+        }
+        return new Text2(clampLinesToWidth(text2.split(`
+`), width).join(`
+`), 0, 0);
       }
       const info = formatReadResultText({ range: readSeekValue.range, truncation: readSeekValue.truncation, symbol: readSeekValue.symbol, map: readSeekValue.map, warnings: readSeekValue.warnings });
       const visibleLines = info.truncated && readSeekValue.truncation ? readSeekValue.truncation.outputLines : readSeekValue.range.endLine - readSeekValue.range.startLine + 1;
@@ -6124,7 +6146,6 @@ async function statSearchPathOrError(tool, rawPath, searchPath) {
   try {
     return { ok: true, stats: await fsStat2(searchPath) };
   } catch (err) {
-    const display = rawPath ?? ".";
     const path3 = rawPath ?? searchPath;
     const { code, message } = formatFsError(err, "stat-error");
     return { ok: false, error: buildToolErrorResult(tool, code, message, { path: path3 }) };

package/package.json

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

package/prompts/read.md

@@ -1,4 +1,4 @@
-Read anchored text by range, map, or symbol, and process images or PDFs with an explicit mode.
+Read anchored text by range, map, or symbol, process images with an explicit mode, and always read PDF text.
 
 ## Choose the right read
 
@@ -14,10 +14,10 @@ Read anchored text by range, map, or symbol, and process images or PDFs with an
 - `map` — full-file map; incompatible with `symbol` or `bundle`.
 - `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"`.
+- `image` — an exposed standalone-image/PDF embedded-image 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}}. PDF reads return one page by default. 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 always return text for one page by default. Omitting `image` skips standalone images and PDF embedded images unless native vision is available in `"auto"` mode. With native vision, prepared standalone and PDF embedded images are passed directly instead of using local analysis.
 
 Truncated full-file reads append a map when available. Use its ranges for follow-up reads.