pi-readseek 0.9.10 → 0.9.12

package/README.md

@@ -2,8 +2,9 @@
 
 `pi-readseek` adds ReadSeek's anchored file operations, structural search,
 symbol navigation, and document tools to Pi. Built-ins remain available unless
-`overrideTools` maps `edit`, `write`, or `grep` to a ReadSeek-backed
-implementation.
+`overrideTools` maps `read`, `edit`, `write`, or `grep` to a ReadSeek-backed
+implementation. The `read` override runs ReadSeek's `digest` command; it does not
+add a separate `readSeek_read` tool.
 
 ## Install
 
@@ -12,8 +13,9 @@ pi install npm:pi-readseek
 ```
 
 The package depends on `@jarkkojs/readseek`, which supplies the native binary on
-supported platforms. A user-managed `readseek` on `PATH` (for example a
-system-package or developer install) takes precedence over the bundled binary.
+supported platforms. The extension uses that packaged binary exclusively; an
+unresolved binary indicates a broken installation rather than falling back to an
+unrelated `readseek` executable on `PATH`.
 
 ## Tools
 
@@ -58,11 +60,13 @@ Defaults:
 }
 ```
 
-- `overrideTools`: any of `"edit"`, `"write"`, and `"grep"`.
-- `imageMode`: `"auto"` uses Pi's native image input when available, `"on"`
-  always runs local analysis, and `"off"` skips standalone images. Image modes
-  are `all`, `ocr`, `caption`, and `objects`; in `"auto"`, `none` returns a
-  prepared image without local analysis. Documents use `readSeek_view` with
+- `overrideTools`: any of `"read"`, `"edit"`, `"write"`, and `"grep"`.
+- `imageMode`: controls standalone images when `digest` overrides `read`.
+  `"auto"` passes the prepared image to image-capable Pi models and otherwise
+  runs local analysis, `"on"` always runs local analysis, and `"off"` skips the
+  image. Local analysis defaults to `all` and also supports `ocr`, `caption`, and
+  `objects` through `visionMode`. The namespaced `readSeek_digest` tool applies
+  `visionMode` directly, including `none`. Documents use `readSeek_view` with
   optional `visionMode` and `visionLevel`. Local analysis uses
   [Qwen3-VL-2B-Instruct](../../docs/models/qwen3-vl-2b-instruct.md).
 - `syntaxValidation`: `"warn"` (write and warn), `"block"` (abort), or `"off"`.

package/dist/index.ts

