@infinityi/engine-lib 1.0.0 → 1.4.0

package/dist/tools-fs/index.js

@@ -0,0 +1,1695 @@
+import {
+  FilesystemPolicyError,
+  SchemaValidationError
+} from "../index-ajr3nk10.js";
+import {
+  defineTool
+} from "../index-a67ej96j.js";
+import {
+  __require
+} from "../index-37x76zdn.js";
+
+// src/tools-fs/define.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { lstat as lstat3, mkdir as mkdir2, readFile as readFile3, stat } from "node:fs/promises";
+import { dirname as dirname4, extname as extname3 } from "node:path";
+import { applyPatch as applyUnifiedPatch, parsePatch } from "diff";
+import Fuse from "fuse.js";
+
+// src/tools-fs/files.ts
+import { createHash } from "node:crypto";
+import { existsSync as existsSync2 } from "node:fs";
+import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname as dirname2, extname, join, relative as relative2 } from "node:path";
+import { glob } from "glob";
+import ignore from "ignore";
+
+// src/tools-fs/policy.ts
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+class FilesystemAccessError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FilesystemAccessError";
+  }
+}
+var DEFAULT_MAX_READ_BYTES = 20000;
+var DEFAULT_MAX_WRITE_BYTES = 1e6;
+var DEFAULT_MAX_ENTRIES = 300;
+var DEFAULT_MAX_RESULTS = 50;
+function normalizePathForOutput(path) {
+  return path.replaceAll("\\", "/");
+}
+function isInside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function displayPath(root, path) {
+  const rel = relative(root, path);
+  return rel === "" ? "." : normalizePathForOutput(rel);
+}
+function realpathIfPossible(path) {
+  return existsSync(path) ? realpathSync.native(path) : resolve(path);
+}
+function assertPositiveInt(name, value, fallback) {
+  if (value === undefined)
+    return fallback;
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new FilesystemPolicyError(`filesystemTools: \`${name}\` must be a positive integer`);
+  }
+  return value;
+}
+function normalizeFilesystemPolicy(config) {
+  if (!Array.isArray(config.allowedRoots) || config.allowedRoots.length === 0) {
+    throw new FilesystemPolicyError("filesystemTools: `allowedRoots` must be a non-empty array of absolute paths");
+  }
+  const allowedRoots = config.allowedRoots.map((entry) => {
+    if (typeof entry !== "string" || !isAbsolute(entry)) {
+      throw new FilesystemPolicyError(`filesystemTools: allowedRoots entry must be an absolute path, got ${JSON.stringify(entry)}`);
+    }
+    const logical = resolve(entry);
+    return { logical, real: realpathIfPossible(logical) };
+  });
+  const defaultRoot = config.defaultRoot === undefined ? allowedRoots[0].logical : resolve(allowedRoots[0].logical, config.defaultRoot);
+  const defaultRootReal = realpathIfPossible(defaultRoot);
+  const defaultAllowed = allowedRoots.some((root) => isInside(root.logical, defaultRoot) && isInside(root.real, defaultRootReal));
+  if (!defaultAllowed) {
+    throw new FilesystemPolicyError("filesystemTools: `defaultRoot` must resolve inside allowedRoots");
+  }
+  return {
+    allowedRoots,
+    defaultRoot,
+    defaultRootReal,
+    maxReadBytes: assertPositiveInt("maxReadBytes", config.maxReadBytes, DEFAULT_MAX_READ_BYTES),
+    maxWriteBytes: assertPositiveInt("maxWriteBytes", config.maxWriteBytes, DEFAULT_MAX_WRITE_BYTES),
+    maxEntries: assertPositiveInt("maxEntries", config.maxEntries, DEFAULT_MAX_ENTRIES),
+    maxResults: assertPositiveInt("maxResults", config.maxResults, DEFAULT_MAX_RESULTS)
+  };
+}
+function allowedRootFor(policy, logicalPath) {
+  return policy.allowedRoots.find((root) => isInside(root.logical, logicalPath)) ?? null;
+}
+function nearestExistingParent(path) {
+  let current = path;
+  while (!existsSync(current)) {
+    const parent = dirname(current);
+    if (parent === current)
+      return current;
+    current = parent;
+  }
+  const stat = lstatSync(current);
+  return stat.isDirectory() ? current : dirname(current);
+}
+async function resolvePath(policy, input, options = {}) {
+  const raw = input === undefined || input === "" ? "." : input;
+  const base = options.base ?? policy.defaultRoot;
+  const logicalPath = isAbsolute(raw) ? resolve(raw) : resolve(base, raw);
+  const root = allowedRootFor(policy, logicalPath);
+  if (root === null) {
+    throw new FilesystemAccessError(`path ${JSON.stringify(raw)} is outside the allowed roots`);
+  }
+  if (options.mustExist === true && !existsSync(logicalPath)) {
+    throw new FilesystemAccessError(`path ${JSON.stringify(raw)} does not exist`);
+  }
+  if (existsSync(logicalPath)) {
+    const realPath = realpathSync.native(logicalPath);
+    if (!isInside(root.real, realPath)) {
+      throw new FilesystemAccessError(`path ${JSON.stringify(raw)} resolves outside the allowed roots`);
+    }
+    return { path: logicalPath, root: root.logical, realPath };
+  }
+  if (options.forCreate === true || options.mustExist !== true) {
+    const parent = nearestExistingParent(logicalPath);
+    const parentReal = realpathSync.native(parent);
+    if (!isInside(root.real, parentReal)) {
+      throw new FilesystemAccessError(`path ${JSON.stringify(raw)} parent resolves outside the allowed roots`);
+    }
+    return { path: logicalPath, root: root.logical };
+  }
+  throw new FilesystemAccessError(`path ${JSON.stringify(raw)} does not exist`);
+}
+async function resolveRoot(policy, input) {
+  const resolved = await resolvePath(policy, input, { mustExist: true });
+  if (!lstatSync(resolved.path).isDirectory()) {
+    throw new FilesystemAccessError(`root ${JSON.stringify(input ?? ".")} is not a directory`);
+  }
+  return resolved;
+}
+
+// src/tools-fs/files.ts
+var DEFAULT_IGNORE = [
+  ".git",
+  "node_modules",
+  "dist",
+  "coverage",
+  ".cache",
+  "*.tsbuildinfo"
+];
+var TEXT_EXTENSIONS = new Set([
+  ".c",
+  ".cc",
+  ".config",
+  ".cpp",
+  ".cs",
+  ".css",
+  ".csv",
+  ".go",
+  ".h",
+  ".hpp",
+  ".html",
+  ".java",
+  ".js",
+  ".json",
+  ".jsx",
+  ".md",
+  ".mjs",
+  ".php",
+  ".py",
+  ".rb",
+  ".rs",
+  ".sh",
+  ".sql",
+  ".svg",
+  ".toml",
+  ".ts",
+  ".tsx",
+  ".txt",
+  ".xml",
+  ".yaml",
+  ".yml"
+]);
+function fileVersion(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function languageForPath(path) {
+  const ext = extname(path).toLowerCase();
+  switch (ext) {
+    case ".ts":
+      return "TypeScript";
+    case ".tsx":
+      return "TSX";
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return "JavaScript";
+    case ".jsx":
+      return "JSX";
+    case ".json":
+      return "JSON";
+    case ".md":
+      return "Markdown";
+    case ".css":
+      return "CSS";
+    case ".html":
+      return "HTML";
+    case ".py":
+      return "Python";
+    case ".rs":
+      return "Rust";
+    case ".go":
+      return "Go";
+    case ".java":
+      return "Java";
+    case ".sh":
+      return "Shell";
+    case ".yml":
+    case ".yaml":
+      return "YAML";
+    default:
+      return;
+  }
+}
+function isProbablyTextPath(path) {
+  const ext = extname(path).toLowerCase();
+  return TEXT_EXTENSIONS.has(ext) || basename(path).startsWith(".");
+}
+function isHiddenRelativePath(path) {
+  return normalizePathForOutput(path).split("/").some((part) => part.startsWith(".") && part !== "." && part !== "..");
+}
+async function buildIgnore(root, respectGitignore) {
+  const ig = ignore().add(DEFAULT_IGNORE);
+  if (!respectGitignore)
+    return ig;
+  const gitignorePath = join(root, ".gitignore");
+  if (existsSync2(gitignorePath)) {
+    const content = await readFile(gitignorePath, "utf8");
+    ig.add(content);
+  }
+  return ig;
+}
+function hasGlobMatch(path, globs) {
+  if (globs === undefined || globs.length === 0)
+    return true;
+  const matcher = ignore().add(globs.map((g) => g.replaceAll("\\", "/")));
+  return matcher.ignores(path);
+}
+function isExcluded(path, globs) {
+  if (globs === undefined || globs.length === 0)
+    return false;
+  const matcher = ignore().add(globs.map((g) => g.replaceAll("\\", "/")));
+  return matcher.ignores(path);
+}
+async function listEntries(root, options = {}) {
+  const includeHidden = options.includeHidden ?? false;
+  const respectGitignore = options.respectGitignore ?? true;
+  const maxEntries = options.maxEntries ?? Number.POSITIVE_INFINITY;
+  const ig = await buildIgnore(root, respectGitignore);
+  const patterns = options.includeGlobs !== undefined && options.includeGlobs.length > 0 ? [...options.includeGlobs] : ["**/*"];
+  const matches = await glob(patterns, {
+    cwd: root,
+    dot: includeHidden,
+    nodir: false,
+    absolute: true,
+    follow: false,
+    windowsPathsNoEscape: true
+  });
+  const entries = [];
+  let total = 0;
+  for (const abs of matches.sort()) {
+    const rel = normalizePathForOutput(relative2(root, abs));
+    if (rel === "")
+      continue;
+    if (!includeHidden && isHiddenRelativePath(rel))
+      continue;
+    if (ig.ignores(rel))
+      continue;
+    if (!hasGlobMatch(rel, options.includeGlobs))
+      continue;
+    if (isExcluded(rel, options.excludeGlobs))
+      continue;
+    const info = await lstat(abs);
+    const type = info.isDirectory() ? "directory" : info.isFile() ? "file" : info.isSymbolicLink() ? "symlink" : "other";
+    if (options.onlyFiles === true && type !== "file")
+      continue;
+    if (options.includeFiles === false && type === "file")
+      continue;
+    total += 1;
+    if (entries.length >= maxEntries)
+      continue;
+    entries.push({ path: abs, relativePath: rel, type, size: info.size });
+  }
+  return { entries, truncated: total > entries.length, total };
+}
+async function readTextFile(path, maxBytes) {
+  const bytes = await readFile(path);
+  const sliced = bytes.byteLength > maxBytes ? bytes.subarray(0, maxBytes) : bytes;
+  return {
+    text: sliced.toString("utf8"),
+    version: fileVersion(bytes),
+    truncated: bytes.byteLength > maxBytes
+  };
+}
+async function atomicWrite(path, content) {
+  await mkdir(dirname2(path), { recursive: true });
+  const tmp = join(dirname2(path), `.engine-lib-${process.pid}-${Date.now()}.tmp`);
+  await writeFile(tmp, content, "utf8");
+  await rename(tmp, path);
+  return fileVersion(content);
+}
+async function removeFile(path) {
+  await rm(path, { force: true });
+}
+function lineOffsets(text) {
+  return text.replace(/\r\n/g, `
+`).split(`
+`);
+}
+function renderLineRange(lines, startLine, endLine, includeLineNumbers) {
+  const selected = lines.slice(startLine - 1, endLine);
+  if (!includeLineNumbers)
+    return selected.join(`
+`);
+  return selected.map((line, index) => `${startLine + index}: ${line}`).join(`
+`);
+}
+function clampLineRange(totalLines, startLine, endLine) {
+  const start = Math.max(1, Math.min(startLine ?? 1, Math.max(totalLines, 1)));
+  const end = Math.max(start, Math.min(endLine ?? totalLines, Math.max(totalLines, 1)));
+  return { startLine: start, endLine: end };
+}
+function detectFrameworks(entries) {
+  const files = new Set(entries.map((entry) => entry.relativePath));
+  const frameworks = new Set;
+  if (files.has("package.json"))
+    frameworks.add("Node.js");
+  if (files.has("bun.lock") || files.has("bun.lockb"))
+    frameworks.add("Bun");
+  if ([...files].some((file) => file.includes("vite.config.")))
+    frameworks.add("Vite");
+  if ([...files].some((file) => file.includes("next.config.")))
+    frameworks.add("Next.js");
+  if ([...files].some((file) => file.includes("tsconfig.json")))
+    frameworks.add("TypeScript");
+  if (files.has("Cargo.toml"))
+    frameworks.add("Rust/Cargo");
+  if (files.has("go.mod"))
+    frameworks.add("Go modules");
+  return [...frameworks].sort();
+}
+function importantFiles(entries) {
+  const importantNames = new Set([
+    "README.md",
+    "package.json",
+    "tsconfig.json",
+    "bun.lock",
+    "Cargo.toml",
+    "go.mod",
+    "pyproject.toml",
+    "Dockerfile",
+    ".gitignore"
+  ]);
+  return entries.filter((entry) => entry.type === "file" && importantNames.has(entry.relativePath)).map((entry) => entry.relativePath);
+}
+
+// src/tools-fs/git.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile);
+async function git(root, args) {
+  try {
+    const { stdout } = await execFileAsync("git", ["-C", root, ...args], {
+      maxBuffer: 10 * 1024 * 1024,
+      windowsHide: true
+    });
+    return stdout;
+  } catch {
+    return null;
+  }
+}
+function truncate(text, maxChars) {
+  if (text.length <= maxChars)
+    return { text, truncated: false };
+  return { text: `${text.slice(0, Math.max(0, maxChars - 13))}
+[truncated]`, truncated: true };
+}
+function splitGitDiffByFile(diff) {
+  const sections = diff.match(/^diff --git .*?(?=^diff --git |\s*$)/gms) ?? [];
+  const byPath = new Map;
+  for (const section of sections) {
+    const header = /^diff --git a\/(.+?) b\/(.+)$/m.exec(section);
+    if (header === null)
+      continue;
+    const oldPath = header[1]?.replaceAll("\\", "/");
+    const newPath = header[2]?.replaceAll("\\", "/");
+    if (oldPath !== undefined)
+      byPath.set(oldPath, section);
+    if (newPath !== undefined)
+      byPath.set(newPath, section);
+  }
+  return byPath;
+}
+async function diffStatus(root, options) {
+  const top = await git(root, ["rev-parse", "--show-toplevel"]);
+  if (top === null)
+    return { isGitRepo: false, files: [], truncated: false };
+  const pathArgs = options.paths !== undefined && options.paths.length > 0 ? ["--", ...options.paths] : [];
+  const status = await git(root, ["status", "--porcelain=v1", ...pathArgs]);
+  if (status === null)
+    return { isGitRepo: false, files: [], truncated: false };
+  const files = status.split(/\r?\n/).filter((line) => line.trim() !== "").map((line) => {
+    const statusCode = line.slice(0, 2).trim() || "modified";
+    const path = line.slice(3).replace(/^.* -> /, "").replaceAll("\\", "/");
+    return { path, status: statusCode };
+  });
+  if (!options.includeDiff || files.length === 0) {
+    return { isGitRepo: true, files, truncated: false };
+  }
+  const diff = await git(root, ["diff", `--unified=${options.contextLines}`, ...pathArgs]);
+  const diffByFile = splitGitDiffByFile(diff ?? "");
+  let truncated = false;
+  const withDiff = files.map((file) => {
+    const clipped = truncate(diffByFile.get(file.path) ?? "", options.maxDiffChars);
+    truncated = truncated || clipped.truncated;
+    return { ...file, diff: clipped.text };
+  });
+  return {
+    isGitRepo: true,
+    files: withDiff,
+    truncated
+  };
+}
+
+// src/tools-fs/schemas.ts
+function issue(path, message) {
+  return { path: [...path], message };
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validate(node, input, path = []) {
+  const issues = [];
+  if (node.oneOf !== undefined) {
+    const matches = node.oneOf.filter((schema) => validate(schema, input, path).length === 0);
+    if (matches.length !== 1)
+      issues.push(issue(path, "expected exactly one matching schema"));
+    return issues;
+  }
+  if (node.enum !== undefined) {
+    if (!node.enum.includes(input)) {
+      issues.push(issue(path, `expected one of ${JSON.stringify(node.enum)}`));
+    }
+    return issues;
+  }
+  switch (node.type) {
+    case "string":
+      if (typeof input !== "string")
+        issues.push(issue(path, "expected string"));
+      break;
+    case "boolean":
+      if (typeof input !== "boolean")
+        issues.push(issue(path, "expected boolean"));
+      break;
+    case "integer":
+      if (typeof input !== "number" || !Number.isInteger(input)) {
+        issues.push(issue(path, "expected integer"));
+      }
+      break;
+    case "number":
+      if (typeof input !== "number" || Number.isNaN(input))
+        issues.push(issue(path, "expected number"));
+      break;
+    case "array":
+      if (!Array.isArray(input)) {
+        issues.push(issue(path, "expected array"));
+        break;
+      }
+      if (node.items !== undefined) {
+        input.forEach((value, index) => {
+          issues.push(...validate(node.items, value, [...path, index]));
+        });
+      }
+      break;
+    case "object": {
+      if (!isPlainObject(input)) {
+        issues.push(issue(path, "expected object"));
+        break;
+      }
+      const properties = node.properties ?? {};
+      for (const key of node.required ?? []) {
+        if (input[key] === undefined)
+          issues.push(issue([...path, key], "required"));
+      }
+      for (const [key, prop] of Object.entries(properties)) {
+        if (input[key] !== undefined)
+          issues.push(...validate(prop, input[key], [...path, key]));
+      }
+      if (node.additionalProperties === false) {
+        for (const key of Object.keys(input)) {
+          if (!(key in properties))
+            issues.push(issue([...path, key], "unexpected property"));
+        }
+      } else if (typeof node.additionalProperties === "object") {
+        for (const [key, value] of Object.entries(input)) {
+          if (!(key in properties)) {
+            issues.push(...validate(node.additionalProperties, value, [...path, key]));
+          }
+        }
+      }
+      break;
+    }
+    default:
+      break;
+  }
+  if ((node.type === "integer" || node.type === "number") && typeof input === "number") {
+    if (node.minimum !== undefined && input < node.minimum) {
+      issues.push(issue(path, `expected >= ${node.minimum}`));
+    }
+    if (node.maximum !== undefined && input > node.maximum) {
+      issues.push(issue(path, `expected <= ${node.maximum}`));
+    }
+  }
+  return issues;
+}
+function toolSchema(jsonSchema) {
+  return {
+    jsonSchema,
+    safeParse(input) {
+      const issues = validate(jsonSchema, input);
+      if (issues.length === 0)
+        return { success: true, data: input };
+      return {
+        success: false,
+        error: new SchemaValidationError("schema validation failed", { issues })
+      };
+    },
+    parse(input) {
+      const result = this.safeParse(input);
+      if (!result.success)
+        throw result.error;
+      return result.data;
+    }
+  };
+}
+var stringSchema = { type: "string" };
+var boolSchema = { type: "boolean" };
+var intSchema = (extra = {}) => ({ type: "integer", ...extra });
+var stringArray = { type: "array", items: stringSchema };
+var SCHEMAS = {
+  repoMap: toolSchema({
+    type: "object",
+    properties: {
+      root: { ...stringSchema, default: "." },
+      depth: intSchema({ minimum: 1, maximum: 6, default: 3 }),
+      include_files: { ...boolSchema, default: true },
+      include_symbols: { ...boolSchema, default: false },
+      max_entries: intSchema({ default: 300 }),
+      respect_gitignore: { ...boolSchema, default: true }
+    },
+    additionalProperties: false
+  }),
+  findFiles: toolSchema({
+    type: "object",
+    properties: {
+      query: stringSchema,
+      mode: { type: "string", enum: ["auto", "exact", "glob", "fuzzy", "extension", "regex"], default: "auto" },
+      root: { ...stringSchema, default: "." },
+      include_hidden: { ...boolSchema, default: false },
+      respect_gitignore: { ...boolSchema, default: true },
+      max_results: intSchema({ default: 50 })
+    },
+    required: ["query"],
+    additionalProperties: false
+  }),
+  searchText: toolSchema({
+    type: "object",
+    properties: {
+      pattern: stringSchema,
+      mode: { type: "string", enum: ["literal", "regex"], default: "literal" },
+      root: { ...stringSchema, default: "." },
+      include_globs: stringArray,
+      exclude_globs: stringArray,
+      case_sensitive: { ...boolSchema, default: false },
+      context_lines: intSchema({ minimum: 0, maximum: 10, default: 2 }),
+      max_results: intSchema({ default: 50 }),
+      max_preview_chars: intSchema({ default: 12000 }),
+      use_index: { ...boolSchema, default: true }
+    },
+    required: ["pattern"],
+    additionalProperties: false
+  }),
+  searchSemantic: toolSchema({
+    type: "object",
+    properties: {
+      query: stringSchema,
+      root: { ...stringSchema, default: "." },
+      include_globs: stringArray,
+      exclude_globs: stringArray,
+      granularity: { type: "string", enum: ["file", "chunk", "symbol"], default: "chunk" },
+      max_results: intSchema({ default: 20 }),
+      max_preview_chars: intSchema({ default: 12000 })
+    },
+    required: ["query"],
+    additionalProperties: false
+  }),
+  symbols: toolSchema({
+    type: "object",
+    properties: {
+      path: stringSchema,
+      recursive: { ...boolSchema, default: false },
+      symbol_kinds: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: ["class", "function", "method", "interface", "type", "variable", "import", "export"]
+        }
+      },
+      max_results: intSchema({ default: 200 })
+    },
+    required: ["path"],
+    additionalProperties: false
+  }),
+  read: toolSchema({
+    type: "object",
+    properties: {
+      path: stringSchema,
+      start_line: intSchema({ minimum: 1 }),
+      end_line: intSchema({ minimum: 1 }),
+      symbol: stringSchema,
+      max_bytes: intSchema({ default: 20000 }),
+      include_line_numbers: { ...boolSchema, default: true },
+      collapse_imports: { ...boolSchema, default: false },
+      collapse_comments: { ...boolSchema, default: false }
+    },
+    required: ["path"],
+    additionalProperties: false
+  }),
+  openWindow: toolSchema({
+    type: "object",
+    properties: {
+      path: stringSchema,
+      anchor: { oneOf: [intSchema(), stringSchema] },
+      window_lines: intSchema({ minimum: 20, maximum: 200, default: 100 }),
+      direction: { type: "string", enum: ["center", "next", "prev"], default: "center" }
+    },
+    required: ["path"],
+    additionalProperties: false
+  }),
+  editReplace: toolSchema({
+    type: "object",
+    properties: {
+      path: stringSchema,
+      old_text: stringSchema,
+      new_text: stringSchema,
+      occurrence: intSchema({ minimum: 1, default: 1 }),
+      expected_file_version: stringSchema,
+      validate: validationSchema()
+    },
+    required: ["path", "old_text", "new_text"],
+    additionalProperties: false
+  }),
+  editRange: toolSchema({
+    type: "object",
+    properties: {
+      path: stringSchema,
+      start_line: intSchema({ minimum: 1 }),
+      end_line: intSchema({ minimum: 1 }),
+      new_text: stringSchema,
+      expected_file_version: stringSchema,
+      validate: validationSchema()
+    },
+    required: ["path", "start_line", "end_line", "new_text", "expected_file_version"],
+    additionalProperties: false
+  }),
+  applyPatch: toolSchema({
+    type: "object",
+    properties: {
+      patch: stringSchema,
+      root: { ...stringSchema, default: "." },
+      dry_run: { ...boolSchema, default: false },
+      expected_versions: { type: "object", additionalProperties: stringSchema },
+      validate: validationSchema()
+    },
+    required: ["patch"],
+    additionalProperties: false
+  }),
+  writeFile: toolSchema({
+    type: "object",
+    properties: {
+      path: stringSchema,
+      content: stringSchema,
+      mode: { type: "string", enum: ["create_only", "overwrite", "append"], default: "create_only" },
+      expected_file_version: stringSchema,
+      create_dirs: { ...boolSchema, default: true }
+    },
+    required: ["path", "content"],
+    additionalProperties: false
+  }),
+  diffStatus: toolSchema({
+    type: "object",
+    properties: {
+      paths: stringArray,
+      include_diff: { ...boolSchema, default: true },
+      max_diff_chars: intSchema({ default: 20000 }),
+      context_lines: intSchema({ default: 3 })
+    },
+    additionalProperties: false
+  })
+};
+function validationSchema() {
+  return {
+    type: "object",
+    properties: {
+      syntax: { ...boolSchema, default: true },
+      format: { ...boolSchema, default: false },
+      tests: stringArray
+    },
+    additionalProperties: false
+  };
+}
+
+// src/tools-fs/search.ts
+import { spawn } from "node:child_process";
+import { readFile as readFile2 } from "node:fs/promises";
+import { dirname as dirname3, isAbsolute as isAbsolute2, relative as relative3 } from "node:path";
+import MiniSearch from "minisearch";
+function truncate2(text, maxChars) {
+  return text.length > maxChars ? `${text.slice(0, Math.max(0, maxChars - 13))}
+[truncated]` : text;
+}
+function buildRegex(pattern, mode, caseSensitive) {
+  const source = mode === "literal" ? pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") : pattern;
+  return new RegExp(source, caseSensitive ? "g" : "gi");
+}
+function searchOneFile(text, relPath, regex, contextLines, maxPreviewChars, maxResults) {
+  const lines = lineOffsets(text);
+  const out = [];
+  for (let index = 0;index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    regex.lastIndex = 0;
+    const match = regex.exec(line);
+    if (match === null)
+      continue;
+    const start = Math.max(0, index - contextLines);
+    const end = Math.min(lines.length - 1, index + contextLines);
+    const context = [];
+    for (let lineIndex = start;lineIndex <= end; lineIndex += 1) {
+      context.push({
+        line: lineIndex + 1,
+        text: lines[lineIndex] ?? "",
+        match: lineIndex === index
+      });
+    }
+    out.push({
+      path: relPath,
+      line: index + 1,
+      column: match.index + 1,
+      preview: truncate2(line, maxPreviewChars),
+      context
+    });
+    if (out.length >= maxResults)
+      break;
+  }
+  return out;
+}
+async function tryRipgrepSearch(options) {
+  try {
+    const mod = await import("@vscode/ripgrep");
+    const rgPath = mod.rgPath;
+    if (typeof rgPath !== "string")
+      return null;
+    const args = [
+      "--json",
+      "--color=never",
+      "--line-number",
+      "--column",
+      "--context",
+      String(options.contextLines),
+      ...options.caseSensitive ? [] : ["--ignore-case"],
+      ...options.mode === "literal" ? ["--fixed-strings"] : [],
+      ...(options.includeGlobs ?? []).flatMap((glob2) => ["--glob", glob2]),
+      ...(options.excludeGlobs ?? []).flatMap((glob2) => ["--glob", `!${glob2}`]),
+      "--",
+      options.pattern,
+      options.root
+    ];
+    const stdout = await new Promise((resolve2, reject) => {
+      const child = spawn(rgPath, args, { cwd: options.root, stdio: ["ignore", "pipe", "pipe"] });
+      let out = "";
+      let err = "";
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => {
+        out += chunk;
+      });
+      child.stderr.on("data", (chunk) => {
+        err += chunk;
+      });
+      child.on("error", reject);
+      child.on("close", (code) => {
+        if (code === 0 || code === 1)
+          resolve2(out);
+        else
+          reject(new Error(err || `ripgrep exited ${code}`));
+      });
+    });
+    const results = [];
+    for (const raw of stdout.split(/\r?\n/)) {
+      if (raw.trim() === "")
+        continue;
+      const event = JSON.parse(raw);
+      if (event.type !== "match" || event.data === undefined)
+        continue;
+      const rawPath = event.data.path?.text ?? "";
+      const path = isAbsolute2(rawPath) ? relative3(options.root, rawPath) : rawPath;
+      const line = event.data.line_number ?? 1;
+      const text = event.data.lines?.text?.replace(/\r?\n$/, "") ?? "";
+      const column = (event.data.submatches?.[0]?.start ?? 0) + 1;
+      results.push({
+        path: path.replaceAll("\\", "/"),
+        line,
+        column,
+        preview: truncate2(text, options.maxPreviewChars),
+        context: [{ line, text, match: true }]
+      });
+      if (results.length >= options.maxResults)
+        break;
+    }
+    return results;
+  } catch {
+    return null;
+  }
+}
+async function searchText(root, options) {
+  const rg = await tryRipgrepSearch({ root, ...options });
+  if (rg !== null) {
+    return { results: rg, backend: "ripgrep", truncated: rg.length >= options.maxResults };
+  }
+  const files = await listEntries(root, {
+    onlyFiles: true,
+    respectGitignore: true,
+    includeHidden: false,
+    includeGlobs: options.includeGlobs,
+    excludeGlobs: options.excludeGlobs,
+    maxEntries: Number.POSITIVE_INFINITY
+  });
+  const regex = buildRegex(options.pattern, options.mode, options.caseSensitive);
+  const out = [];
+  for (const entry of files.entries) {
+    if (!isProbablyTextPath(entry.path))
+      continue;
+    const text = await readFile2(entry.path, "utf8").catch(() => "");
+    out.push(...searchOneFile(text, entry.relativePath, regex, options.contextLines, options.maxPreviewChars, options.maxResults - out.length));
+    if (out.length >= options.maxResults)
+      break;
+  }
+  return { results: out, backend: "node", truncated: files.truncated || out.length >= options.maxResults };
+}
+function chunksForText(path, text, maxPreviewChars) {
+  const lines = lineOffsets(text);
+  const chunks = [];
+  const chunkSize = 40;
+  for (let start = 0;start < lines.length; start += chunkSize) {
+    const end = Math.min(lines.length, start + chunkSize);
+    const preview = truncate2(lines.slice(start, end).join(`
+`), maxPreviewChars);
+    chunks.push({ path, score: 0, startLine: start + 1, endLine: end, preview });
+  }
+  return chunks;
+}
+function symbolDocsForText(path, text, maxPreviewChars) {
+  const lines = lineOffsets(text);
+  const out = [];
+  const regex = /^\s*(?:export\s+)?(?:class|function|interface|type|const|let|var)\s+([A-Za-z_$][\w$]*)/;
+  lines.forEach((line, index) => {
+    const match = regex.exec(line);
+    if (match === null)
+      return;
+    out.push({
+      path,
+      score: 0,
+      startLine: index + 1,
+      endLine: index + 1,
+      preview: truncate2(line, maxPreviewChars),
+      symbol: match[1]
+    });
+  });
+  return out;
+}
+async function searchSemantic(root, options) {
+  const files = await listEntries(root, {
+    onlyFiles: true,
+    respectGitignore: true,
+    includeGlobs: options.includeGlobs,
+    excludeGlobs: options.excludeGlobs,
+    maxEntries: Number.POSITIVE_INFINITY
+  });
+  const docs = [];
+  for (const entry of files.entries) {
+    if (!isProbablyTextPath(entry.path))
+      continue;
+    const text = (await readTextFile(entry.path, 200000).catch(() => null))?.text;
+    if (text === undefined)
+      continue;
+    if (options.granularity === "file") {
+      docs.push({
+        id: entry.relativePath,
+        path: entry.relativePath,
+        score: 0,
+        startLine: 1,
+        endLine: lineOffsets(text).length,
+        preview: truncate2(text, options.maxPreviewChars),
+        text: `${entry.relativePath}
+${text}`
+      });
+    } else {
+      const units = options.granularity === "symbol" ? symbolDocsForText(entry.relativePath, text, options.maxPreviewChars) : chunksForText(entry.relativePath, text, options.maxPreviewChars);
+      for (const chunk of units.length > 0 ? units : chunksForText(entry.relativePath, text, options.maxPreviewChars)) {
+        docs.push({
+          id: `${entry.relativePath}:${chunk.startLine}:${chunk.symbol ?? ""}`,
+          ...chunk,
+          text: `${entry.relativePath}
+${chunk.symbol ?? ""}
+${chunk.preview}`
+        });
+      }
+    }
+  }
+  if (docs.length === 0)
+    return { results: [], truncated: false };
+  const index = new MiniSearch({
+    fields: ["path", "text", "symbol"],
+    storeFields: ["path", "startLine", "endLine", "preview", "symbol"],
+    searchOptions: { prefix: true, fuzzy: 0.2 }
+  });
+  index.addAll(docs);
+  const matches = index.search(options.query).slice(0, options.maxResults);
+  return {
+    results: matches.map((match) => ({
+      path: String(match.path),
+      score: match.score,
+      startLine: Number(match.startLine),
+      endLine: Number(match.endLine),
+      preview: String(match.preview),
+      ...match.symbol !== undefined ? { symbol: String(match.symbol) } : {}
+    })),
+    truncated: matches.length >= options.maxResults && docs.length > matches.length
+  };
+}
+
+// src/tools-fs/symbols.ts
+import { lstat as lstat2 } from "node:fs/promises";
+import { extname as extname2 } from "node:path";
+var TS_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+function wanted(kind, kinds) {
+  return kinds === undefined || kinds.length === 0 || kinds.includes(kind);
+}
+function lineRangeFromText(text, start, end) {
+  const beforeStart = text.slice(0, start);
+  const beforeEnd = text.slice(0, end);
+  return {
+    startLine: beforeStart.split(/\r\n|\r|\n/).length,
+    endLine: beforeEnd.split(/\r\n|\r|\n/).length
+  };
+}
+function regexSymbols(text, path, kinds) {
+  const results = [];
+  const lines = lineOffsets(text);
+  const patterns = [
+    { kind: "import", regex: /^\s*import\s+(?:type\s+)?(?:.+?\s+from\s+)?["']([^"']+)["']/gm, nameIndex: 1 },
+    { kind: "export", regex: /^\s*export\s+(?:default\s+)?(?:\{[^}]+\}|(?:class|function|interface|type|const|let|var)\s+([A-Za-z_$][\w$]*)?)/gm, nameIndex: 1 },
+    { kind: "class", regex: /^\s*(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/gm, nameIndex: 1 },
+    { kind: "function", regex: /^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm, nameIndex: 1 },
+    { kind: "interface", regex: /^\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/gm, nameIndex: 1 },
+    { kind: "type", regex: /^\s*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)/gm, nameIndex: 1 },
+    { kind: "variable", regex: /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)/gm, nameIndex: 1 }
+  ];
+  for (const { kind, regex, nameIndex } of patterns) {
+    if (!wanted(kind, kinds))
+      continue;
+    for (const match of text.matchAll(regex)) {
+      const name = match[nameIndex] ?? match[0].trim();
+      const range = lineRangeFromText(text, match.index ?? 0, (match.index ?? 0) + match[0].length);
+      results.push({
+        path,
+        name,
+        kind,
+        startLine: range.startLine,
+        endLine: range.endLine,
+        signature: lines[range.startLine - 1]?.trim()
+      });
+    }
+  }
+  return results.sort((a, b) => a.startLine - b.startLine || a.name.localeCompare(b.name));
+}
+async function typescriptSymbols(text, path, kinds) {
+  if (!TS_EXTENSIONS.has(extname2(path).toLowerCase()))
+    return regexSymbols(text, path, kinds);
+  try {
+    const ts = await import("typescript");
+    const scriptKind = extname2(path).toLowerCase().includes("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind);
+    const lines = lineOffsets(text);
+    const out = [];
+    const emit = (node, kind, name) => {
+      if (!wanted(kind, kinds))
+        return;
+      const start = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+      const end = source.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
+      out.push({
+        path,
+        name,
+        kind,
+        startLine: start,
+        endLine: end,
+        signature: lines[start - 1]?.trim()
+      });
+    };
+    const exported = (node) => {
+      return ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) === true;
+    };
+    const visit = (node) => {
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+        emit(node, "import", node.moduleSpecifier.text);
+      } else if (ts.isClassDeclaration(node) && node.name !== undefined) {
+        emit(node, "class", node.name.text);
+        if (exported(node))
+          emit(node, "export", node.name.text);
+      } else if (ts.isFunctionDeclaration(node) && node.name !== undefined) {
+        emit(node, "function", node.name.text);
+        if (exported(node))
+          emit(node, "export", node.name.text);
+      } else if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name)) {
+        emit(node, "method", node.name.text);
+      } else if (ts.isInterfaceDeclaration(node)) {
+        emit(node, "interface", node.name.text);
+        if (exported(node))
+          emit(node, "export", node.name.text);
+      } else if (ts.isTypeAliasDeclaration(node)) {
+        emit(node, "type", node.name.text);
+        if (exported(node))
+          emit(node, "export", node.name.text);
+      } else if (ts.isVariableStatement(node)) {
+        for (const declaration of node.declarationList.declarations) {
+          if (ts.isIdentifier(declaration.name)) {
+            emit(declaration, "variable", declaration.name.text);
+            if (exported(node))
+              emit(declaration, "export", declaration.name.text);
+          }
+        }
+      } else if (ts.isExportDeclaration(node)) {
+        const moduleName = node.moduleSpecifier !== undefined && ts.isStringLiteral(node.moduleSpecifier) ? node.moduleSpecifier.text : "export";
+        emit(node, "export", moduleName);
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return out.sort((a, b) => a.startLine - b.startLine || a.name.localeCompare(b.name));
+  } catch {
+    return regexSymbols(text, path, kinds);
+  }
+}
+async function symbolsForFile(absPath, root, maxBytes, kinds) {
+  const text = (await readTextFile(absPath, maxBytes)).text;
+  return typescriptSymbols(text, displayPath(root, absPath), kinds);
+}
+async function symbolsForPath(policy, input, options = {}) {
+  const resolved = await resolvePath(policy, input, { mustExist: true });
+  const info = await lstat2(resolved.path);
+  const maxResults = options.maxResults ?? 200;
+  if (info.isDirectory()) {
+    if (options.recursive !== true) {
+      return { results: [], truncated: false, root: resolved.path };
+    }
+    const root = await resolveRoot(policy, input);
+    const listed = await listEntries(root.path, {
+      onlyFiles: true,
+      respectGitignore: true,
+      maxEntries: maxResults * 4
+    });
+    const out = [];
+    for (const entry of listed.entries) {
+      if (!TS_EXTENSIONS.has(extname2(entry.path).toLowerCase()))
+        continue;
+      out.push(...await symbolsForFile(entry.path, root.path, policy.maxReadBytes, options.kinds));
+      if (out.length >= maxResults)
+        break;
+    }
+    return { results: out.slice(0, maxResults), truncated: listed.truncated || out.length > maxResults, root: root.path };
+  }
+  const results = await symbolsForFile(resolved.path, resolved.root, policy.maxReadBytes, options.kinds);
+  return { results: results.slice(0, maxResults), truncated: results.length > maxResults, root: resolved.root };
+}
+
+// src/tools-fs/define.ts
+function fail(error) {
+  if (error instanceof FilesystemAccessError)
+    return { ok: false, error: error.message };
+  if (error instanceof Error)
+    return { ok: false, error: error.message };
+  return { ok: false, error: String(error) };
+}
+function bounded(value, fallback, min, max) {
+  const n = value ?? fallback;
+  return Math.max(min, Math.min(max, n));
+}
+function countLanguages(entries) {
+  const counts = new Map;
+  for (const entry of entries) {
+    if (entry.type !== "file")
+      continue;
+    const language = languageForPath(entry.relativePath);
+    if (language !== undefined)
+      counts.set(language, (counts.get(language) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([language, files]) => ({ language, files })).sort((a, b) => b.files - a.files || a.language.localeCompare(b.language));
+}
+function depthOf(path) {
+  return path === "." ? 0 : path.split("/").filter(Boolean).length;
+}
+function modeFor(query, mode) {
+  if (mode !== undefined && mode !== "auto")
+    return mode;
+  if (/[\\/[*?\]]/.test(query))
+    return query.includes("*") || query.includes("?") ? "glob" : "exact";
+  if (query.startsWith(".") || /^[A-Za-z0-9]+$/.test(query))
+    return "fuzzy";
+  return "fuzzy";
+}
+function resultEntry(root, path, type, size, score) {
+  return {
+    path: displayPath(root, path),
+    absolutePath: path,
+    type,
+    size,
+    ...score !== undefined ? { score } : {}
+  };
+}
+function collapseLines(lines, options) {
+  const out = [];
+  for (let i = 0;i < lines.length; i += 1) {
+    const text = lines[i] ?? "";
+    if (options.collapseImports && /^\s*import\b/.test(text)) {
+      const start = i;
+      while (i + 1 < lines.length && /^\s*import\b/.test(lines[i + 1] ?? ""))
+        i += 1;
+      out.push({ line: start + 1, text: `[imports collapsed: ${i - start + 1} lines]` });
+      continue;
+    }
+    if (options.collapseComments && /^\s*(\/\/|\/\*|\*|#)/.test(text)) {
+      const start = i;
+      while (i + 1 < lines.length && /^\s*(\/\/|\/\*|\*|#)/.test(lines[i + 1] ?? ""))
+        i += 1;
+      out.push({ line: start + 1, text: `[comments collapsed: ${i - start + 1} lines]` });
+      continue;
+    }
+    out.push({ line: i + 1, text });
+  }
+  return out;
+}
+function renderCollapsedLineRange(lines, startLine, endLine, includeLineNumbers, options) {
+  const collapsed = collapseLines(lines.slice(startLine - 1, endLine), options);
+  if (!includeLineNumbers)
+    return collapsed.map((line) => line.text).join(`
+`);
+  return collapsed.map((line) => `${startLine + line.line - 1}: ${line.text}`).join(`
+`);
+}
+async function syntaxCheck(path, content) {
+  const ext = extname3(path).toLowerCase();
+  try {
+    if (ext === ".json")
+      JSON.parse(content);
+    if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].includes(ext)) {
+      const ts = await import("typescript");
+      const diagnostics = ts.transpileModule(content, {
+        compilerOptions: { noEmit: true },
+        reportDiagnostics: true
+      }).diagnostics ?? [];
+      const first = diagnostics.find((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+      if (first !== undefined) {
+        return { ok: false, error: ts.flattenDiagnosticMessageText(first.messageText, `
+`) };
+      }
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+async function runValidation(config, validate2, changedFiles, cwd, ctx) {
+  const options = validate2 ?? {};
+  const syntax = options.syntax ?? true;
+  const syntaxResults = [];
+  if (syntax) {
+    for (const file of changedFiles) {
+      syntaxResults.push({ path: file.path, ...await syntaxCheck(file.path, file.content) });
+    }
+  }
+  const tests = [];
+  for (const command of options.tests ?? []) {
+    if (config.runValidationCommand === undefined) {
+      tests.push({ command, ok: false, skipped: true, reason: "no runValidationCommand hook configured" });
+      continue;
+    }
+    tests.push(await config.runValidationCommand(command, {
+      cwd,
+      changedFiles: changedFiles.map((file) => file.path),
+      ctx
+    }));
+  }
+  return {
+    syntax: syntaxResults,
+    ...options.format === true ? { format: { ok: false, skipped: true, reason: "no formatter hook configured" } } : {},
+    tests
+  };
+}
+async function readWholeFile(path, maxBytes) {
+  const info = await stat(path);
+  if (info.size > maxBytes) {
+    throw new FilesystemAccessError(`file ${JSON.stringify(path)} exceeds max write/read size`);
+  }
+  const bytes = await readFile3(path);
+  return { text: bytes.toString("utf8"), version: fileVersion(bytes) };
+}
+function checkExpectedVersion(current, expected) {
+  if (expected !== undefined && expected !== current) {
+    return { ok: false, error: `file version mismatch: expected ${expected}, got ${current}` };
+  }
+  return null;
+}
+function stripPatchPath(path) {
+  if (path === undefined || path === "/dev/null")
+    return null;
+  return normalizePathForOutput(path).replace(/^a\//, "").replace(/^b\//, "");
+}
+function filesystemTools(config) {
+  const policy = normalizeFilesystemPolicy(config);
+  const repoMap = defineTool({
+    name: "repo_map",
+    description: "Compact repository overview with directory tree, important files, languages, frameworks, and optional symbols.",
+    parameters: SCHEMAS.repoMap,
+    async execute(args) {
+      try {
+        const root = await resolveRoot(policy, args.root);
+        const depth = bounded(args.depth, 3, 1, 6);
+        const maxEntries = bounded(args.max_entries, policy.maxEntries, 1, 1e4);
+        const listed = await listEntries(root.path, {
+          includeFiles: args.include_files ?? true,
+          respectGitignore: args.respect_gitignore ?? true,
+          maxEntries
+        });
+        const visible = listed.entries.filter((entry) => depthOf(entry.relativePath) <= depth);
+        const symbols2 = args.include_symbols === true ? (await symbolsForPath(policy, root.path, { recursive: true, maxResults: 100 })).results : undefined;
+        return {
+          ok: true,
+          content: {
+            root: root.path,
+            tree: visible.map((entry) => ({
+              path: entry.relativePath,
+              type: entry.type,
+              size: entry.type === "file" ? entry.size : undefined,
+              language: entry.type === "file" ? languageForPath(entry.relativePath) : undefined
+            })),
+            importantFiles: importantFiles(listed.entries),
+            languages: countLanguages(listed.entries),
+            frameworks: detectFrameworks(listed.entries),
+            truncated: listed.truncated || visible.length < listed.entries.length,
+            totalEntries: listed.total,
+            ...symbols2 !== undefined ? { symbols: symbols2 } : {}
+          }
+        };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const findFiles = defineTool({
+    name: "find_files",
+    description: "Find files by exact path, glob, fuzzy name, extension, or regex path pattern.",
+    parameters: SCHEMAS.findFiles,
+    async execute(args) {
+      try {
+        const root = await resolveRoot(policy, args.root);
+        const maxResults = bounded(args.max_results, policy.maxResults, 1, 1000);
+        const mode = modeFor(args.query, args.mode);
+        if (mode === "exact") {
+          const resolved = await resolvePath(policy, args.query, { base: root.path, mustExist: true });
+          const info = await lstat3(resolved.path);
+          return {
+            ok: true,
+            content: {
+              root: root.path,
+              mode,
+              results: [resultEntry(root.path, resolved.path, info.isDirectory() ? "directory" : "file", info.size)],
+              truncated: false
+            }
+          };
+        }
+        const listed = await listEntries(root.path, {
+          includeHidden: args.include_hidden ?? false,
+          respectGitignore: args.respect_gitignore ?? true,
+          maxEntries: Number.POSITIVE_INFINITY,
+          includeGlobs: mode === "glob" ? [args.query] : undefined
+        });
+        let matches = listed.entries;
+        if (mode === "extension") {
+          const ext = args.query.startsWith(".") ? args.query : `.${args.query}`;
+          matches = matches.filter((entry) => entry.type === "file" && extname3(entry.relativePath) === ext);
+        } else if (mode === "regex") {
+          const regex = new RegExp(args.query);
+          matches = matches.filter((entry) => regex.test(entry.relativePath));
+        } else if (mode === "fuzzy") {
+          const fuse = new Fuse(matches, { keys: ["relativePath"], includeScore: true, threshold: 0.45 });
+          const ranked = fuse.search(args.query).slice(0, maxResults);
+          return {
+            ok: true,
+            content: {
+              root: root.path,
+              mode,
+              results: ranked.map((item) => resultEntry(root.path, item.item.path, item.item.type, item.item.size, item.score)),
+              truncated: ranked.length < matches.length && ranked.length >= maxResults
+            }
+          };
+        }
+        return {
+          ok: true,
+          content: {
+            root: root.path,
+            mode,
+            results: matches.slice(0, maxResults).map((entry) => resultEntry(root.path, entry.path, entry.type, entry.size)),
+            truncated: matches.length > maxResults
+          }
+        };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const searchText2 = defineTool({
+    name: "search_text",
+    description: "Search file contents using literal text or regex and return compact previews.",
+    parameters: SCHEMAS.searchText,
+    async execute(args) {
+      try {
+        const root = await resolveRoot(policy, args.root);
+        const result = await searchText(root.path, {
+          pattern: args.pattern,
+          mode: args.mode ?? "literal",
+          includeGlobs: args.include_globs,
+          excludeGlobs: args.exclude_globs,
+          caseSensitive: args.case_sensitive ?? false,
+          contextLines: bounded(args.context_lines, 2, 0, 10),
+          maxResults: bounded(args.max_results, policy.maxResults, 1, 1000),
+          maxPreviewChars: bounded(args.max_preview_chars, 12000, 100, 1e5)
+        });
+        return { ok: true, content: { root: root.path, ...result } };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const searchSemantic2 = defineTool({
+    name: "search_semantic",
+    description: "Find relevant files, chunks, or symbols from a natural-language code query.",
+    parameters: SCHEMAS.searchSemantic,
+    async execute(args) {
+      try {
+        const root = await resolveRoot(policy, args.root);
+        const result = await searchSemantic(root.path, {
+          query: args.query,
+          includeGlobs: args.include_globs,
+          excludeGlobs: args.exclude_globs,
+          granularity: args.granularity ?? "chunk",
+          maxResults: bounded(args.max_results, 20, 1, 1000),
+          maxPreviewChars: bounded(args.max_preview_chars, 12000, 100, 1e5)
+        });
+        return { ok: true, content: { root: root.path, backend: "minisearch", ...result } };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const symbols = defineTool({
+    name: "symbols",
+    description: "Return compact symbols, imports, exports, and line ranges for a file or directory.",
+    parameters: SCHEMAS.symbols,
+    async execute(args) {
+      try {
+        const result = await symbolsForPath(policy, args.path, {
+          recursive: args.recursive ?? false,
+          kinds: args.symbol_kinds,
+          maxResults: bounded(args.max_results, 200, 1, 5000)
+        });
+        return { ok: true, content: result };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const read = defineTool({
+    name: "read",
+    description: "Read exact line ranges or symbol ranges with line numbers and token-aware limits.",
+    parameters: SCHEMAS.read,
+    async execute(args) {
+      try {
+        const resolved = await resolvePath(policy, args.path, { mustExist: true });
+        const maxBytes = bounded(args.max_bytes, policy.maxReadBytes, 1, policy.maxWriteBytes);
+        const file = await readTextFile(resolved.path, maxBytes);
+        const lines = lineOffsets(file.text);
+        let range = clampLineRange(lines.length, args.start_line, args.end_line);
+        if (args.symbol !== undefined) {
+          const found = (await symbolsForFile(resolved.path, resolved.root, maxBytes)).find((symbol) => symbol.name === args.symbol);
+          if (found === undefined)
+            return { ok: false, error: `symbol ${JSON.stringify(args.symbol)} not found` };
+          range = { startLine: found.startLine, endLine: found.endLine };
+        }
+        return {
+          ok: true,
+          content: {
+            path: displayPath(resolved.root, resolved.path),
+            absolutePath: resolved.path,
+            fileVersion: file.version,
+            startLine: range.startLine,
+            endLine: range.endLine,
+            totalLines: lines.length,
+            truncated: file.truncated,
+            content: renderCollapsedLineRange(lines, range.startLine, range.endLine, args.include_line_numbers ?? true, {
+              collapseImports: args.collapse_imports ?? false,
+              collapseComments: args.collapse_comments ?? false
+            })
+          }
+        };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const openWindow = defineTool({
+    name: "open_window",
+    description: "Open or scroll a token-limited viewing window over a file.",
+    parameters: SCHEMAS.openWindow,
+    async execute(args) {
+      try {
+        const resolved = await resolvePath(policy, args.path, { mustExist: true });
+        const file = await readTextFile(resolved.path, policy.maxReadBytes);
+        const lines = lineOffsets(file.text);
+        const windowLines = bounded(args.window_lines, 100, 20, 200);
+        let anchorLine = 1;
+        if (typeof args.anchor === "number") {
+          anchorLine = args.anchor;
+        } else if (typeof args.anchor === "string") {
+          const symbol = (await symbolsForFile(resolved.path, resolved.root, policy.maxReadBytes)).find((item) => item.name === args.anchor);
+          anchorLine = symbol?.startLine ?? Math.max(1, lines.findIndex((line) => line.includes(args.anchor)) + 1);
+        }
+        const direction = args.direction ?? "center";
+        const start = direction === "next" ? anchorLine + 1 : direction === "prev" ? anchorLine - windowLines : anchorLine - Math.floor(windowLines / 2);
+        const range = clampLineRange(lines.length, start, start + windowLines - 1);
+        return {
+          ok: true,
+          content: {
+            path: displayPath(resolved.root, resolved.path),
+            absolutePath: resolved.path,
+            fileVersion: file.version,
+            anchorLine,
+            startLine: range.startLine,
+            endLine: range.endLine,
+            totalLines: lines.length,
+            content: renderLineRange(lines, range.startLine, range.endLine, true)
+          }
+        };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const editReplace = defineTool({
+    name: "edit_replace",
+    description: "Replace exact text in a file with concurrency checks and mismatch diagnostics.",
+    parameters: SCHEMAS.editReplace,
+    async execute(args, ctx) {
+      try {
+        const resolved = await resolvePath(policy, args.path, { mustExist: true });
+        const current = await readWholeFile(resolved.path, policy.maxWriteBytes);
+        const versionError = checkExpectedVersion(current.version, args.expected_file_version);
+        if (versionError !== null)
+          return versionError;
+        const occurrence = args.occurrence ?? 1;
+        let index = -1;
+        let from = 0;
+        for (let i = 0;i < occurrence; i += 1) {
+          index = current.text.indexOf(args.old_text, from);
+          if (index === -1)
+            return { ok: false, error: `old_text occurrence ${occurrence} not found` };
+          from = index + args.old_text.length;
+        }
+        const next = `${current.text.slice(0, index)}${args.new_text}${current.text.slice(index + args.old_text.length)}`;
+        const nextVersion = await atomicWrite(resolved.path, next);
+        const validation = await runValidation(config, args.validate, [{ path: resolved.path, content: next }], dirname4(resolved.path), ctx);
+        return {
+          ok: true,
+          content: {
+            path: displayPath(resolved.root, resolved.path),
+            previousFileVersion: current.version,
+            fileVersion: nextVersion,
+            changed: true,
+            validation
+          }
+        };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const editRange = defineTool({
+    name: "edit_range",
+    description: "Replace a precise line range in a file.",
+    parameters: SCHEMAS.editRange,
+    async execute(args, ctx) {
+      try {
+        const resolved = await resolvePath(policy, args.path, { mustExist: true });
+        const current = await readWholeFile(resolved.path, policy.maxWriteBytes);
+        const versionError = checkExpectedVersion(current.version, args.expected_file_version);
+        if (versionError !== null)
+          return versionError;
+        const lines = lineOffsets(current.text);
+        if (args.end_line < args.start_line)
+          return { ok: false, error: "end_line must be >= start_line" };
+        if (args.start_line > lines.length)
+          return { ok: false, error: "start_line is beyond end of file" };
+        const replacement = args.new_text.replace(/\r\n/g, `
+`).split(`
+`);
+        const nextLines = [
+          ...lines.slice(0, args.start_line - 1),
+          ...replacement,
+          ...lines.slice(args.end_line)
+        ];
+        const next = nextLines.join(`
+`);
+        const nextVersion = await atomicWrite(resolved.path, next);
+        const validation = await runValidation(config, args.validate, [{ path: resolved.path, content: next }], dirname4(resolved.path), ctx);
+        return {
+          ok: true,
+          content: {
+            path: displayPath(resolved.root, resolved.path),
+            previousFileVersion: current.version,
+            fileVersion: nextVersion,
+            changed: true,
+            validation
+          }
+        };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const applyPatch = defineTool({
+    name: "apply_patch",
+    description: "Apply a unified diff patch across one or more files with dry-run and validation support.",
+    parameters: SCHEMAS.applyPatch,
+    async execute(args, ctx) {
+      try {
+        const root = await resolveRoot(policy, args.root);
+        const parsed = parsePatch(args.patch);
+        if (parsed.length === 0)
+          return { ok: false, error: "patch did not contain any file changes" };
+        const dryRun = args.dry_run ?? false;
+        const files = [];
+        const changedFiles = [];
+        for (const patch of parsed) {
+          const relPath = stripPatchPath(patch.newFileName) ?? stripPatchPath(patch.oldFileName);
+          if (relPath === null)
+            return { ok: false, error: "patch file is missing a path" };
+          const resolved = await resolvePath(policy, relPath, { base: root.path, forCreate: true });
+          const current = existsSync3(resolved.path) ? await readWholeFile(resolved.path, policy.maxWriteBytes) : { text: "", version: fileVersion("") };
+          const expected = args.expected_versions?.[relPath] ?? args.expected_versions?.[displayPath(root.path, resolved.path)];
+          const versionError = checkExpectedVersion(current.version, expected);
+          if (versionError !== null)
+            return versionError;
+          const next = applyUnifiedPatch(current.text, patch, { autoConvertLineEndings: true });
+          if (next === false)
+            return { ok: false, error: `patch failed to apply to ${relPath}` };
+          const deleting = stripPatchPath(patch.newFileName) === null;
+          if (!dryRun) {
+            if (deleting)
+              await removeFile(resolved.path);
+            else
+              await atomicWrite(resolved.path, next);
+          }
+          if (!deleting)
+            changedFiles.push({ path: resolved.path, content: next });
+          files.push({
+            path: relPath,
+            changed: true,
+            deleted: deleting,
+            previousFileVersion: current.version,
+            fileVersion: deleting ? undefined : fileVersion(next)
+          });
+        }
+        const validation = dryRun ? undefined : await runValidation(config, args.validate, changedFiles, root.path, ctx);
+        return { ok: true, content: { root: root.path, dryRun, files, validation } };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const writeFileTool = defineTool({
+    name: "write_file",
+    description: "Create, append, or overwrite a file. Prefer patch/range/replace edits for existing files.",
+    parameters: SCHEMAS.writeFile,
+    async execute(args) {
+      try {
+        if (Buffer.byteLength(args.content, "utf8") > policy.maxWriteBytes) {
+          return { ok: false, error: "content exceeds maxWriteBytes" };
+        }
+        const resolved = await resolvePath(policy, args.path, { forCreate: true });
+        const mode = args.mode ?? "create_only";
+        const exists = existsSync3(resolved.path);
+        if (mode === "create_only" && exists)
+          return { ok: false, error: "file already exists" };
+        if ((args.create_dirs ?? true) === false && !existsSync3(dirname4(resolved.path))) {
+          return { ok: false, error: "parent directory does not exist" };
+        }
+        let previousFileVersion;
+        let next = args.content;
+        if (exists) {
+          const current = await readWholeFile(resolved.path, policy.maxWriteBytes);
+          previousFileVersion = current.version;
+          const versionError = checkExpectedVersion(current.version, args.expected_file_version);
+          if (versionError !== null)
+            return versionError;
+          if (mode === "append")
+            next = current.text + args.content;
+        }
+        if (Buffer.byteLength(next, "utf8") > policy.maxWriteBytes) {
+          return { ok: false, error: "resulting file exceeds maxWriteBytes" };
+        }
+        if ((args.create_dirs ?? true) === true)
+          await mkdir2(dirname4(resolved.path), { recursive: true });
+        const nextVersion = await atomicWrite(resolved.path, next);
+        return {
+          ok: true,
+          content: {
+            path: displayPath(resolved.root, resolved.path),
+            previousFileVersion,
+            fileVersion: nextVersion,
+            mode,
+            changed: true
+          }
+        };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  const diffStatus2 = defineTool({
+    name: "diff_status",
+    description: "Return compact Git-style status and diffs for changed files.",
+    parameters: SCHEMAS.diffStatus,
+    async execute(args) {
+      try {
+        const paths = [];
+        for (const path of args.paths ?? []) {
+          const resolved = await resolvePath(policy, path, { mustExist: false });
+          paths.push(displayPath(policy.defaultRoot, resolved.path));
+        }
+        const result = await diffStatus(policy.defaultRoot, {
+          paths,
+          includeDiff: args.include_diff ?? true,
+          maxDiffChars: bounded(args.max_diff_chars, 20000, 100, 1e6),
+          contextLines: bounded(args.context_lines, 3, 0, 20)
+        });
+        return { ok: true, content: { root: policy.defaultRoot, ...result } };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  });
+  return {
+    repoMap,
+    findFiles,
+    searchText: searchText2,
+    searchSemantic: searchSemantic2,
+    symbols,
+    read,
+    openWindow,
+    editReplace,
+    editRange,
+    applyPatch,
+    writeFile: writeFileTool,
+    diffStatus: diffStatus2
+  };
+}
+export {
+  filesystemTools
+};