opencode-readseek 0.9.4 → 0.9.5

package/index.ts

@@ -1,1663 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (C) Jarkko Sakkinen 2026
-
-import { lstat, mkdir, open, readFile, readlink, realpath, stat } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { homedir } from "node:os";
-import path from "node:path";
-
-import { tool, type Plugin, type PluginOptions, type ToolAttachment, type ToolContext } from "@opencode-ai/plugin";
-
-const require = createRequire(import.meta.url);
-const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
-const DEFAULT_READSEEK_TIMEOUT_MS = 120_000;
-const DEFAULT_VISION_TIMEOUT_MS = 30 * 60 * 1000;
-const DEFAULT_READ_LIMIT = 2000;
-const EDIT_RESULT_READ_LIMIT = 40;
-const MAX_DOCUMENT_OUTPUT_BYTES = 256 * 1024;
-const MAX_DOCUMENT_OUTPUT_LINES = 2000;
-const TOOL_POLICY = [
-  "ReadSeek tool policy:",
-  "- Prefer readseek_* tools over built-ins when they can do the job.",
-  "- Read with readseek_read first; readseek_edit needs fresh LINE:HASH anchors.",
-  "- Use readseek_grep for text/regex, readseek_search for AST patterns, and readseek_digest/def/refs for symbol navigation.",
-  "- Use readseek_edit for existing files, readseek_write for whole-file creation or replacement, and readseek_rename for symbol renames.",
-  "- Do not use built-in read, edit, write, grep, or apply_patch when a ReadSeek tool can do the job.",
-  "- Run readseek_digest with select=diagnostics after source edits for a quick syntax check.",
-].join("\n");
-const PREFERRED_TOOL_DESCRIPTIONS: Record<string, string> = {
-  readseek_read: "Preferred file reader; returns LINE:HASH anchors for durable references.",
-  readseek_edit: "Preferred tool for editing existing text files with fresh LINE:HASH anchors.",
-  readseek_write: "Preferred tool for creating or replacing a complete text file; returns LINE:HASH anchors.",
-  readseek_rename: "Use to rename a symbol with binding-aware, verified edits.",
-  readseek_grep: "Preferred text/regex search; returns edit-ready LINE:HASH anchors.",
-  readseek_search: "Use for AST or structural code search with ast-grep-style patterns.",
-  readseek_digest: "Use to digest native facets (metadata, content, map, diagnostics, identity) and return the full envelope.",
-  readseek_def: "Use for go-to-definition or declaration lookup by name.",
-  readseek_refs: "Use to find identifier-name matches or binding-specific references before rename or delete.",
-  readseek_view: "Use to digest document structure or selected content.",
-};
-const FALLBACK_TOOL_DESCRIPTIONS: Record<string, string> = {
-  read: "Fallback only. Prefer readseek_read so edits can use LINE:HASH anchors.",
-  edit: "Fallback only. Prefer readseek_edit with fresh LINE:HASH anchors.",
-  write: "Fallback only. Prefer readseek_write so the result returns LINE:HASH anchors.",
-  grep: "Fallback only. Prefer readseek_grep for text/regex search with edit-ready anchors.",
-  apply_patch: "Fallback only. Prefer readseek_edit for existing text files.",
-};
-const READSEEK_PLATFORM_PACKAGES: Record<string, string> = {
-  "darwin-arm64": "@jarkkojs/readseek-darwin-arm64",
-  "linux-arm64": "@jarkkojs/readseek-linux-arm64",
-  "linux-x64": "@jarkkojs/readseek-linux-x64",
-  "win32-x64": "@jarkkojs/readseek-win32-x64",
-};
-
-type RenamePlan = {
-  summary: string;
-  files: Set<string>;
-};
-
-type PresentationKind = "read" | "view" | "digest" | "search" | "grep" | "def" | "refs" | "rename" | "edit" | "write";
-
-type Presentation = {
-  title: string;
-  metadata: Record<string, number>;
-};
-
-type RenderedToolResult = {
-  output: string;
-  attachments?: ToolAttachment[];
-};
-
-type ImagePolicy = "on" | "auto" | "off";
-type ImageMode = "none" | "all" | "ocr" | "caption" | "objects";
-type VisionAnalysisMode = Exclude<ImageMode, "none">;
-type VisionLevel = "low" | "medium" | "high";
-type DocumentNodeKind = "artifact" | "footer" | "header" | "heading" | "marginal_label" | "page" | "page_number" | "paragraph" | "section" | "structural_section";
-const VISION_ANALYSIS_MODES: [VisionAnalysisMode, ...VisionAnalysisMode[]] = ["all", "ocr", "caption", "objects"];
-const VISION_LEVELS: [VisionLevel, ...VisionLevel[]] = ["low", "medium", "high"];
-
-const DOCUMENT_NODE_KINDS: [DocumentNodeKind, ...DocumentNodeKind[]] = [
-  "artifact",
-  "footer",
-  "header",
-  "heading",
-  "marginal_label",
-  "page",
-  "page_number",
-  "paragraph",
-  "section",
-  "structural_section",
-];
-
-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"
-    || (typeof type === "string" && type.startsWith("image/"));
-}
-
-function isVisualBoundsError(error: unknown): boolean {
-  if (!(error instanceof Error)) return false;
-  const message = error.message.replace(/^error:\s*/, "");
-  return message.startsWith("--end")
-    && /(?:does|do) not apply to images/.test(message);
-}
-
-function isDocumentBoundsError(error: unknown): boolean {
-  if (!(error instanceof Error)) return false;
-  const message = error.message.replace(/^error:\s*/, "");
-  return /(?:does|do) not apply to (?:documents|PDFs)/.test(message)
-    || /document content belongs to view/.test(message)
-    || /source facets do not apply to documents/.test(message);
-}
-
-function isPdfFile(value: unknown): boolean {
-  const output = record(value);
-  return output.format === "pdf" || output.type === "application/pdf";
-}
-
-function documentReceipt(filePath: string, envelope: unknown): Record<string, unknown> {
-  const recordEnvelope = record(envelope);
-  return {
-    file: filePath,
-    use: "readseek_view",
-    reason: "document content belongs to readseek_view",
-    metadata: digestMetadata(envelope),
-    ...(recordEnvelope.cache !== undefined ? { cache: recordEnvelope.cache } : {}),
-  };
-}
-
-async function digestDocumentReceipt(context: ToolContext, filePath: string): Promise<Record<string, unknown>> {
-  const cacheDir = await ensureReadSeekCache(context);
-  const envelope = await runReadSeek(context, [
-    "--readseek-dir",
-    cacheDir,
-    ...digestArgs(filePath, "metadata"),
-  ]);
-  return documentReceipt(filePath, envelope);
-}
-
-function digestArgs(filePath: string, select: string, extra: string[] = []): string[] {
-  return ["digest", filePath, "--select", select, ...extra];
-}
-
-function requireDigestFacet(envelope: unknown, facet: "content" | "map" | "diagnostics" | "identity"): unknown {
-  const value = record(envelope)[facet];
-  if (value === undefined || value === null || typeof value !== "object") {
-    throw new Error(`digest returned no ${facet} facet`);
-  }
-  return value;
-}
-
-function digestMetadata(envelope: unknown): Record<string, unknown> {
-  return record(record(envelope).metadata);
-}
-
-class SessionAnchors {
-  #pathsBySession = new Map<string, Set<string>>();
-  #renamePlans = new Map<string, RenamePlan>();
-
-  mark(sessionID: string, filePath: string): void {
-    let paths = this.#pathsBySession.get(sessionID);
-    if (!paths) {
-      paths = new Set<string>();
-      this.#pathsBySession.set(sessionID, paths);
-    }
-    paths.add(filePath);
-  }
-
-  forget(filePath: string): void {
-    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 record = output as Record<string, unknown>;
-    if (record.applied === true) {
-      this.#renamePlans.delete(sessionID);
-      return;
-    }
-    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 {
-    const paths = this.#pathsBySession.get(sessionID);
-    const sections: string[] = [];
-    if (paths?.size) {
-      sections.push(`## ReadSeek Anchors\nThe following files have fresh LINE:HASH anchors:\n${[...paths]
-      .sort()
-      .map((filePath) => `- ${filePath}`)
-      .join("\n")}`);
-    }
-    const renamePlan = this.#renamePlans.get(sessionID);
-    if (renamePlan) sections.push(`## Pending ReadSeek Rename Plan\n- ${renamePlan.summary}`);
-    return sections.length === 0 ? undefined : sections.join("\n\n");
-  }
-}
-
-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 resolveSymlinks(filePath: string): Promise<string> {
-  let unresolved = path.resolve(filePath);
-  let symlinks = 0;
-
-  while (true) {
-    const parsed = path.parse(unresolved);
-    const parts = unresolved.slice(parsed.root.length).split(path.sep).filter(Boolean);
-    let resolved = parsed.root;
-    let restart = false;
-
-    for (let index = 0; index < parts.length; index++) {
-      const candidate = path.join(resolved, parts[index]);
-      const info = await lstat(candidate);
-      if (!info.isSymbolicLink()) {
-        resolved = candidate;
-        continue;
-      }
-
-      symlinks++;
-      if (symlinks > 40) {
-        const error = new Error(`too many symbolic links: ${filePath}`) as NodeJS.ErrnoException;
-        error.code = "ELOOP";
-        throw error;
-      }
-
-      const target = await readlink(candidate);
-      unresolved = path.resolve(path.dirname(candidate), target, ...parts.slice(index + 1));
-      restart = true;
-      break;
-    }
-
-    if (!restart) return resolved;
-  }
-}
-
-async function portableRealpath(filePath: string): Promise<string> {
-  try {
-    return await realpath(filePath);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EACCES") throw error;
-    return resolveSymlinks(filePath);
-  }
-}
-
-async function canonicalPath(filePath: string): Promise<string> {
-  const missing: string[] = [];
-  let existing = filePath;
-  while (true) {
-    try {
-      return path.join(await portableRealpath(existing), ...missing.reverse());
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-      const parent = path.dirname(existing);
-      if (parent === existing) throw error;
-      missing.push(path.basename(existing));
-      existing = parent;
-    }
-  }
-}
-
-async function authorizeExternal(context: ToolContext, filePath: string): Promise<void> {
-  const [accessPath, directory, worktree] = await Promise.all([
-    canonicalPath(filePath),
-    canonicalPath(context.directory),
-    context.worktree === "/" ? Promise.resolve("/") : canonicalPath(context.worktree),
-  ]);
-  if (containsPath(directory, accessPath) || (worktree !== "/" && containsPath(worktree, accessPath))) {
-    return;
-  }
-
-  const info = await stat(accessPath).catch(() => undefined);
-  const parentDir = info?.isDirectory() ? accessPath : path.dirname(accessPath);
-  const pattern = path.join(parentDir, "*").replaceAll("\\", "/");
-  await context.ask({
-    permission: "external_directory",
-    patterns: [pattern],
-    always: [pattern],
-    metadata: { filepath: filePath, parentDir },
-  });
-}
-
-async function rejectSymlinkMutation(filePath: string): Promise<void> {
-  const info = await lstat(filePath).catch((error: NodeJS.ErrnoException) => {
-    if (error.code === "ENOENT") return undefined;
-    throw error;
-  });
-  if (info?.isSymbolicLink()) throw new Error(`refusing to modify symbolic link: ${filePath}`);
-}
-
-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);
-}
-
-async function authorizeEdit(
-  context: ToolContext,
-  filePaths: string[],
-  diff = "",
-  authorizeExternalPaths = true,
-): Promise<void> {
-  if (authorizeExternalPaths) {
-    for (const filePath of filePaths) await authorizeExternal(context, filePath);
-  }
-  const patterns = filePaths.map((filePath) => path.relative(context.worktree, filePath).replaceAll("\\", "/"));
-  await context.ask({
-    permission: "edit",
-    patterns,
-    always: ["*"],
-    metadata: { filepath: filePaths.join(", "), diff },
-  });
-}
-
-function optionalFlag(args: string[], enabled: boolean | undefined, flag: string): void {
-  if (enabled) args.push(flag);
-}
-
-function atLocation(line: number, column?: number): string {
-  return column === undefined ? `line:${line}` : `line:${line}:${column}`;
-}
-
-function withAt(args: string[], line: number, column?: number): void {
-  args.push("--at", atLocation(line, column));
-}
-
-function isLikelyImagePath(filePath: string): boolean {
-  return /\.(avif|bmp|gif|heic|heif|ico|jpe?g|png|svg|tiff?|webp)$/i.test(filePath);
-}
-
-function isLikelyDocumentPath(filePath: string): boolean {
-  return /\.pdf$/i.test(filePath);
-}
-
-function readRangeArgs(filePath: string, start: number, end: number): string[] {
-  const extra: string[] = [];
-  if (start > 1) withAt(extra, start);
-  extra.push("--end", String(end));
-  return digestArgs(filePath, "content", extra);
-}
-
-async function runDigestContent(
-  context: ToolContext,
-  args: string[],
-  options: { cancelable?: boolean; timeoutMs?: number } = {},
-): Promise<unknown> {
-  return requireDigestFacet(await runReadSeek(context, args, options), "content");
-}
-
-function readSeekBinaryPath(): string {
-  const platform = `${process.platform}-${process.arch}`;
-  const platformPackage = READSEEK_PLATFORM_PACKAGES[platform];
-  if (!platformPackage) {
-    throw new Error(`@jarkkojs/readseek ships no binary for ${platform}`);
-  }
-
-  const readseekPackageDir = path.dirname(require.resolve("@jarkkojs/readseek/package.json"));
-  const packageJson = require.resolve(`${platformPackage}/package.json`, { paths: [readseekPackageDir] });
-  return path.join(path.dirname(packageJson), "bin", process.platform === "win32" ? "readseek.exe" : "readseek");
-}
-
-async function readBoundedText(
-  stream: ReadableStream<Uint8Array>,
-  streamName: "stdout" | "stderr",
-  onOverflow: () => void,
-): Promise<string> {
-  const reader = stream.getReader();
-  const chunks: Uint8Array[] = [];
-  let totalBytes = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      totalBytes += value.byteLength;
-      if (totalBytes > MAX_OUTPUT_BYTES) {
-        onOverflow();
-        await reader.cancel().catch(() => undefined);
-        throw new Error(`readseek ${streamName} exceeded the ${MAX_OUTPUT_BYTES}-byte output limit`);
-      }
-      chunks.push(value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
-
-  const bytes = new Uint8Array(totalBytes);
-  let offset = 0;
-  for (const chunk of chunks) {
-    bytes.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return new TextDecoder().decode(bytes);
-}
-
-async function runReadSeekRaw(
-  context: ToolContext,
-  args: string[],
-  options: { cancelable?: boolean; stdin?: string; timeoutMs?: number } = {},
-): Promise<string> {
-  context.abort.throwIfAborted();
-  const cancelable = options.cancelable !== false;
-  const spawnOptions = {
-    cwd: context.directory,
-    stderr: "pipe" as const,
-    stdin: options.stdin === undefined ? undefined : Buffer.from(options.stdin),
-    stdout: "pipe" as const,
-  };
-  const child = Bun.spawn(
-    [readSeekBinaryPath(), ...args],
-    cancelable
-      ? { ...spawnOptions, killSignal: "SIGKILL" as const, signal: context.abort }
-      : spawnOptions,
-  );
-  let killedForOverflow = false;
-  const killForOverflow = () => {
-    if (killedForOverflow) return;
-    killedForOverflow = true;
-    try {
-      child.kill("SIGKILL");
-    } catch {
-      // Preserve the output-limit error if the process exited concurrently.
-    }
-  };
-  const timeoutMs = options.timeoutMs ?? DEFAULT_READSEEK_TIMEOUT_MS;
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  const timeoutResult = new Promise<never>((_resolve, reject) => {
-    timeout = setTimeout(() => {
-      try {
-        child.kill("SIGKILL");
-      } catch {
-        // Preserve the timeout error if the process exited concurrently.
-      }
-      reject(new Error(`readseek timed out after ${timeoutMs} ms`));
-    }, timeoutMs);
-    timeout.unref?.();
-  });
-  const pending = Promise.all([
-    readBoundedText(child.stdout, "stdout", killForOverflow),
-    readBoundedText(child.stderr, "stderr", killForOverflow),
-    child.exited,
-  ]);
-  let result: Awaited<typeof pending>;
-  try {
-    result = await Promise.race([pending, timeoutResult]);
-  } finally {
-    if (timeout !== undefined) clearTimeout(timeout);
-  }
-  const [stdout, stderr, exitCode] = result;
-  if (cancelable) context.abort.throwIfAborted();
-  if (exitCode !== 0) throw new Error(stderr.trim() || `readseek exited with status ${exitCode}`);
-  return stdout;
-}
-
-async function runReadSeek(
-  context: ToolContext,
-  args: string[],
-  options: { cancelable?: boolean; stdin?: string; timeoutMs?: number } = {},
-): Promise<unknown> {
-  const stdout = await runReadSeekRaw(context, args, options);
-  try {
-    return JSON.parse(stdout) as unknown;
-  } catch {
-    throw new Error(`readseek returned invalid JSON: ${stdout.trim()}`);
-  }
-}
-
-async function postMutationPreview(
-  context: ToolContext,
-  args: string[],
-  filePath: string,
-  changed: boolean,
-): Promise<unknown> {
-  try {
-    return await runDigestContent(context, args, {
-      cancelable: false,
-      timeoutMs: DEFAULT_READSEEK_TIMEOUT_MS,
-    });
-  } catch (error) {
-    const previewError = error instanceof Error ? error.message : String(error);
-    return {
-      file: filePath,
-      changed,
-      preview_error: previewError,
-      warning: "File mutation completed, but the post-write preview failed. Do not retry the mutation; read the file to verify content and refresh anchors.",
-    };
-  }
-}
-
-let readSeekCacheInit: Promise<string> | undefined;
-
-function readSeekCacheDir(): string {
-  const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
-  const cacheHome = xdgCacheHome || path.join(homedir(), ".cache");
-  return path.join(cacheHome, "opencode", "readseek");
-}
-
-async function ensureReadSeekCache(context: ToolContext): Promise<string> {
-  const cacheDir = readSeekCacheDir();
-  try {
-    const info = await stat(cacheDir);
-    if (!info.isDirectory()) throw new Error(`readseek cache is not a directory: ${cacheDir}`);
-    return cacheDir;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-  }
-
-  readSeekCacheInit ??= runReadSeekRaw(context, ["--readseek-dir", cacheDir, "init"])
-    .then(() => cacheDir)
-    .finally(() => {
-      readSeekCacheInit = undefined;
-    });
-  return readSeekCacheInit;
-}
-
-function render(value: unknown): string {
-  return JSON.stringify(value, null, 2);
-}
-
-function collectAnchoredFiles(value: unknown, files: Set<string>): void {
-  if (Array.isArray(value)) {
-    for (const item of value) collectAnchoredFiles(item, files);
-    return;
-  }
-  if (!value || typeof value !== "object") return;
-
-  const output = value as Record<string, unknown>;
-  const hashlines = output.hashlines;
-  if (
-    typeof output.file === "string" &&
-    Array.isArray(hashlines) &&
-    hashlines.some((line) => typeof record(line).line === "number" && typeof record(line).hash === "string")
-  ) files.add(output.file);
-  for (const item of Object.values(output)) collectAnchoredFiles(item, files);
-}
-
-type AnchorEdit =
-  | { set_line: { anchor: string; new_text: string } }
-  | { replace_lines: { start_anchor: string; end_anchor: string; new_text: string } }
-  | { insert_after: { anchor: string; new_text: string } };
-
-type EditItem =
-  | AnchorEdit
-  | { replace: { old_text: string; new_text: string; all?: boolean } }
-  | { replace_symbol: { symbol: string; new_body: string } };
-
-type TextSnapshot = {
-  exists: boolean;
-  content: string;
-};
-
-const fileMutationTails = new Map<string, Promise<void>>();
-const MAX_PERMISSION_DIFF_BYTES = 32 * 1024;
-
-async function withFileMutationQueue<T>(filePath: string, operation: () => Promise<T>): Promise<T> {
-  const key = path.resolve(filePath);
-  const previous = fileMutationTails.get(key);
-  let release = () => {};
-  const current = new Promise<void>((resolve) => {
-    release = resolve;
-  });
-  fileMutationTails.set(key, current);
-  if (previous) await previous;
-  try {
-    return await operation();
-  } finally {
-    release();
-    if (fileMutationTails.get(key) === current) fileMutationTails.delete(key);
-  }
-}
-
-function validateEdits(value: unknown): asserts value is EditItem[] {
-  if (!Array.isArray(value) || value.length === 0) throw new Error("edits must contain at least one edit");
-  const requiredFields = {
-    set_line: ["anchor", "new_text"],
-    replace_lines: ["end_anchor", "new_text", "start_anchor"],
-    insert_after: ["anchor", "new_text"],
-    replace: ["new_text", "old_text"],
-    replace_symbol: ["new_body", "symbol"],
-  } as const;
-  for (const [index, item] of value.entries()) {
-    if (!item || typeof item !== "object") throw new Error(`edits[${index}] must be an edit object`);
-    const keys = Object.keys(item);
-    const variant = keys[0] as keyof typeof requiredFields;
-    if (keys.length !== 1 || !Object.hasOwn(requiredFields, variant)) {
-      throw new Error(`edits[${index}] must contain exactly one of: set_line, replace_lines, insert_after, replace, replace_symbol`);
-    }
-    const payload = (item as Record<string, unknown>)[variant];
-    if (!payload || typeof payload !== "object") throw new Error(`edits[${index}].${variant} must be an object`);
-    const expectedFields: readonly string[] = requiredFields[variant];
-    const allowedFields = variant === "replace" ? [...expectedFields, "all"] : expectedFields;
-    const actualFields = Object.keys(payload).sort();
-    if (actualFields.some((field) => !allowedFields.includes(field)) || expectedFields.some((field) => !actualFields.includes(field))) {
-      throw new Error(`edits[${index}].${variant} contains invalid fields`);
-    }
-    const values = payload as Record<string, unknown>;
-    for (const field of expectedFields) {
-      if (typeof values[field] !== "string") {
-        throw new Error(`edits[${index}].${variant}.${field} must be a string`);
-      }
-    }
-    if (variant === "replace" && values.all !== undefined && typeof values.all !== "boolean") {
-      throw new Error(`edits[${index}].replace.all must be a boolean`);
-    }
-    for (const field of expectedFields.filter((field) => field.endsWith("anchor"))) {
-      parseAnchor(values[field] as string);
-    }
-  }
-}
-
-function parseAnchor(anchor: string): { line: number; hash: string } {
-  const match = /^(\d+):([0-9a-fA-F]{3})$/.exec(anchor.trim());
-  if (!match) throw new Error(`invalid LINE:HASH anchor: ${anchor}`);
-  const line = Number(match[1]);
-  if (line === 0) throw new Error(`anchor line must be greater than zero: ${anchor}`);
-  return { line, hash: match[2].toLowerCase() };
-}
-
-function firstChangedLine(before: string, after: string): number {
-  const beforeLines = normalizeToLf(before).split("\n");
-  const afterLines = normalizeToLf(after).split("\n");
-  const count = Math.max(beforeLines.length, afterLines.length);
-  for (let index = 0; index < count; index++) {
-    if (beforeLines[index] !== afterLines[index]) return index + 1;
-  }
-  return 1;
-}
-
-
-async function readTextSnapshot(filePath: string): Promise<TextSnapshot> {
-  try {
-    return { exists: true, content: await readFile(filePath, "utf8") };
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { exists: false, content: "" };
-    throw error;
-  }
-}
-
-async function writeHandle(handle: Awaited<ReturnType<typeof open>>, content: string): Promise<void> {
-  const data = Buffer.from(content, "utf8");
-  await handle.truncate(0);
-  let offset = 0;
-  while (offset < data.length) {
-    const { bytesWritten } = await handle.write(data, offset, data.length - offset, offset);
-    if (bytesWritten === 0) throw new Error("write made no progress");
-    offset += bytesWritten;
-  }
-}
-
-async function writeText(filePath: string, expected: TextSnapshot, content: string): Promise<void> {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  if (!expected.exists) {
-    let handle: Awaited<ReturnType<typeof open>>;
-    try {
-      handle = await open(filePath, "wx+");
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "EEXIST") {
-        throw new Error(`refusing to overwrite changed file: ${filePath}`);
-      }
-      throw error;
-    }
-    try {
-      await writeHandle(handle, content);
-    } finally {
-      await handle.close();
-    }
-    return;
-  }
-
-  const pathInfo = await lstat(filePath);
-  if (pathInfo.isSymbolicLink()) throw new Error(`refusing to modify symbolic link: ${filePath}`);
-  const handle = await open(filePath, "r+");
-  try {
-    const handleInfo = await handle.stat();
-    const currentPathInfo = await lstat(filePath);
-    if (
-      currentPathInfo.isSymbolicLink() ||
-      currentPathInfo.dev !== handleInfo.dev ||
-      currentPathInfo.ino !== handleInfo.ino
-    ) {
-      throw new Error(`refusing to overwrite changed file: ${filePath}`);
-    }
-    const current = (await handle.readFile()).toString("utf8");
-    if (current !== expected.content) throw new Error(`refusing to overwrite changed file: ${filePath}`);
-    if (current !== content) await writeHandle(handle, content);
-  } finally {
-    await handle.close();
-  }
-}
-
-function renameFiles(value: unknown): string[] {
-  const output = record(value);
-  const files: string[] = [];
-  if (typeof output.file === "string" && items(output.edits).length > 0) files.push(path.resolve(output.file));
-  for (const other of items(output.others)) {
-    const item = record(other);
-    if (typeof item.file === "string" && items(item.edits).length > 0) files.push(path.resolve(item.file));
-  }
-  return files;
-}
-
-function normalizeToLf(content: string): string {
-  return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-}
-
-function diffLines(content: string): string[] {
-  if (content === "") return [];
-  const lines = content.split("\n");
-  if (lines.at(-1) === "") lines.pop();
-  return lines.map((line) => line.replace(/\r/g, "\\r"));
-}
-
-function hasFinalNewline(content: string): boolean {
-  return content === "" || /[\r\n]$/.test(content);
-}
-
-function diffRange(start: number, count: number): string {
-  return count === 0 ? `${start},0` : `${start + 1},${count}`;
-}
-
-function utf8Prefix(value: string, maxBytes: number): string {
-  const bytes = Buffer.from(value, "utf8");
-  if (bytes.length <= maxBytes) return value;
-  let end = maxBytes;
-  const decoder = new TextDecoder("utf-8", { fatal: true });
-  while (end > 0) {
-    try {
-      return decoder.decode(bytes.subarray(0, end));
-    } catch {
-      end--;
-    }
-  }
-  return "";
-}
-
-function boundDocumentOutput(value: string): string {
-  const lines = value.split("\n");
-  let output = lines.length > MAX_DOCUMENT_OUTPUT_LINES
-    ? lines.slice(0, MAX_DOCUMENT_OUTPUT_LINES).join("\n")
-    : value;
-  const truncated = output !== value || Buffer.byteLength(output, "utf8") > MAX_DOCUMENT_OUTPUT_BYTES;
-  output = utf8Prefix(output, MAX_DOCUMENT_OUTPUT_BYTES);
-  return truncated
-    ? `${output}\n[… document view truncated; narrow it with page, node, kind, or depth]`
-    : output;
-}
-
-function attachmentExtension(mime: string): string {
-  switch (mime) {
-    case "image/gif":
-      return "gif";
-    case "image/jpeg":
-      return "jpg";
-    case "image/png":
-      return "png";
-    case "image/webp":
-      return "webp";
-    default:
-      return "bin";
-  }
-}
-
-function imageAttachment(image: Record<string, unknown>, filename: string): ToolAttachment | undefined {
-  if (image.encoding !== "base64" || typeof image.data !== "string" || typeof image.mime !== "string") {
-    return undefined;
-  }
-  return {
-    type: "file",
-    mime: image.mime,
-    url: `data:${image.mime};base64,${image.data}`,
-    filename: `${filename}.${attachmentExtension(image.mime)}`,
-  };
-}
-
-function formatReadResult(value: unknown): RenderedToolResult {
-  const output = record(value);
-  if (output.use === "readseek_view") return { output: render(value) };
-
-  const attachment = imageAttachment(output, "image");
-  if (!attachment) return { output: render(value) };
-  const sanitized = { ...output };
-  delete sanitized.data;
-  delete sanitized.encoding;
-  return { output: render(sanitized), attachments: [attachment] };
-}
-
-function previewDiffLine(prefix: string, line: string): string {
-  const value = `${prefix}${line}`;
-  const maxBytes = 256;
-  if (Buffer.byteLength(value) <= maxBytes) return value;
-  return `${utf8Prefix(value, maxBytes - Buffer.byteLength("…"))}…`;
-}
-
-function sampleDiffLines(lines: string[], start: number, end: number, prefix: string): string[] {
-  const sampleSize = 20;
-  const count = end - start;
-  if (count <= sampleSize * 2) {
-    return lines.slice(start, end).map((line) => previewDiffLine(prefix, line));
-  }
-  return [
-    ...lines.slice(start, start + sampleSize).map((line) => previewDiffLine(prefix, line)),
-    ` ${count - sampleSize * 2} ${prefix === "-" ? "removed" : "added"} lines omitted`,
-    ...lines.slice(end - sampleSize, end).map((line) => previewDiffLine(prefix, line)),
-  ];
-}
-
-function simpleDiff(filePath: string, before: string, after: string): string {
-  if (before === after) return "";
-  const oldLines = diffLines(before);
-  const newLines = diffLines(after);
-  const oldHasFinalNewline = hasFinalNewline(before);
-  const newHasFinalNewline = hasFinalNewline(after);
-  let prefix = 0;
-  while (prefix < oldLines.length && prefix < newLines.length && oldLines[prefix] === newLines[prefix]) prefix++;
-  let suffix = 0;
-  while (
-    suffix < oldLines.length - prefix &&
-    suffix < newLines.length - prefix &&
-    oldLines[oldLines.length - 1 - suffix] === newLines[newLines.length - 1 - suffix]
-  ) suffix++;
-  if (prefix === oldLines.length && prefix === newLines.length) {
-    prefix = Math.max(0, prefix - 1);
-    suffix = 0;
-  }
-
-  const oldChangeEnd = oldLines.length - suffix;
-  const newChangeEnd = newLines.length - suffix;
-  const oldStart = Math.max(0, prefix - 3);
-  const newStart = Math.max(0, prefix - 3);
-  const oldEnd = Math.min(oldLines.length, oldChangeEnd + 3);
-  const newEnd = Math.min(newLines.length, newChangeEnd + 3);
-  const safePath = utf8Prefix(filePath.replace(/[\r\n]/g, ""), 1024);
-  const header = [
-    `--- ${safePath}`,
-    `+++ ${safePath}`,
-    `@@ -${diffRange(oldStart, oldEnd - oldStart)} +${diffRange(newStart, newEnd - newStart)} @@`,
-  ];
-  const fullDiff = [...header];
-  let fullDiffBytes = Buffer.byteLength(header.join("\n"));
-  let complete = true;
-  const ranges: Array<[string[], number, number, string, boolean]> = [
-    [oldLines, oldStart, prefix, " ", oldHasFinalNewline],
-    [oldLines, prefix, oldChangeEnd, "-", oldHasFinalNewline],
-    [newLines, prefix, newChangeEnd, "+", newHasFinalNewline],
-    [newLines, newChangeEnd, newEnd, " ", newHasFinalNewline],
-  ];
-  outer: for (const [lines, start, end, marker, hasNewline] of ranges) {
-    for (let index = start; index < end; index++) {
-      const lineBytes = 2 + Buffer.byteLength(lines[index]);
-      if (fullDiffBytes + lineBytes > MAX_PERMISSION_DIFF_BYTES) {
-        complete = false;
-        break outer;
-      }
-      fullDiff.push(`${marker}${lines[index]}`);
-      fullDiffBytes += lineBytes;
-      if (index === lines.length - 1 && !hasNewline) {
-        const eofMarker = "\";
-        if (fullDiffBytes + Buffer.byteLength(eofMarker) + 1 > MAX_PERMISSION_DIFF_BYTES) {
-          complete = false;
-          break outer;
-        }
-        fullDiff.push(eofMarker);
-        fullDiffBytes += Buffer.byteLength(eofMarker) + 1;
-      }
-    }
-  }
-  if (complete) return fullDiff.join("\n");
-
-  const newlineSummary = oldHasFinalNewline === newHasFinalNewline
-    ? []
-    : [` final newline: ${oldHasFinalNewline ? "present" : "missing"} -> ${newHasFinalNewline ? "present" : "missing"}`];
-  return [
-    ...header,
-    ` diff truncated: ${oldChangeEnd - prefix} removed, ${newChangeEnd - prefix} added lines`,
-    ...newlineSummary,
-    ...sampleDiffLines(oldLines, prefix, oldChangeEnd, "-"),
-    ...sampleDiffLines(newLines, prefix, newChangeEnd, "+"),
-  ].join("\n");
-}
-
-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 "view":
-      return `View ${args.path}`;
-    case "digest":
-      return `Digest ${args.path}`;
-    case "search":
-      return `Search ${args.pattern}`;
-    case "grep":
-      return `Grep ${args.pattern}`;
-    case "def":
-      return `Find definition ${args.name}`;
-    case "refs":
-      return `Find references to ${args.name}`;
-    case "rename":
-      return `Rename ${args.path}:${args.line} to ${args.to}`;
-    case "edit":
-      return `Edit ${args.path}`;
-    case "write":
-      return `Write ${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 "view":
-      return { title: `Viewed ${args.path}`, metadata: {} };
-    case "digest": {
-      const map = record(output.map);
-      const diagnostics = record(output.diagnostics);
-      const identity = record(output.identity);
-      const content = record(output.content);
-      const metadata: Record<string, number> = {};
-      const summary: string[] = [];
-      if (output.map !== undefined) {
-        const symbols = items(map.symbols).length;
-        metadata.symbols = symbols;
-        summary.push(`${symbols} symbols`);
-      }
-      if (output.diagnostics !== undefined) {
-        const errors = typeof diagnostics.error_count === "number" ? diagnostics.error_count : 0;
-        const missing = typeof diagnostics.missing_count === "number" ? diagnostics.missing_count : 0;
-        metadata.error_count = errors;
-        metadata.missing_count = missing;
-        summary.push(`${errors} errors, ${missing} missing`);
-      }
-      if (output.identity !== undefined) {
-        if (typeof identity.line === "number") metadata.line = identity.line;
-        if (typeof identity.column === "number") metadata.column = identity.column;
-        const identifier = record(identity.identifier).text;
-        if (typeof identifier === "string") summary.push(identifier);
-      }
-      if (typeof content.start_line === "number") metadata.start_line = content.start_line;
-      if (typeof content.end_line === "number") metadata.end_line = content.end_line;
-      return {
-        title: summary.length > 0 ? `Digested ${args.path} (${summary.join(", ")})` : `Digested ${args.path}`,
-        metadata,
-      };
-    }
-    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 "grep": {
-      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 "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"
-          ? `${output.applied === true ? "Renamed" : "Plan"} ${oldName} -> ${newName}`
-          : initialTitle(kind, args);
-      return { title, metadata: { edits, conflicts, others } };
-    }
-    case "edit":
-    case "write": {
-      const preview = typeof output.preview_error === "string" ? " (preview unavailable)" : "";
-      return { title: `${kind === "edit" ? "Edited" : "Wrote"} ${args.path}${preview}`, metadata: {} };
-    }
-  }
-  return { title: initialTitle(kind, args), metadata: {} };
-}
-
-function readseekTool(
-  description: string,
-  args: Record<string, any>,
-  kind: PresentationKind,
-  execute: (args: any, context: ToolContext) => Promise<unknown>,
-  formatResult: (result: unknown) => RenderedToolResult = (result) => ({ output: render(result) }),
-) {
-  return tool({
-    description,
-    args,
-    async execute(args, context) {
-      const title = initialTitle(kind, args);
-      context.metadata({ title });
-      const result = await execute(args, context);
-      const presentation = resultPresentation(kind, args, result);
-      return {
-        title: presentation.title,
-        ...formatResult(result),
-        metadata: presentation.metadata,
-      };
-    },
-  });
-}
-
-/**
- * Adds readseek's anchored reads and structural navigation without replacing
- * OpenCode's built-in file tools.
- */
-export const ReadSeekPlugin: Plugin = async (_input, options) => {
-  const anchors = new SessionAnchors();
-  const imagePolicy = resolveImagePolicy(options);
-  const imageModes: readonly ImageMode[] = imagePolicy === "auto"
-    ? ["none", "all", "ocr", "caption", "objects"]
-    : ["all", "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");
-    const selection = [
-      input.cached && "cached",
-      input.others && "others",
-      input.ignored && "ignored",
-    ].filter((value): value is string => Boolean(value));
-    if (selection.length > 0) args.push("--git", selection.join(","));
-  };
-
-  return {
-    tool: {
-      readseek_read: readseekTool(
-        imagePolicy === "off"
-          ? "Read text with LINE:HASH anchors. Image reads are disabled. For documents, use readseek_view."
-          : `Read text with LINE:HASH anchors. For an image, select image (${imageModes.join(", ")}); omit it to skip image files. For documents such as PDFs, use readseek_view.`,
-        {
-          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; defaults to ${DEFAULT_READ_LIMIT}`),
-          language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
-          ...(imagePolicy === "off"
-            ? {}
-            : {
-                image: tool.schema.enum(imageModes as [ImageMode, ...ImageMode[]]).optional()
-                  .describe("Standalone image processing mode")
-              }),
-        },
-        "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 reads are disabled");
-          if (imagePolicy === "on" && image === "none") throw new Error('image="none" requires imageMode="auto"');
-
-          if (isLikelyDocumentPath(filePath)) {
-            if (image !== undefined) throw new Error("image does not apply to documents; use readseek_view");
-            if (input.offset !== undefined || input.limit !== undefined) {
-              throw new Error("offset and limit do not apply to documents; use readseek_view");
-            }
-            if (input.language !== undefined) {
-              throw new Error("language does not apply to documents; use readseek_view");
-            }
-            return digestDocumentReceipt(context, filePath);
-          }
-
-          // Image paths without an image mode only need metadata (skip without loading content).
-          // Text paths always use one digest --select content spawn.
-          let detectedText = false;
-          if (image === undefined && isLikelyImagePath(filePath)) {
-            const envelope = await runReadSeek(context, digestArgs(filePath, "metadata"));
-            const metadata = digestMetadata(envelope);
-            if (isPdfFile(metadata)) return documentReceipt(filePath, envelope);
-            if (isVisualFile(metadata)) {
-              return { file: filePath, skipped: true, reason: "image mode not selected" };
-            }
-            detectedText = true;
-          }
-
-          const extra: string[] = [];
-          const wantsImage = !detectedText
-            && (image !== undefined || isLikelyImagePath(filePath));
-          if (!wantsImage) {
-            const start = (input.offset as number | undefined) ?? 1;
-            const end = start + ((input.limit as number | undefined) ?? DEFAULT_READ_LIMIT) - 1;
-            if (start > 1) withAt(extra, start);
-            extra.push("--end", String(end));
-            if (input.language) extra.push("--language", input.language as string);
-          } else {
-            if (input.offset !== undefined || input.limit !== undefined) {
-              throw new Error("offset and limit do not apply to image reads");
-            }
-            if (input.language !== undefined) {
-              throw new Error("language does not apply to image reads");
-            }
-            if (image !== undefined) extra.push("--vision-mode", image);
-          }
-
-          let envelope: unknown;
-          try {
-            envelope = await runReadSeek(
-              context,
-              digestArgs(filePath, "content", extra),
-              image !== undefined && image !== "none" ? { timeoutMs: DEFAULT_VISION_TIMEOUT_MS } : {},
-            );
-          } catch (error) {
-            // A visual or document file with an uncommon extension rejects text bounds before
-            // an envelope can be returned. Probe metadata only on this cold path.
-            if (image !== undefined) throw error;
-            if (isDocumentBoundsError(error)) {
-              return digestDocumentReceipt(context, filePath);
-            }
-            if (isVisualBoundsError(error)) {
-              const metadataEnvelope = await runReadSeek(context, digestArgs(filePath, "metadata"));
-              if (isPdfFile(digestMetadata(metadataEnvelope))) {
-                return documentReceipt(filePath, metadataEnvelope);
-              }
-              if (isVisualFile(digestMetadata(metadataEnvelope))) {
-                return { file: filePath, skipped: true, reason: "image mode not selected" };
-              }
-            }
-            throw error;
-          }
-          const metadata = digestMetadata(envelope);
-          if (isPdfFile(metadata) || record(envelope).cache !== undefined) {
-            return documentReceipt(filePath, envelope);
-          }
-          const visual = isVisualFile(metadata);
-
-          if (visual && image === undefined) {
-            return { file: filePath, skipped: true, reason: "image mode not selected" };
-          }
-          if (visual && (input.offset !== undefined || input.limit !== undefined)) {
-            throw new Error("offset and limit do not apply to image reads");
-          }
-          if (visual && input.language !== undefined) {
-            throw new Error("language does not apply to image reads");
-          }
-
-          return requireDigestFacet(envelope, "content");
-        },
-        formatReadResult,
-      ),
-      readseek_view: readseekTool(
-        "Digest a document's structure or selected content. Start with the overview, then narrow by page, node, kind, or depth instead of reading the whole document.",
-        {
-          path: tool.schema.string().describe("Document path relative to the project directory"),
-          node: tool.schema.string().min(1).optional().describe("Node ID to use as the view root"),
-          page: tool.schema.number().int().positive().optional().describe("One-based source page"),
-          kind: tool.schema.enum(DOCUMENT_NODE_KINDS).optional().describe("Node kind filter"),
-          depth: tool.schema.number().int().nonnegative().optional().describe("Maximum depth below selected roots"),
-          outline: tool.schema.boolean().optional().describe("Return outline nodes only"),
-          visionMode: tool.schema.enum(VISION_ANALYSIS_MODES).optional()
-            .describe("Analyze selected assets: all, ocr, caption, or objects"),
-          visionLevel: tool.schema.enum(VISION_LEVELS).optional()
-            .describe("Vision inference level: low (default), medium, or high"),
-        },
-        "view",
-        async (input, context) => {
-          const filePath = resolvePath(context.directory, input.path as string);
-          await authorizeRead(context, filePath);
-          const visionMode = input.visionMode as VisionAnalysisMode | undefined;
-          const visionLevel = input.visionLevel as VisionLevel | undefined;
-          if (visionLevel !== undefined && visionMode === undefined) {
-            throw new Error("visionLevel requires visionMode");
-          }
-          if (input.outline && (visionMode !== undefined || visionLevel !== undefined)) {
-            throw new Error("vision options cannot be combined with outline");
-          }
-          const cacheDir = await ensureReadSeekCache(context);
-          const args = ["--readseek-dir", cacheDir, "view", filePath];
-          if (input.node) args.push("--node", input.node as string);
-          if (input.page !== undefined) args.push("--page", String(input.page));
-          if (input.kind) args.push("--kind", input.kind as string);
-          if (input.depth !== undefined) args.push("--depth", String(input.depth));
-          optionalFlag(args, input.outline as boolean | undefined, "--outline");
-          if (visionMode !== undefined) args.push("--vision-mode", visionMode);
-          if (visionLevel !== undefined) args.push("--vision-level", visionLevel);
-          return runReadSeekRaw(
-            context,
-            args,
-            visionMode === undefined ? {} : { timeoutMs: DEFAULT_VISION_TIMEOUT_MS },
-          );
-        },
-        (result) => ({ output: boundDocumentOutput(String(result)) }),
-      ),
-      readseek_digest: readseekTool(
-        "Digest native facets for a path and return the full envelope unchanged. Facets: metadata, content, map, diagnostics, identity (comma-separated). Metadata is always present; other selected facets appear when available.",
-        {
-          path: tool.schema.string().describe("Path relative to the project directory"),
-          select: tool.schema.string().optional()
-            .describe("Comma-separated facets: metadata, content, map, diagnostics, identity; defaults to content"),
-          at: tool.schema.string().optional()
-            .describe("Location: line:N[:COLUMN], hash:HASH[:COLUMN], or symbol:NAME"),
-          end: tool.schema.number().int().positive().optional().describe("Last line to include; content facet only"),
-          limit: tool.schema.number().int().positive().optional().describe("Maximum number of lines; content facet only"),
-          language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
-          visionMode: tool.schema.enum(["none", ...VISION_ANALYSIS_MODES] as [ImageMode, ...ImageMode[]]).optional()
-            .describe("Standalone image mode for the content facet: none, all, ocr, caption, or objects"),
-          visionLevel: tool.schema.enum(VISION_LEVELS).optional()
-            .describe("Vision inference level: low (default), medium, or high; content facet only"),
-        },
-        "digest",
-        async (input, context) => {
-          const filePath = resolvePath(context.directory, input.path as string);
-          await authorizeRead(context, filePath);
-          const select = ((input.select as string | undefined) ?? "content").trim() || "content";
-          const visionMode = input.visionMode as ImageMode | undefined;
-          const visionLevel = input.visionLevel as VisionLevel | undefined;
-          if (visionLevel !== undefined && visionMode === undefined) {
-            throw new Error("visionLevel requires visionMode");
-          }
-          const cacheDir = await ensureReadSeekCache(context);
-          const args = ["--readseek-dir", cacheDir, ...digestArgs(filePath, select)];
-          if (input.at) args.push("--at", input.at as string);
-          if (input.end !== undefined) args.push("--end", String(input.end));
-          if (input.limit !== undefined) args.push("--limit", String(input.limit));
-          if (input.language) args.push("--language", input.language as string);
-          if (visionMode !== undefined) args.push("--vision-mode", visionMode);
-          if (visionLevel !== undefined) args.push("--vision-level", visionLevel);
-          return runReadSeek(
-            context,
-            args,
-            visionMode === undefined || visionMode === "none"
-              ? {}
-              : { timeoutMs: DEFAULT_VISION_TIMEOUT_MS },
-          );
-        },
-      ),
-      readseek_grep: readseekTool(
-        "Search text or regex in files and return matching LINE:HASH anchors. Set literal for exact text. Use for identifiers, strings, configuration, errors, comments, and documentation.",
-        {
-          pattern: tool.schema.string().describe("Text or regular expression to search for; set literal for exact text"),
-          path: tool.schema.string().optional().describe("File or directory to search; defaults to the project directory"),
-          glob: tool.schema.string().optional().describe("File-name glob, such as **/*.ts"),
-          literal: tool.schema.boolean().optional().describe("Treat pattern as literal text"),
-          ignoreCase: tool.schema.boolean().optional().describe("Ignore case"),
-          context: tool.schema.number().int().nonnegative().optional().describe("Surrounding lines for each match"),
-          limit: tool.schema.number().int().positive().optional().describe("Maximum matching lines; defaults to 100"),
-        },
-        "grep",
-        async (input, context) => {
-          const target = resolvePath(context.directory, (input.path as string | undefined) ?? ".");
-          const pattern = input.pattern as string;
-          await authorizeSearch(context, target, pattern);
-          let expression: RegExp;
-          try {
-            const source = input.literal ? pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") : pattern;
-            expression = new RegExp(source, input.ignoreCase ? "i" : "");
-          } catch (error) {
-            throw new Error(`invalid regular expression: ${error instanceof Error ? error.message : String(error)}`);
-          }
-
-          const info = await stat(target);
-          const files: string[] = [];
-          if (info.isFile()) files.push(target);
-          else if (info.isDirectory()) {
-            const glob = new Bun.Glob((input.glob as string | undefined) ?? "**/*");
-            for await (const filePath of glob.scan({ cwd: target, absolute: true, onlyFiles: true, followSymlinks: false })) {
-              files.push(filePath);
-            }
-          } else throw new Error(`grep target is not a file or directory: ${target}`);
-
-          const maxMatches = (input.limit as number | undefined) ?? 100;
-          const contextLines = (input.context as number | undefined) ?? 0;
-          const results: { file: string; matches: unknown[]; hashlines: unknown[] }[] = [];
-          let totalMatches = 0;
-          let truncated = false;
-          for (const filePath of files.sort()) {
-            context.abort.throwIfAborted();
-            if (truncated) break;
-            const buffer = await readFile(filePath);
-            if (buffer.includes(0)) continue;
-            const lines = buffer.toString("utf8").replace(/\r\n/g, "\n").split("\n");
-            const matchLines = new Set<number>();
-            const ranges: [number, number][] = [];
-            for (let index = 0; index < lines.length; index++) {
-              expression.lastIndex = 0;
-              if (!expression.test(lines[index] ?? "")) continue;
-              if (totalMatches === maxMatches) {
-                truncated = true;
-                break;
-              }
-              const line = index + 1;
-              matchLines.add(line);
-              ranges.push([Math.max(1, line - contextLines), Math.min(lines.length, line + contextLines)]);
-              totalMatches++;
-            }
-            if (ranges.length === 0) continue;
-
-            const mergedRanges: [number, number][] = [];
-            for (const [start, end] of ranges) {
-              const previous = mergedRanges.at(-1);
-              if (previous && start <= previous[1] + 1) previous[1] = Math.max(previous[1], end);
-              else mergedRanges.push([start, end]);
-            }
-            const linesByNumber = new Map<number, unknown>();
-            for (const [start, end] of mergedRanges) {
-              const output = record(await runDigestContent(context, readRangeArgs(filePath, start, end)));
-              for (const hashline of items(output.hashlines)) {
-                const line = record(hashline).line;
-                if (typeof line === "number" && !linesByNumber.has(line)) linesByNumber.set(line, hashline);
-              }
-            }
-            const hashlines = [...linesByNumber.values()];
-            const matches = hashlines.filter((hashline) => {
-              const line = record(hashline).line;
-              return typeof line === "number" && matchLines.has(line);
-            });
-            results.push({ file: filePath, matches, hashlines });
-          }
-          return { results, truncated };
-        },
-      ),
-      readseek_search: readseekTool(
-        "Search code by AST structure using ast-grep-style patterns. Results include line hashes usable as LINE:HASH anchors. Use readseek_grep for identifiers, strings, comments, configuration, documentation, or other plain text and regex.",
-        {
-          pattern: tool.schema.string().describe("AST pattern (ast-grep style), such as console.log($$$ARGS)"),
-          path: tool.schema.string().optional().describe("File or directory to search; defaults to the project directory"),
-          language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
-          cached: tool.schema.boolean().optional().describe("In a Git repository, search tracked/indexed files"),
-          others: tool.schema.boolean().optional().describe("In a Git repository, search untracked files"),
-          ignored: tool.schema.boolean().optional().describe("With others=true, include ignored untracked files"),
-        },
-        "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);
-          await authorizeSearch(context, target, input.pattern as string);
-          const result = await runReadSeek(context, args);
-          return result;
-        },
-      ),
-      readseek_def: readseekTool(
-        "Go to a symbol definition or declaration by name. Accepts qualified or unqualified names; use this instead of text search for functions, methods, classes, types, and other declarations.",
-        {
-          name: tool.schema.string().describe("Qualified or unqualified symbol name"),
-          path: tool.schema.string().optional().describe("File or directory to search; defaults to the project directory"),
-          language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
-          cached: tool.schema.boolean().optional().describe("In a Git repository, search tracked/indexed files"),
-          others: tool.schema.boolean().optional().describe("In a Git repository, search untracked files"),
-          ignored: tool.schema.boolean().optional().describe("With others=true, include ignored untracked files"),
-        },
-        "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);
-          await authorizeSearch(context, target, input.name as string);
-          return runReadSeek(context, args);
-        },
-      ),
-      readseek_refs: readseekTool(
-        "Find references or usages of an identifier by name or cursor binding. Results include enclosing symbols and line hashes usable as LINE:HASH anchors. Without cursor scope, results are identifier-name matches; with scope, they follow one binding and exclude shadows. Use text search for literal occurrences in strings or comments, and use this tool before renaming or deleting a symbol.",
-        {
-          name: tool.schema.string().describe("Identifier to find references for"),
-          path: tool.schema.string().optional().describe("File or directory to search; defaults to the project directory"),
-          language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
-          scope: tool.schema.boolean().optional().describe("Restrict results to the binding at the cursor"),
-          line: tool.schema.number().int().positive().optional().describe("One-based cursor line; required with scope"),
-          column: tool.schema.number().int().positive().optional().describe("One-based cursor byte column for disambiguation"),
-          cached: tool.schema.boolean().optional().describe("In a Git repository, search tracked/indexed files"),
-          others: tool.schema.boolean().optional().describe("In a Git repository, search untracked files"),
-          ignored: tool.schema.boolean().optional().describe("With others=true, include ignored untracked files"),
-        },
-        "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];
-          if (input.scope) {
-            withAt(args, input.line as number, input.column as number | undefined);
-          } else {
-            args.push(input.name as string);
-          }
-          if (input.language) args.push("--language", input.language as string);
-          withSearchFlags(args, input);
-          await authorizeSearch(context, target, input.name as string);
-          return runReadSeek(context, args);
-        },
-      ),
-      readseek_rename: readseekTool(
-        "Rename a symbol at a source location. Resolvable same-named bindings are preserved; verified edits apply by default. Set `apply: false` to preview the plan before changing files.",
-        {
-          path: tool.schema.string().describe("Path relative to the project directory"),
-          line: tool.schema.number().int().positive().describe("One-based cursor line of the symbol to rename"),
-          column: tool.schema.number().int().positive().optional().describe("One-based cursor byte column for disambiguation"),
-          to: tool.schema.string().min(1).describe("New symbol name"),
-          workspace: tool.schema.boolean().optional().describe("Rename across the project"),
-          apply: tool.schema.boolean().optional().describe("Apply the verified edits; defaults to true"),
-        },
-        "rename",
-        async (input, context) => {
-          const filePath = resolvePath(context.directory, input.path as string);
-          await authorizeRead(context, filePath);
-          if (input.workspace) {
-            const identifyArgs = digestArgs(filePath, "identity");
-            withAt(identifyArgs, input.line as number, input.column as number | undefined);
-            const envelope = await runReadSeek(context, identifyArgs);
-            const name = identifiedName(requireDigestFacet(envelope, "identity"));
-            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];
-          withAt(args, input.line as number, input.column as number | undefined);
-          args.push("--to", input.to as string);
-          if (input.workspace) args.push("--workspace", context.directory);
-          const plan = await runReadSeek(context, args);
-          if (input.apply === false) return plan;
-          const files = renameFiles(plan);
-          const planHash = record(plan).plan_hash;
-          if (typeof planHash !== "string" || planHash.length === 0) {
-            throw new Error("readseek rename plan did not include a plan hash");
-          }
-          await authorizeEdit(context, files);
-          return runReadSeek(context, [...args, "--plan-hash", planHash, "--apply"], {
-            cancelable: false,
-            timeoutMs: DEFAULT_READSEEK_TIMEOUT_MS,
-          });
-        },
-      ),
-      readseek_edit: readseekTool(
-        "Edit an existing text file with fresh LINE:HASH anchors, exact text, or a mapped symbol. The native engine rejects stale or overlapping edits before writing.",
-        {
-          path: tool.schema.string().describe("Path relative to the project directory"),
-          edits: tool.schema.array(tool.schema.union([
-            tool.schema.object({
-              set_line: tool.schema.object({
-                anchor: tool.schema.string().describe("Fresh LINE:HASH anchor for the line to replace"),
-                new_text: tool.schema.string().describe("Replacement text; use an empty string to delete the line"),
-              }).strict(),
-            }).strict(),
-            tool.schema.object({
-              replace_lines: tool.schema.object({
-                start_anchor: tool.schema.string().describe("Fresh LINE:HASH anchor for the first line in the range"),
-                end_anchor: tool.schema.string().describe("Fresh LINE:HASH anchor for the last line in the range"),
-                new_text: tool.schema.string().describe("Replacement text; use an empty string to delete the range"),
-              }).strict(),
-            }).strict(),
-            tool.schema.object({
-              insert_after: tool.schema.object({
-                anchor: tool.schema.string().describe("Fresh LINE:HASH anchor for the line after which to insert"),
-                new_text: tool.schema.string().describe("Text to insert after the anchored line"),
-              }).strict(),
-            }).strict(),
-            tool.schema.object({
-              replace: tool.schema.object({
-                old_text: tool.schema.string().describe("Exact text to find"),
-                new_text: tool.schema.string().describe("Replacement text"),
-                all: tool.schema.boolean().optional().describe("Replace every exact match"),
-              }).strict(),
-            }).strict(),
-            tool.schema.object({
-              replace_symbol: tool.schema.object({
-                symbol: tool.schema.string().describe("Mapped symbol name"),
-                new_body: tool.schema.string().describe("Complete replacement body for the symbol"),
-              }).strict(),
-            }).strict(),
-          ])).min(1).describe("Use set_line, replace_lines, insert_after, replace, or replace_symbol"),
-          language: tool.schema.string().optional().describe("Language override for symbol replacement"),
-        },
-        "edit",
-        async (input, context) => {
-          const filePath = resolvePath(context.directory, input.path as string);
-          validateEdits(input.edits);
-          return withFileMutationQueue(filePath, async () => {
-            context.abort.throwIfAborted();
-            await authorizeRead(context, filePath);
-            await rejectSymlinkMutation(filePath);
-            const edits = input.edits as EditItem[];
-            const request = JSON.stringify({ edits });
-            const baseArgs = ["edit", filePath];
-            if (input.language) baseArgs.push("--language", input.language as string);
-            const plan = record(await runReadSeek(context, baseArgs, { stdin: request }));
-            if (
-              typeof plan.before_content !== "string" ||
-              typeof plan.content !== "string" ||
-              typeof plan.plan_hash !== "string"
-            ) {
-              throw new Error("readseek edit plan is missing before_content, content, or plan_hash");
-            }
-            const before = plan.before_content;
-            const after = plan.content;
-            const previewStart = Math.max(1, firstChangedLine(before, after) - 3);
-            const previewArgs = readRangeArgs(filePath, previewStart, previewStart + EDIT_RESULT_READ_LIMIT - 1);
-            if (before === after) {
-              return postMutationPreview(context, previewArgs, filePath, false);
-            }
-            await authorizeEdit(context, [filePath], simpleDiff(filePath, before, after), false);
-            context.abort.throwIfAborted();
-            const applied = record(await runReadSeek(
-              context,
-              [...baseArgs, "--apply", "--plan-hash", plan.plan_hash],
-              {
-                cancelable: false,
-                stdin: request,
-                timeoutMs: DEFAULT_READSEEK_TIMEOUT_MS,
-              },
-            ));
-            if (applied.applied !== true) {
-              throw new Error("readseek did not confirm that the edit was applied");
-            }
-            return postMutationPreview(context, previewArgs, filePath, true);
-          });
-        },
-      ),
-      readseek_write: readseekTool(
-        "Create or replace a complete text file and return LINE:HASH anchors. Use anchored edits for small changes to an existing file. Binary-looking content is rejected before writing.",
-        {
-          path: tool.schema.string().describe("Path relative to the project directory"),
-          content: tool.schema.string().describe("Complete text file content"),
-        },
-        "write",
-        async (input, context) => {
-          const filePath = resolvePath(context.directory, input.path as string);
-          await authorizeExternal(context, filePath);
-          return withFileMutationQueue(filePath, async () => {
-            context.abort.throwIfAborted();
-            await rejectSymlinkMutation(filePath);
-            const before = await readTextSnapshot(filePath);
-            const content = input.content as string;
-            if (content.includes("\0")) throw new Error("write content must be text");
-            await authorizeEdit(context, [filePath], simpleDiff(filePath, before.content, content), false);
-            context.abort.throwIfAborted();
-            await writeText(filePath, before, content);
-            return postMutationPreview(
-              context,
-              digestArgs(filePath, "content", ["--end", String(DEFAULT_READ_LIMIT)]),
-              filePath,
-              !before.exists || before.content !== content,
-            );
-          });
-        },
-      ),
-    },
-    "experimental.chat.system.transform": async (_input, output) => {
-      output.system.push(TOOL_POLICY);
-    },
-    "tool.definition": async (input, output) => {
-      const preference = PREFERRED_TOOL_DESCRIPTIONS[input.toolID];
-      if (preference) {
-        output.description = `${preference} ${output.description}`;
-        return;
-      }
-      const fallback = FALLBACK_TOOL_DESCRIPTIONS[input.toolID];
-      if (fallback) output.description = `${fallback} ${output.description}`;
-    },
-    event: async ({ event }) => {
-      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.after": async (input, output) => {
-      if (!input.tool.startsWith("readseek_")) return;
-      try {
-        const result = JSON.parse(output.output) as unknown;
-        if (input.tool === "readseek_rename") {
-          anchors.planRename(input.sessionID, result);
-          if (record(result).applied === true) {
-            for (const filePath of renameFiles(result)) anchors.forget(filePath);
-          }
-        }
-
-        const files = new Set<string>();
-        collectAnchoredFiles(result, files);
-        for (const filePath of files) anchors.mark(input.sessionID, path.resolve(filePath));
-      } catch {
-        // A failed tool result has no valid anchors to retain.
-      }
-    },
-    "experimental.session.compacting": async (input, output) => {
-      const context = anchors.render(input.sessionID);
-      if (context) output.context.push(context);
-    },
-  };
-};
-
-export default { id: "opencode-readseek", server: ReadSeekPlugin };