opencode-readseek 0.5.19 → 0.6.1

package/README.md

@@ -10,7 +10,7 @@ Add the plugin to `opencode.json`:
 
 ```json
 {
-  "plugin": ["opencode-readseek"]
+  "plugin": [["opencode-readseek", { "imageMode": "auto" }]]
 }
 ```
 
@@ -19,7 +19,7 @@ binary dependency with Bun at startup.
 
 ## Tools
 
-- `readseek_read`: read text with `LINE:HASH` anchors.
+- `readseek_read`: read text with `LINE:HASH` anchors; image/PDF handling is explicit.
 - `readseek_map`: generate a structural symbol map.
 - `readseek_search`: AST-pattern search.
 - `readseek_def`, `readseek_refs`, `readseek_hover`: symbol navigation.
@@ -31,6 +31,10 @@ records anchors from successful ReadSeek tool results, refuses any attempt to
 apply a rename directly, and adds current anchors plus a pending rename plan to
 the OpenCode compaction context.
 
+`imageMode` defaults to `"auto"`: it exposes `none`, `ocr`, `caption`, and
+`objects`. `"on"` omits `none`; `"off"` skips image/PDF files. Omitting
+`image` also skips visual files.
+
 ## Licensing
 
 This package is Apache-2.0. `@jarkkojs/readseek` is licensed separately as

package/index.ts

@@ -1,17 +1,47 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) Jarkko Sakkinen 2026
 
+import { stat } from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
 
-import { tool, type Plugin } from "@opencode-ai/plugin";
+import { tool, type Plugin, type PluginOptions, type ToolContext } from "@opencode-ai/plugin";
 
 const require = createRequire(import.meta.url);
 const readseekScript = require.resolve("@jarkkojs/readseek/bin/readseek.js");