@@ -403,6 +403,11 @@ var TOOL_CONTRACTS = [
 ];
 // ../readseek-api/src/policy.ts
 var REPLACEABLE_TOOLS = [
+  {
+    tool: "digest",
+    builtIn: "read",
+    benefit: "it returns LINE:HASH anchors for safe edits."
+  },
   {
     tool: "edit",
     builtIn: "edit",
@@ -685,23 +690,17 @@ function resolveReadSeekBinaryFromPackages(resolver = resolveFromPackage, option
   const metaPackage = options.metaPackage ?? "@jarkkojs/readseek";
   const metaPackageJson = resolve(`${metaPackage}/package.json`);
   const metaPackageDir = path.dirname(metaPackageJson);
-  const packageJsonPath = resolve(`${platformPackage}/package.json`, {
-    paths: [metaPackageDir]
-  });
-  return path.join(path.dirname(packageJsonPath), "bin", readSeekBinaryName(platform));
-}
-function resolveReadSeekBinaryFromPath(pathEnv = process.env.PATH) {
-  const name = readSeekBinaryName();
-  for (const dir of (pathEnv ?? "").split(path.delimiter)) {
-    if (!dir)
-      continue;
-    const candidate = path.join(dir, name);
-    try {
-      accessSync(candidate, fsConstants.X_OK);
-      return candidate;
-    } catch {}
+  let packageJsonPath;
+  try {
+    packageJsonPath = resolve(`${platformPackage}/package.json`);
+  } catch {
+    packageJsonPath = resolve(`${platformPackage}/package.json`, {
+      paths: [metaPackageDir]
+    });
   }
-  return null;
+  const binaryPath = path.join(path.dirname(packageJsonPath), "bin", readSeekBinaryName(platform));
+  accessSync(binaryPath, fsConstants.X_OK);
+  return binaryPath;
 }
 // ../readseek-api/src/json.ts
 var READSEEK_USAGE_HINT = /\n\s*Run readseek(?: [\w-]+)* --help for more information\.?\s*$/;
@@ -2150,6 +2149,7 @@ import { readFileSync, statSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { join } from "node:path";
 var READSEEK_TOOL_REPLACEMENTS = {
+  read: "readSeek_digest",
   edit: "readSeek_edit",
   grep: "readSeek_grep",
   write: "readSeek_write"
@@ -2346,6 +2346,9 @@ function resolveReadSeekJsonSettings() {
     warnings: [...globalResult.warnings, ...projectResult.warnings]
   };
 }
+function resolveReadSeekImageMode() {
+  return resolveReadSeekJsonSettings().settings.imageMode ?? "auto";
+}
 function resolveReadSeekSyntaxValidation() {
   return resolveReadSeekJsonSettings().settings.syntaxValidation;
 }
@@ -2359,7 +2362,7 @@ function resolveReadSeekToolDisplayMode(tool) {
 // src/readseek-client.ts
 var resolveFromHost = createRequire2(import.meta.url).resolve;
 function readSeekBinaryPath() {
-  return resolveReadSeekBinaryFromPath() ?? resolveReadSeekBinaryFromPackages(resolveFromHost);
+  return resolveReadSeekBinaryFromPackages(resolveFromHost);
 }
 function readSeekBinaryAvailability() {
   try {
@@ -5460,6 +5463,36 @@ function summarizeEnvelope(envelope, facets) {
     parts.unshift("metadata");
   return `digested ${parts.join(",") || "metadata"}`;
 }
+function parseImageEnvelope(envelope) {
+  if (!envelope || typeof envelope !== "object")
+    return;
+  const record = envelope;
+  if (!record.metadata || typeof record.metadata !== "object")
+    return;
+  const metadata = record.metadata;
+  if (typeof metadata.type !== "string" || !metadata.type.startsWith("image/"))
+    return;
+  if (!record.content || typeof record.content !== "object")
+    return { metadata };
+  const content = record.content;
+  const mime = content.mime ?? content.type ?? metadata.mime ?? metadata.type;
+  const prepared = content.encoding === "base64" && typeof content.data === "string" && typeof mime === "string" ? { data: content.data, mimeType: mime } : undefined;
+  return { metadata, prepared };
+}
+function buildDigestSuccess(filePath, facets, envelope, content = [{ type: "text", text: JSON.stringify(envelope) }]) {
+  return {
+    content,
+    details: {
+      readSeekValue: {
+        tool: "digest",
+        ok: true,
+        path: filePath,
+        select: facets,
+        envelope
+      }
+    }
+  };
+}
 async function executeDigest(opts) {
   const { params, signal, cwd, onFileAnchored } = opts;
   const p = params;
@@ -5471,6 +5504,8 @@ async function executeDigest(opts) {
       path: p.path
     });
   }
+  const facets = selectedFacets(select);
+  const appliesImagePolicy = opts.imageMode !== undefined && facets.includes("content");
   const end = coerceObviousBase10Int(p.end, "end");
   if (!end.ok || end.value !== undefined && end.value < 1) {
     const message = end.ok ? `Invalid end: expected a positive integer, received ${end.value}.` : end.message;
@@ -5487,41 +5522,67 @@ async function executeDigest(opts) {
       path: p.path
     });
   }
-  if (p.visionLevel !== undefined && p.visionMode === undefined) {
+  if (p.visionLevel !== undefined && p.visionMode === undefined && !appliesImagePolicy) {
     return buildToolErrorResult("digest", "invalid-params-combo", "visionLevel requires visionMode.", {
       path: p.path
     });
   }
   const filePath = resolveToCwd(p.path, cwd);
-  const facets = selectedFacets(select);
-  const vision = p.visionMode !== undefined && p.visionMode !== "none";
+  const commonOptions = { select, signal };
+  const textOptions = {
+    ...commonOptions,
+    at,
+    end: end.value,
+    limit: limit.value,
+    language: p.language
+  };
+  const hasTextOptions = at !== undefined || end.value !== undefined || limit.value !== undefined || p.language !== undefined;
+  const hasVisionOptions = p.visionMode !== undefined || p.visionLevel !== undefined;
+  const initialVisionMode = appliesImagePolicy ? undefined : p.visionMode;
+  const initialVisionLevel = appliesImagePolicy ? undefined : p.visionLevel;
   try {
     const envelope = await readSeekDigestNative(filePath, {
-      select,
-      at,
-      end: end.value,
-      limit: limit.value,
-      language: p.language,
+      ...appliesImagePolicy ? commonOptions : textOptions,
+      visionMode: initialVisionMode,
+      visionLevel: initialVisionLevel,
+      vision: initialVisionMode !== undefined && initialVisionMode !== "none"
+    });
+    const image = appliesImagePolicy ? parseImageEnvelope(envelope) : undefined;
+    if (image) {
+      const imageDetails = { metadata: image.metadata };
+      if (opts.imageMode === "off") {
+        return buildDigestSuccess(filePath, facets, imageDetails, [
+          { type: "text", text: `[Skipped standalone image: ${p.path}; readseek.imageMode is off]` }
+        ]);
+      }
+      if (opts.imageMode === "auto" && opts.modelSupportsImages && image.prepared) {
+        return buildDigestSuccess(filePath, facets, imageDetails, [
+          { type: "image", data: image.prepared.data, mimeType: image.prepared.mimeType }
+        ]);
+      }
+      const visionMode = p.visionMode && p.visionMode !== "none" ? p.visionMode : "all";
+      const analyzedEnvelope = await readSeekDigestNative(filePath, {
+        ...commonOptions,
+        visionMode,
+        visionLevel: p.visionLevel,
+        vision: true
+      });
+      return buildDigestSuccess(filePath, facets, analyzedEnvelope);
+    }
+    if (p.visionLevel !== undefined && p.visionMode === undefined) {
+      return buildToolErrorResult("digest", "invalid-params-combo", "visionLevel requires visionMode.", {
+        path: p.path
+      });
+    }
+    const textEnvelope = appliesImagePolicy && (hasTextOptions || hasVisionOptions) ? await readSeekDigestNative(filePath, {
+      ...textOptions,
       visionMode: p.visionMode,
       visionLevel: p.visionLevel,
-      signal,
-      vision
-    });
-    if (hasDigestAnchors(envelope))
+      vision: p.visionMode !== undefined && p.visionMode !== "none"
+    }) : envelope;
+    if (hasDigestAnchors(textEnvelope))
       onFileAnchored?.(filePath);
-    const text = JSON.stringify(envelope);
-    return {
-      content: [{ type: "text", text }],
-      details: {
-        readSeekValue: {
-          tool: "digest",
-          ok: true,
-          path: filePath,
-          select: facets,
-          envelope
-        }
-      }
-    };
+    return buildDigestSuccess(filePath, facets, textEnvelope);
   } catch (err) {
     const failure = classifyReadSeekFailure(err);
     return buildToolErrorResult("digest", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
@@ -5543,7 +5604,14 @@ function registerDigestTool(pi, options = {}) {
     promptGuidelines: promptMetadata.promptGuidelines,
     parameters: digestSchema,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      return executeDigest({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
+      return executeDigest({
+        params,
+        signal,
+        cwd: ctx.cwd,
+        onFileAnchored: options.onFileAnchored,
+        imageMode: options.imageMode,
+        modelSupportsImages: ctx.model?.input.includes("image") ?? false
+      });
     },
     renderCall(args, theme, ...rest) {
       const context = rest[0] ?? {};
@@ -5736,7 +5804,7 @@ var READSEEK_TOOL_ENTRIES = [
   { builtIn: null, readSeekName: "readSeek_rename" },
   { builtIn: "write", readSeekName: "readSeek_write" },
   { builtIn: null, readSeekName: "readSeek_def" },
-  { builtIn: null, readSeekName: "readSeek_digest" },
+  { builtIn: "read", readSeekName: "readSeek_digest" },
   { builtIn: null, readSeekName: "readSeek_view" }
 ];
 function formatSettingsWarning(warning) {
@@ -5756,11 +5824,13 @@ function piReadSeekExtension(pi) {
   const { settings } = resolveReadSeekJsonSettings();
   const replacedBuiltIns = new Set(settings.overrideTools ?? []);
   const binaryAvailable = readSeekBinaryAvailability().available;
-  const swap = (builtIn, readSeekName) => binaryAvailable && replacedBuiltIns.has(builtIn) ? builtIn : readSeekName;
+  const swap = (builtIn, readSeekName) => replacedBuiltIns.has(builtIn) ? builtIn : readSeekName;
+  const readName = swap("read", "readSeek_digest");
   const editName = swap("edit", "readSeek_edit");
   const writeName = swap("write", "readSeek_write");
   const grepName = swap("grep", "readSeek_grep");
   const toolAliases = {
+    readSeek_digest: readName,
     readSeek_edit: editName,
     readSeek_grep: grepName,
     readSeek_write: writeName
@@ -5775,7 +5845,12 @@ function piReadSeekExtension(pi) {
   registerRefsTool(pi, { onFileAnchored: markAnchored });
   registerRenameTool(pi, { onFileMutated: forgetAnchors });
   registerDefTool(pi, { onFileAnchored: markAnchored });
-  registerDigestTool(pi, { onFileAnchored: markAnchored, name: "readSeek_digest", toolAliases });
+  registerDigestTool(pi, {
+    onFileAnchored: markAnchored,
+    name: readName,
+    toolAliases,
+    imageMode: replacedBuiltIns.has("read") ? resolveReadSeekImageMode() : undefined
+  });
   registerViewTool(pi);
   registerWriteTool(pi, { onFileAnchored: markAnchored, name: writeName });
   pi.on("before_agent_start", (event) => {
@@ -5791,7 +5866,7 @@ ${toolRoutingPolicy(policyAliases)}` };
     const problems = warnings.map(formatSettingsWarning);
     const availability = readSeekBinaryAvailability();
     if (!availability.available) {
-      problems.push(`readseek tools are inactive: ${availability.reason}`);
+      problems.push(`readseek installation is broken: ${availability.reason}`);
     }
     for (const problem of problems) {
       if (ctx.hasUI)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "description": "Pi extension for LINE:HASH-anchored file operations and structural code navigation",
   "type": "module",
   "exports": {
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.9.10",
+    "@jarkkojs/readseek": "^0.9.12",
     "diff": "^9.0.0",
     "xxhash-wasm": "^1.1.0"
   },