+const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+
+type RenamePlan = {
+  summary: string;
+  files: Set<string>;
+};
+
+type PresentationKind = "read" | "map" | "search" | "def" | "refs" | "hover" | "rename" | "check";
+
+type Presentation = {
+  title: string;
+  metadata: Record<string, number>;
+};
+
+type ImagePolicy = "on" | "auto" | "off";
+type ImageMode = "none" | "ocr" | "caption" | "objects";
+
+function resolveImagePolicy(options: PluginOptions | undefined): ImagePolicy {
+  const value = options?.imageMode;
+  if (value === undefined) return "auto";
+  if (value === "on" || value === "auto" || value === "off") return value;
+  throw new Error('opencode-readseek imageMode must be "on", "auto", or "off"');
+}
+
+function isVisualFile(value: unknown): boolean {
+  const output = record(value);
+  const type = output.type;
+  return typeof output.width === "number" || type === "application/pdf";
+}
 
 class SessionAnchors {
   #pathsBySession = new Map<string, Set<string>>();
-  #renamePlans = new Map<string, string>();
+  #renamePlans = new Map<string, RenamePlan>();
 
   mark(sessionID: string, filePath: string): void {
     let paths = this.#pathsBySession.get(sessionID);
@@ -23,15 +53,33 @@ class SessionAnchors {
   }
 
   forget(filePath: string): void {
-    for (const paths of this.#pathsBySession.values()) paths.delete(filePath);
+    const absolutePath = path.resolve(filePath);
+    for (const paths of this.#pathsBySession.values()) paths.delete(absolutePath);
+    for (const [sessionID, plan] of this.#renamePlans) {
+      if (plan.files.has(absolutePath)) this.#renamePlans.delete(sessionID);
+    }
+  }
+
+  deleteSession(sessionID: string): void {
+    this.#pathsBySession.delete(sessionID);
+    this.#renamePlans.delete(sessionID);
   }
 
   planRename(sessionID: string, output: unknown): void {
     if (!output || typeof output !== "object") return;
-    const { old_name: oldName, new_name: newName } = output as Record<string, unknown>;
-    if (typeof oldName === "string" && typeof newName === "string") {
-      this.#renamePlans.set(sessionID, `${oldName} -> ${newName}`);
+    const record = output as Record<string, unknown>;
+    const { file, old_name: oldName, new_name: newName, others } = record;
+    if (typeof file !== "string" || typeof oldName !== "string" || typeof newName !== "string") return;
+
+    const files = new Set([path.resolve(file)]);
+    if (Array.isArray(others)) {
+      for (const item of others) {
+        if (!item || typeof item !== "object") continue;
+        const otherFile = (item as Record<string, unknown>).file;
+        if (typeof otherFile === "string") files.add(path.resolve(otherFile));
+      }
     }
+    this.#renamePlans.set(sessionID, { summary: `${oldName} -> ${newName}`, files });
   }
 
   render(sessionID: string): string | undefined {
@@ -44,7 +92,7 @@ class SessionAnchors {
       .join("\n")}`);
     }
     const renamePlan = this.#renamePlans.get(sessionID);
-    if (renamePlan) sections.push(`## Pending ReadSeek Rename Plan\n- ${renamePlan}`);
+    if (renamePlan) sections.push(`## Pending ReadSeek Rename Plan\n- ${renamePlan.summary}`);
     return sections.length === 0 ? undefined : sections.join("\n\n");
   }
 }
@@ -53,13 +101,58 @@ function resolvePath(directory: string, filePath: string): string {
   return path.resolve(directory, filePath);
 }
 
+function containsPath(directory: string, filePath: string): boolean {
+  const relative = path.relative(directory, filePath);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+async function authorizeExternal(context: ToolContext, filePath: string): Promise<void> {
+  if (containsPath(context.directory, filePath) || (context.worktree !== "/" && containsPath(context.worktree, filePath))) {
+    return;
+  }
+
+  const info = await stat(filePath).catch(() => undefined);
+  const parentDir = info?.isDirectory() ? filePath : path.dirname(filePath);
+  const pattern = path.join(parentDir, "*").replaceAll("\\", "/");
+  await context.ask({
+    permission: "external_directory",
+    patterns: [pattern],
+    always: [pattern],
+    metadata: { filepath: filePath, parentDir },
+  });
+}
+
+async function authorizeRead(context: ToolContext, filePath: string): Promise<void> {
+  await authorizeExternal(context, filePath);
+  await context.ask({
+    permission: "read",
+    patterns: [path.relative(context.worktree, filePath).replaceAll("\\", "/")],
+    always: ["*"],
+    metadata: {},
+  });
+}
+
+async function authorizeSearch(context: ToolContext, filePath: string, pattern: string): Promise<void> {
+  await context.ask({
+    permission: "grep",
+    patterns: [pattern],
+    always: ["*"],
+    metadata: { pattern, path: filePath },
+  });
+  await authorizeExternal(context, filePath);
+}
+
 function optionalFlag(args: string[], enabled: boolean | undefined, flag: string): void {
   if (enabled) args.push(flag);
 }
 
-async function runReadSeek(directory: string, args: string[]): Promise<unknown> {
+async function runReadSeek(context: ToolContext, args: string[]): Promise<unknown> {
+  context.abort.throwIfAborted();
   const child = Bun.spawn([process.execPath, readseekScript, ...args], {
-    cwd: directory,
+    cwd: context.directory,
+    killSignal: "SIGKILL",
+    maxBuffer: MAX_OUTPUT_BYTES,
+    signal: context.abort,
     stderr: "pipe",
     stdout: "pipe",
   });
@@ -68,6 +161,7 @@ async function runReadSeek(directory: string, args: string[]): Promise<unknown>
     new Response(child.stderr).text(),
     child.exited,
   ]);
+  context.abort.throwIfAborted();
   if (exitCode !== 0) throw new Error(stderr.trim() || `readseek exited with status ${exitCode}`);
 
   try {
@@ -94,16 +188,131 @@ function collectFiles(value: unknown, files: Set<string>): void {
   }
 }
 
+function identifiedName(value: unknown): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const identifier = (value as Record<string, unknown>).identifier;
+  if (!identifier || typeof identifier !== "object") return undefined;
+  const text = (identifier as Record<string, unknown>).text;
+  return typeof text === "string" ? text : undefined;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
+}
+
+function items(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function initialTitle(kind: PresentationKind, args: any): string {
+  switch (kind) {
+    case "read":
+      return `Read ${args.path}`;
+    case "map":
+      return `Map ${args.path}`;
+    case "search":
+      return `Search ${args.pattern}`;
+    case "def":
+      return `Find definition ${args.name}`;
+    case "refs":
+      return `Find references to ${args.name}`;
+    case "hover":
+      return `Identify ${args.path}:${args.line}`;
+    case "rename":
+      return `Rename ${args.path}:${args.line} to ${args.to}`;
+    case "check":
+      return `Check ${args.path}`;
+  }
+}
+
+function resultPresentation(kind: PresentationKind, args: any, value: unknown): Presentation {
+  const output = record(value);
+  switch (kind) {
+    case "read": {
+      const startLine = output.start_line;
+      const endLine = output.end_line;
+      if (typeof startLine === "number" && typeof endLine === "number") {
+        return {
+          title: `Read ${args.path}:${startLine}-${endLine}`,
+          metadata: { start_line: startLine, end_line: endLine, line_count: endLine - startLine + 1 },
+        };
+      }
+      const width = output.width;
+      const height = output.height;
+      if (typeof width === "number" && typeof height === "number") {
+        return { title: `Read ${args.path} (${width}x${height})`, metadata: { width, height } };
+      }
+      break;
+    }
+    case "map": {
+      const symbols = items(output.symbols).length;
+      return { title: `Mapped ${args.path} (${symbols} symbols)`, metadata: { symbols } };
+    }
+    case "search": {
+      const results = items(output.results);
+      const matches = results.reduce<number>((total, result) => total + items(record(result).matches).length, 0);
+      return { title: `Found ${matches} matches`, metadata: { results: results.length, matches } };
+    }
+    case "def": {
+      const locations = items(output.locations).length;
+      return { title: `Found ${locations} definitions`, metadata: { locations } };
+    }
+    case "refs": {
+      const references = items(output.references).length;
+      return { title: `Found ${references} references`, metadata: { references } };
+    }
+    case "hover": {
+      const identifier = record(output.identifier).text;
+      const line = output.line;
+      const column = output.column;
+      const metadata: Record<string, number> = {};
+      if (typeof line === "number") metadata.line = line;
+      if (typeof column === "number") metadata.column = column;
+      return { title: typeof identifier === "string" ? `Identified ${identifier}` : initialTitle(kind, args), metadata };
+    }
+    case "rename": {
+      const oldName = output.old_name;
+      const newName = output.new_name;
+      const otherOutputs = items(output.others).map(record);
+      const edits = otherOutputs.reduce((total, item) => total + items(item.edits).length, items(output.edits).length);
+      const conflicts = otherOutputs.reduce(
+        (total, item) => total + items(item.conflicts).length,
+        items(output.conflicts).length,
+      );
+      const others = otherOutputs.length;
+      const title =
+        typeof oldName === "string" && typeof newName === "string"
+          ? `Plan ${oldName} -> ${newName}`
+          : initialTitle(kind, args);
+      return { title, metadata: { edits, conflicts, others } };
+    }
+    case "check": {
+      const errors = typeof output.error_count === "number" ? output.error_count : 0;
+      const missing = typeof output.missing_count === "number" ? output.missing_count : 0;
+      return {
+        title: `Checked ${args.path} (${errors} errors, ${missing} missing)`,
+        metadata: { error_count: errors, missing_count: missing },
+      };
+    }
+  }
+  return { title: initialTitle(kind, args), metadata: {} };
+}
+
 function readseekTool(
   description: string,
   args: Record<string, any>,
-  execute: (args: any, directory: string) => Promise<unknown>,
+  kind: PresentationKind,
+  execute: (args: any, context: ToolContext) => Promise<unknown>,
 ) {
   return tool({
     description,
     args,
     async execute(args, context) {
-      return render(await execute(args, context.directory));
+      const title = initialTitle(kind, args);
+      context.metadata({ title });
+      const result = await execute(args, context);
+      const presentation = resultPresentation(kind, args, result);
+      return { title: presentation.title, output: render(result), metadata: presentation.metadata };
     },
   });
 }
@@ -112,9 +321,14 @@ function readseekTool(
  * Adds readseek's anchored reads and structural navigation without replacing
  * OpenCode's built-in file tools.
  */
-export const ReadSeekPlugin: Plugin = async () => {
+export const ReadSeekPlugin: Plugin = async (_input, options) => {
   const anchors = new SessionAnchors();
+  const imagePolicy = resolveImagePolicy(options);
+  const imageModes: readonly ImageMode[] = imagePolicy === "auto"
+    ? ["none", "ocr", "caption", "objects"]
+    : ["ocr", "caption", "objects"];
   const withSearchFlags = (args: string[], input: { cached?: boolean; others?: boolean; ignored?: boolean }) => {
+    if (input.ignored && !input.others) throw new Error("ignored requires others");
     optionalFlag(args, input.cached, "--cached");
     optionalFlag(args, input.others, "--others");
     optionalFlag(args, input.ignored, "--ignored");
@@ -123,23 +337,48 @@ export const ReadSeekPlugin: Plugin = async () => {
   return {
     tool: {
       readseek_read: readseekTool(
-        "Read a text file with stable LINE:HASH anchors. Use those anchors when describing a later edit.",
+        imagePolicy === "off"
+          ? "Read text with stable LINE:HASH anchors. Image and PDF files are skipped."
+          : `Read text with stable LINE:HASH anchors. For images and PDFs, explicitly select image: ${imageModes.join(", ")}; omitting image skips the file.`,
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           offset: tool.schema.number().int().positive().optional().describe("One-based starting line"),
           limit: tool.schema.number().int().positive().optional().describe("Maximum number of lines"),
+          ...(imagePolicy === "off"
+            ? {}
+            : {
+                image: tool.schema.enum(imageModes as [ImageMode, ...ImageMode[]]).optional()
+                  .describe(`Image/PDF mode: ${imageModes.join(", ")}. Must be selected explicitly.`),
+              }),
         },
-        async (input, directory) => {
-          const filePath = resolvePath(directory, input.path as string);
+        "read",
+        async (input, context) => {
+          const filePath = resolvePath(context.directory, input.path as string);
+          await authorizeRead(context, filePath);
+          const image = input.image as ImageMode | undefined;
+          if (imagePolicy === "off" && image !== undefined) throw new Error("image and PDF reads are disabled");
+          if (imagePolicy === "on" && image === "none") throw new Error('image="none" requires imageMode="auto"');
+          if (image === undefined) {
+            const detection = await runReadSeek(context, ["detect", filePath]);
+            if (isVisualFile(detection)) {
+              return { file: filePath, skipped: true, reason: "image mode not selected" };
+            }
+          }
           const args = ["read", input.offset === undefined ? filePath : `${filePath}:${input.offset}`];
-          if (input.limit !== undefined) args.push("--end", String((input.offset as number) + (input.limit as number) - 1));
-          return runReadSeek(directory, args);
+          if (input.limit !== undefined) args.push("--end", String((input.offset ?? 1) + input.limit - 1));
+          if (image !== undefined) args.push("--image", image);
+          return runReadSeek(context, args);
         },
       ),
       readseek_map: readseekTool(
         "Build a structural symbol map for a source file.",
         { path: tool.schema.string().describe("Path relative to the project directory") },
-        async (input, directory) => runReadSeek(directory, ["map", resolvePath(directory, input.path as string)]),
+        "map",
+        async (input, context) => {
+          const filePath = resolvePath(context.directory, input.path as string);
+          await authorizeRead(context, filePath);
+          return runReadSeek(context, ["map", filePath]);
+        },
       ),
       readseek_search: readseekTool(
         "Search source code using an ast-grep structural pattern. Results include LINE:HASH anchors.",
@@ -151,12 +390,14 @@ export const ReadSeekPlugin: Plugin = async () => {
           others: tool.schema.boolean().optional(),
           ignored: tool.schema.boolean().optional(),
         },
-        async (input, directory) => {
-          const target = resolvePath(directory, (input.path as string | undefined) ?? ".");
+        "search",
+        async (input, context) => {
+          const target = resolvePath(context.directory, (input.path as string | undefined) ?? ".");
           const args = ["search", target, input.pattern as string];
           if (input.language) args.push("--language", input.language as string);
           withSearchFlags(args, input);
-          const result = await runReadSeek(directory, args);
+          await authorizeSearch(context, target, input.pattern as string);
+          const result = await runReadSeek(context, args);
           return result;
         },
       ),
@@ -170,11 +411,14 @@ export const ReadSeekPlugin: Plugin = async () => {
           others: tool.schema.boolean().optional(),
           ignored: tool.schema.boolean().optional(),
         },
-        async (input, directory) => {
-          const args = ["def", resolvePath(directory, (input.path as string | undefined) ?? "."), "--format", "plain", input.name as string];
+        "def",
+        async (input, context) => {
+          const target = resolvePath(context.directory, (input.path as string | undefined) ?? ".");
+          const args = ["def", target, "--format", "plain", input.name as string];
           if (input.language) args.push("--language", input.language as string);
           withSearchFlags(args, input);
-          return runReadSeek(directory, args);
+          await authorizeSearch(context, target, input.name as string);
+          return runReadSeek(context, args);
         },
       ),
       readseek_refs: readseekTool(
@@ -190,14 +434,21 @@ export const ReadSeekPlugin: Plugin = async () => {
           others: tool.schema.boolean().optional(),
           ignored: tool.schema.boolean().optional(),
         },
-        async (input, directory) => {
-          const args = ["refs", resolvePath(directory, (input.path as string | undefined) ?? "."), input.name as string];
+        "refs",
+        async (input, context) => {
+          if (input.scope && input.line === undefined) throw new Error("scope requires line");
+          if (!input.scope && (input.line !== undefined || input.column !== undefined)) {
+            throw new Error("line and column require scope");
+          }
+          const target = resolvePath(context.directory, (input.path as string | undefined) ?? ".");
+          const args = ["refs", target, input.name as string];
           optionalFlag(args, input.scope as boolean | undefined, "--scope");
           if (input.line) args.push("--line", String(input.line));
           if (input.column) args.push("--column", String(input.column));
           if (input.language) args.push("--language", input.language as string);
           withSearchFlags(args, input);
-          return runReadSeek(directory, args);
+          await authorizeSearch(context, target, input.name as string);
+          return runReadSeek(context, args);
         },
       ),
       readseek_hover: readseekTool(
@@ -208,11 +459,14 @@ export const ReadSeekPlugin: Plugin = async () => {
           column: tool.schema.number().int().positive().optional().describe("One-based cursor byte column"),
           language: tool.schema.string().optional(),
         },
-        async (input, directory) => {
-          const args = ["identify", `${resolvePath(directory, input.path as string)}:${input.line}`];
+        "hover",
+        async (input, context) => {
+          const filePath = resolvePath(context.directory, input.path as string);
+          await authorizeRead(context, filePath);
+          const args = ["identify", `${filePath}:${input.line}`];
           if (input.column) args.push("--column", String(input.column));
           if (input.language) args.push("--language", input.language as string);
-          return runReadSeek(directory, args);
+          return runReadSeek(context, args);
         },
       ),
       readseek_rename: readseekTool(
@@ -224,22 +478,40 @@ export const ReadSeekPlugin: Plugin = async () => {
           to: tool.schema.string().min(1).describe("New binding name"),
           workspace: tool.schema.boolean().optional().describe("Include project-wide occurrences"),
         },
-        async (input, directory) => {
-          const args = ["rename", resolvePath(directory, input.path as string), "--line", String(input.line), "--to", input.to as string];
+        "rename",
+        async (input, context) => {
+          const filePath = resolvePath(context.directory, input.path as string);
+          await authorizeRead(context, filePath);
+          if (input.workspace) {
+            const identifyArgs = ["identify", `${filePath}:${input.line}`];
+            if (input.column) identifyArgs.push("--column", String(input.column));
+            const name = identifiedName(await runReadSeek(context, identifyArgs));
+            if (!name) throw new Error("readseek could not identify a binding at the rename cursor");
+            await authorizeSearch(context, context.directory, name);
+          }
+          const args = ["rename", filePath, "--line", String(input.line), "--to", input.to as string];
           if (input.column) args.push("--column", String(input.column));
-          if (input.workspace) args.push("--workspace", directory);
-          return runReadSeek(directory, args);
+          if (input.workspace) args.push("--workspace", context.directory);
+          return runReadSeek(context, args);
         },
       ),
       readseek_check: readseekTool(
         "Check a source file for parser errors and missing syntax.",
         { path: tool.schema.string().describe("Path relative to the project directory") },
-        async (input, directory) => runReadSeek(directory, ["check", resolvePath(directory, input.path as string)]),
+        "check",
+        async (input, context) => {
+          const filePath = resolvePath(context.directory, input.path as string);
+          await authorizeRead(context, filePath);
+          return runReadSeek(context, ["check", filePath]);
+        },
       ),
     },
     event: async ({ event }) => {
-      if (event.type !== "file.edited") return;
-      anchors.forget(path.resolve(event.properties.file));
+      if (event.type === "file.edited" || event.type === "file.watcher.updated") {
+        anchors.forget(event.properties.file);
+        return;
+      }
+      if (event.type === "session.deleted") anchors.deleteSession(event.properties.info.id);
     },
     "tool.execute.before": async (input, output) => {
       if (input.tool === "readseek_rename" && output.args.apply === true) {

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "opencode-readseek",
-  "version": "0.5.19",
+  "version": "0.6.1",
   "description": "OpenCode plugin for readseek-backed structural code navigation",
   "type": "module",
   "exports": {
-    ".": "./index.ts"
+    ".": "./index.ts",
+    "./server": "./index.ts"
   },
   "keywords": [
     "opencode",
@@ -28,7 +29,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.5.19",
+    "@jarkkojs/readseek": "^0.6.1",
     "@opencode-ai/plugin": "^1.17.20"
   },
   "devDependencies": {