@cursor/july 0.1.103 → 0.1.105

package/src/internal/filesystem/tools.ts

@@ -0,0 +1,821 @@
+/**
+ * Native file tools synthesized from a bound {@link FileSystem}.
+ *
+ * Advertised name / input / output match `@cursor/sdk` tool-call types.
+ * Each tool is a `defineTool` whose runtime `inputSchema` accepts those
+ * fields plus the native aliases the harness still sends.
+ */
+
+import { Buffer } from "node:buffer";
+import { minimatch } from "minimatch";
+import { z } from "zod";
+import {
+  canonicalizeFileSystemToolName,
+  collectGrepMatches,
+  type FileSystem,
+  type FileSystemToolName,
+  fileSystemImage,
+  fileSystemText,
+  type GrepContentHit,
+  type GrepOutputMode,
+  type GrepResult,
+  InvalidGrepPatternError,
+  type SearchResult,
+  shapeGrepUnion,
+  sliceReadContent,
+  strReplaceOnFileSystem,
+} from "../../filesystem.js";
+import { defineTool } from "../../tools.js";
+import type { DiscoveredTool, ToolDefinition } from "../../types.js";
+import {
+  toolInputJsonSchema,
+  toolOutputJsonSchema,
+  validateToolInput,
+} from "../json-schema.js";
+import {
+  formatGlobOutput,
+  formatGrepOutput,
+  formatLsTree,
+  formatNumberedLines,
+  formatStrReplaceOutput,
+  formatWriteOutput,
+  slicedReadStartLine,
+} from "./format.js";
+import {
+  sdkDeleteArgs,
+  sdkDeleteResult,
+  sdkEditResult,
+  sdkGlobArgs,
+  sdkGlobResult,
+  sdkGrepArgs,
+  sdkGrepResult,
+  sdkLsArgs,
+  sdkLsResult,
+  sdkReadArgs,
+  sdkReadResult,
+  sdkSemSearchArgs,
+  sdkSemSearchResult,
+  sdkStrReplaceArgs,
+  sdkWriteArgs,
+  sdkWriteResult,
+} from "./sdk-schemas.js";
+import { collectGlob, collectListOrStat, lsFromList } from "./walk.js";
+
+export const SYNTHESIZED_FILE_SYSTEM_TOOL_NAMES = [
+  "Read",
+  "LS",
+  "Glob",
+  "Grep",
+  "Write",
+  "StrReplace",
+  "Delete",
+  "SemanticSearch",
+] as const;
+
+export type SynthesizedFileSystemToolName =
+  (typeof SYNTHESIZED_FILE_SYSTEM_TOOL_NAMES)[number];
+
+const SYNTHESIZED_NAME_SET = new Set<string>(
+  SYNTHESIZED_FILE_SYSTEM_TOOL_NAMES
+);
+
+export function isSynthesizedFileSystemToolName(name: string): boolean {
+  if (SYNTHESIZED_NAME_SET.has(name)) {
+    return true;
+  }
+  const canonical = canonicalizeFileSystemToolName(name);
+  return canonical !== undefined && SYNTHESIZED_NAME_SET.has(canonical);
+}
+
+export function rootFileToolsFromAuthored(
+  tools: readonly string[] | undefined
+): FileSystemToolName[] | undefined {
+  if (tools === undefined) {
+    return undefined;
+  }
+  if (tools.length === 0) {
+    return [];
+  }
+  const files: FileSystemToolName[] = [];
+  for (const name of tools) {
+    if (name === "edit") {
+      files.push("Write", "StrReplace");
+      continue;
+    }
+    const canonical = canonicalizeFileSystemToolName(name);
+    if (canonical !== undefined) {
+      files.push(canonical);
+    }
+  }
+  return files.length === 0 ? undefined : [...new Set(files)];
+}
+
+/**
+ * Host-default file-tool filter. Omitted `tools` keeps the default
+ * seven-tool set (`undefined`). A listed allowlist is closed: names that
+ * are not FileSystem methods synthesize nothing, so agents that already
+ * replaced natives with authored VFS tools (`tools: ["updateTodos"]` plus
+ * `agent/tools/Delete.ts`) do not also get host-disk Delete.
+ *
+ * Authored `root` still uses {@link rootFileToolsFromAuthored}, where a
+ * no-file-name allowlist means the default-on file layer.
+ */
+export function hostFileToolsFromAuthored(
+  tools: readonly string[] | undefined
+): FileSystemToolName[] | undefined {
+  if (tools === undefined) {
+    return undefined;
+  }
+  return rootFileToolsFromAuthored(tools) ?? [];
+}
+
+const HOST_DEFAULT_SYNTHESIZED_NAMES: readonly SynthesizedFileSystemToolName[] =
+  SYNTHESIZED_FILE_SYSTEM_TOOL_NAMES.filter(
+    (name) => name !== "SemanticSearch"
+  );
+
+/**
+ * Names July will actually synthesize for this agent. Discovery reserves
+ * only this set, not every FileSystem alias.
+ */
+export function synthesizedFileSystemToolNames(options: {
+  hasRoot: boolean;
+  tools?: readonly string[];
+}): readonly SynthesizedFileSystemToolName[] {
+  const filter = options.hasRoot
+    ? rootFileToolsFromAuthored(options.tools)
+    : hostFileToolsFromAuthored(options.tools);
+  const catalog = options.hasRoot
+    ? SYNTHESIZED_FILE_SYSTEM_TOOL_NAMES
+    : HOST_DEFAULT_SYNTHESIZED_NAMES;
+  if (filter === undefined) {
+    return catalog;
+  }
+  return catalog.filter((name) => filter.includes(name));
+}
+
+function wantsTool(
+  filter: readonly FileSystemToolName[] | undefined,
+  name: FileSystemToolName
+): boolean {
+  return filter === undefined || filter.includes(name);
+}
+
+/**
+ * Copy native aliases onto the canonical SDK field when the canonical
+ * field is absent. Zod sees the SDK shape; callers can still send
+ * `contents` / `old_string` / `output_mode`.
+ */
+function aliasKeys(aliases: Record<string, string>) {
+  return (raw: unknown): unknown => {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      return raw;
+    }
+    const input = { ...(raw as Record<string, unknown>) };
+    for (const [from, to] of Object.entries(aliases)) {
+      if (input[to] === undefined && input[from] !== undefined) {
+        input[to] = input[from];
+      }
+    }
+    return input;
+  };
+}
+
+function lineCount(content: string): number {
+  return content === "" ? 0 : content.split("\n").length;
+}
+
+function parseGrepOutputMode(value: string | undefined): GrepOutputMode {
+  if (value === "files" || value === "files_with_matches") {
+    return "files_with_matches";
+  }
+  if (value === "count") {
+    return "count";
+  }
+  return "content";
+}
+
+function contextLineCount(
+  specific: number | undefined,
+  both: number | undefined
+): number {
+  const value = specific ?? both;
+  if (value === undefined || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.floor(value));
+}
+
+function compileToolGrepPattern(
+  pattern: string,
+  options: { caseInsensitive?: boolean; multiline?: boolean }
+): RegExp {
+  try {
+    const flags = `${options.caseInsensitive === true ? "i" : ""}${
+      options.multiline === true ? "s" : ""
+    }`;
+    return new RegExp(pattern, flags === "" ? undefined : flags);
+  } catch {
+    throw new InvalidGrepPatternError(pattern);
+  }
+}
+
+/**
+ * File discovery for multiline Grep. A file `path` is that file (the
+ * caller spelling, so host-default relative paths stay relative). A
+ * directory or omitted path uses `FileSystem.glob`, which applies the
+ * mount's own root. Slash-free globs are recursive, matching line grep.
+ */
+async function collectMultilineGrepFiles(
+  root: FileSystem,
+  input: { path?: string; glob?: string }
+): Promise<string[]> {
+  const listed = await collectListOrStat(root, input.path);
+  if (listed.kind === "file") {
+    const filePath = input.path ?? "";
+    if (
+      input.glob !== undefined &&
+      !fileMatchesGrepGlob(filePath, input.glob)
+    ) {
+      return [];
+    }
+    return [filePath];
+  }
+  if (listed.kind === "missing") {
+    return [];
+  }
+  const entries = await collectGlob(root, {
+    pattern: recursiveGrepGlob(input.glob),
+    ...(input.path === undefined ? {} : { dir: input.path }),
+  });
+  return entries.map((entry) => entry.path);
+}
+
+function recursiveGrepGlob(glob: string | undefined): string {
+  if (glob === undefined || glob.length === 0) {
+    return "**/*";
+  }
+  if (glob.startsWith("**/") || glob.includes("/")) {
+    return glob;
+  }
+  return `**/${glob}`;
+}
+
+function fileMatchesGrepGlob(filePath: string, globPattern: string): boolean {
+  const relative = filePath.replace(/^\//, "");
+  if (
+    minimatch(relative, globPattern, { dot: true }) ||
+    minimatch(filePath, globPattern, { dot: true })
+  ) {
+    return true;
+  }
+  if (!globPattern.includes("/")) {
+    const slash = Math.max(
+      relative.lastIndexOf("/"),
+      relative.lastIndexOf("\\")
+    );
+    const base = slash === -1 ? relative : relative.slice(slash + 1);
+    return minimatch(base, globPattern, { dot: true });
+  }
+  return false;
+}
+
+function multilineHitsInContent(
+  path: string,
+  content: string,
+  regex: RegExp
+): GrepResult[] {
+  const global = new RegExp(
+    regex.source,
+    regex.flags.includes("g") ? regex.flags : `${regex.flags}g`
+  );
+  const hits: GrepResult[] = [];
+  let match = global.exec(content);
+  while (match !== null) {
+    hits.push({
+      path,
+      lineNumber: content.slice(0, match.index).split("\n").length,
+      line: content.slice(match.index).split("\n")[0] ?? "",
+    });
+    if (match[0].length === 0) {
+      global.lastIndex += 1;
+    }
+    match = global.exec(content);
+  }
+  return hits;
+}
+
+async function collectMultilineGrepMatches(
+  root: FileSystem,
+  input: {
+    pattern: string;
+    path?: string;
+    glob?: string;
+    caseInsensitive?: boolean;
+  },
+  opts: { outputMode: GrepOutputMode; headLimit?: number; offset?: number }
+): Promise<GrepResult[]> {
+  const regex = compileToolGrepPattern(input.pattern, {
+    caseInsensitive: input.caseInsensitive,
+    multiline: true,
+  });
+  const files = await collectMultilineGrepFiles(root, input);
+  const matches: GrepResult[] = [];
+  const offset = opts.offset !== undefined && opts.offset > 0 ? opts.offset : 0;
+  const headLimit =
+    opts.headLimit !== undefined && opts.headLimit > 0
+      ? opts.headLimit
+      : undefined;
+  let skippedItems = 0;
+  let takenItems = 0;
+  for (const filePath of files) {
+    let content: string | Uint8Array;
+    try {
+      content = await root.read(filePath);
+    } catch {
+      continue;
+    }
+    if (typeof content !== "string") {
+      continue;
+    }
+    const hits = multilineHitsInContent(filePath, content, regex);
+    if (hits.length === 0) {
+      continue;
+    }
+    if (opts.outputMode === "content") {
+      for (const hit of hits) {
+        if (skippedItems < offset) {
+          skippedItems++;
+          continue;
+        }
+        matches.push(hit);
+        takenItems++;
+        if (headLimit !== undefined && takenItems >= headLimit) {
+          return matches;
+        }
+      }
+      continue;
+    }
+    if (skippedItems < offset) {
+      skippedItems++;
+      continue;
+    }
+    if (headLimit !== undefined && takenItems >= headLimit) {
+      break;
+    }
+    matches.push(...hits);
+    takenItems++;
+  }
+  return matches;
+}
+
+async function attachGrepContext(
+  root: FileSystem,
+  matches: GrepResult[],
+  context: { before: number; after: number }
+): Promise<GrepContentHit[]> {
+  if (context.before === 0 && context.after === 0) {
+    return matches;
+  }
+  const linesByPath = new Map<string, string[]>();
+  const hits: GrepContentHit[] = [];
+  for (const match of matches) {
+    let lines = linesByPath.get(match.path);
+    if (lines === undefined) {
+      try {
+        const content = await root.read(match.path);
+        lines = typeof content === "string" ? content.split("\n") : [];
+      } catch {
+        lines = [];
+      }
+      linesByPath.set(match.path, lines);
+    }
+    const index = match.lineNumber - 1;
+    hits.push({
+      ...match,
+      ...(context.before > 0
+        ? {
+            beforeContext: lines.slice(
+              Math.max(0, index - context.before),
+              Math.max(0, index)
+            ),
+          }
+        : {}),
+      ...(context.after > 0
+        ? { afterContext: lines.slice(index + 1, index + 1 + context.after) }
+        : {}),
+    });
+  }
+  return hits;
+}
+
+function discovered(
+  name: FileSystemToolName,
+  definition: ToolDefinition,
+  contract: { input: z.ZodTypeAny; output: z.ZodTypeAny }
+): DiscoveredTool {
+  const effect =
+    typeof definition.effect === "function" ? "dynamic" : definition.effect;
+  return {
+    name,
+    description: definition.description,
+    inputSchema: toolInputJsonSchema(contract.input),
+    outputSchema: toolOutputJsonSchema(contract.output),
+    execution: "server",
+    needsApproval: false,
+    ...(effect === undefined ? {} : { effect }),
+    definition,
+  };
+}
+
+const readInputSchema = z.preprocess(
+  aliasKeys({}),
+  z.object({
+    path: z.string(),
+    offset: z.number().int().optional(),
+    limit: z.number().int().optional(),
+  })
+);
+
+function readTool(root: FileSystem): DiscoveredTool {
+  return discovered(
+    "Read",
+    defineTool({
+      description:
+        "Reads a file from the local filesystem. This tool can also read image files when called with the appropriate path. Formats supported: jpeg/jpg, png, gif, webp.",
+      inputSchema: readInputSchema,
+      effect: "read",
+      async execute({ path, offset, limit }) {
+        const content = await root.read(path);
+        const image = fileSystemImage(content, path);
+        if (image !== undefined) {
+          return {
+            content: [
+              { type: "text" as const, text: `Read image file: ${path}` },
+              {
+                type: "image" as const,
+                data: Buffer.from(image.bytes).toString("base64"),
+                mimeType: image.mimeType,
+              },
+            ],
+          };
+        }
+        const text = fileSystemText(content);
+        const totalLines = lineCount(text);
+        return formatNumberedLines(sliceReadContent(text, offset, limit), {
+          startLine: slicedReadStartLine(totalLines, offset),
+          totalLines,
+        });
+      },
+    }),
+    { input: sdkReadArgs, output: sdkReadResult }
+  );
+}
+
+const lsInputSchema = z.preprocess(
+  aliasKeys({ target_directory: "path", ignore_globs: "ignore" }),
+  z.object({
+    path: z.string(),
+    ignore: z.array(z.string()).optional(),
+  })
+);
+
+function lsTool(root: FileSystem): DiscoveredTool {
+  return discovered(
+    "LS",
+    defineTool({
+      description: `Lists files and directories in a given path.
+The 'path' parameter must be an absolute path.
+You can optionally provide an array of glob patterns to ignore with the "ignore" parameter.
+
+Other details:
+- The result does not display dot-files and dot-directories.`,
+      inputSchema: lsInputSchema,
+      effect: "read",
+      async execute({ path, ignore }) {
+        const listed = await lsFromList(root, path, ignore);
+        if (listed.status === "error") {
+          throw new Error(`Error listing directory: ${listed.error.message}`);
+        }
+        return formatLsTree(listed.value.directoryTreeRoot);
+      },
+    }),
+    { input: sdkLsArgs, output: sdkLsResult }
+  );
+}
+
+const globInputSchema = z.preprocess(
+  aliasKeys({
+    glob_pattern: "globPattern",
+    target_directory: "targetDirectory",
+    path: "targetDirectory",
+  }),
+  z.object({
+    targetDirectory: z.string().optional(),
+    globPattern: z.string(),
+  })
+);
+
+function globTool(root: FileSystem): DiscoveredTool {
+  return discovered(
+    "Glob",
+    defineTool({
+      description: `
+Tool to search for files matching a glob pattern
+
+- Works fast with codebases of any size
+- Returns matching file paths sorted by modification time
+- Use this tool when you need to find files by name patterns
+- You have the capability to call multiple tools in a single response. It is always better to speculatively perform multiple searches that are potentially useful as a batch.
+`,
+      inputSchema: globInputSchema,
+      effect: "read",
+      async execute({ globPattern, targetDirectory }) {
+        const dir = targetDirectory ?? "/";
+        const files = (
+          await collectGlob(root, {
+            pattern: globPattern,
+            ...(targetDirectory === undefined ? {} : { dir: targetDirectory }),
+          })
+        ).map((entry) => entry.path);
+        return formatGlobOutput(dir, files);
+      },
+    }),
+    { input: sdkGlobArgs, output: sdkGlobResult }
+  );
+}
+
+const grepInputSchema = z.preprocess(
+  (raw) => {
+    const aliased = aliasKeys({
+      output_mode: "outputMode",
+      head_limit: "headLimit",
+      "-i": "caseInsensitive",
+      "-A": "contextAfter",
+      "-B": "contextBefore",
+      "-C": "context",
+    })(raw);
+    if (
+      aliased !== null &&
+      typeof aliased === "object" &&
+      !Array.isArray(aliased)
+    ) {
+      const input = aliased as { outputMode?: unknown };
+      if (input.outputMode === "files") {
+        input.outputMode = "files_with_matches";
+      }
+    }
+    return aliased;
+  },
+  z.object({
+    pattern: z.string(),
+    path: z.string().optional(),
+    glob: z.string().optional(),
+    outputMode: z.string().optional(),
+    contextBefore: z.number().optional(),
+    contextAfter: z.number().optional(),
+    context: z.number().optional(),
+    caseInsensitive: z.boolean().optional(),
+    type: z.string().optional(),
+    headLimit: z.number().optional(),
+    offset: z.number().optional(),
+    multiline: z.boolean().optional(),
+    sort: z.string().optional(),
+    sortAscending: z.boolean().optional(),
+  })
+);
+
+function grepTool(root: FileSystem): DiscoveredTool {
+  return discovered(
+    "Grep",
+    defineTool({
+      description: `A search tool built on ripgrep. Results are capped to several thousand output lines for responsiveness; when truncation occurs, the results report "at least" counts, but are otherwise accurate.`,
+      inputSchema: grepInputSchema,
+      effect: "read",
+      async execute(input) {
+        const outputMode = parseGrepOutputMode(input.outputMode);
+        const query = {
+          pattern: input.pattern,
+          ...(input.path === undefined ? {} : { path: input.path }),
+          ...(input.glob === undefined ? {} : { glob: input.glob }),
+          caseInsensitive: input.caseInsensitive === true,
+        };
+        const page = {
+          outputMode,
+          ...(input.headLimit === undefined
+            ? {}
+            : { headLimit: input.headLimit }),
+          ...(input.offset === undefined ? {} : { offset: input.offset }),
+        };
+        const matches =
+          input.multiline === true
+            ? await collectMultilineGrepMatches(root, query, page)
+            : await collectGrepMatches(root, query, page);
+        const before = contextLineCount(input.contextBefore, input.context);
+        const after = contextLineCount(input.contextAfter, input.context);
+        const hits =
+          outputMode === "content"
+            ? await attachGrepContext(root, matches, { before, after })
+            : matches;
+        return formatGrepOutput(shapeGrepUnion(hits, outputMode));
+      },
+    }),
+    { input: sdkGrepArgs, output: sdkGrepResult }
+  );
+}
+
+const writeInputSchema = z.preprocess(
+  aliasKeys({ contents: "fileText" }),
+  z.object({
+    path: z.string(),
+    fileText: z.string(),
+    returnFileContentAfterWrite: z.boolean().optional(),
+  })
+);
+
+function writeTool(root: FileSystem): DiscoveredTool {
+  return discovered(
+    "Write",
+    defineTool({
+      description: "Writes a file to the local filesystem.",
+      inputSchema: writeInputSchema,
+      effect: "write",
+      async execute({ path, fileText }) {
+        await root.write(path, fileText);
+        return formatWriteOutput(path);
+      },
+    }),
+    { input: sdkWriteArgs, output: sdkWriteResult }
+  );
+}
+
+const strReplaceInputSchema = z.preprocess(
+  aliasKeys({
+    old_string: "oldText",
+    new_string: "newText",
+    replace_all: "replaceAll",
+  }),
+  z.object({
+    path: z.string(),
+    oldText: z.string(),
+    newText: z.string(),
+    replaceAll: z.boolean().optional(),
+  })
+);
+
+function strReplaceTool(root: FileSystem): DiscoveredTool {
+  return discovered(
+    "StrReplace",
+    defineTool({
+      description: "Performs exact string replacements in files.",
+      inputSchema: strReplaceInputSchema,
+      effect: "write",
+      async execute({ path, oldText, newText, replaceAll }) {
+        const { occurrencesModified } = await strReplaceOnFileSystem(root, {
+          path,
+          oldText,
+          newText,
+          ...(replaceAll === undefined ? {} : { replaceAll }),
+        });
+        return formatStrReplaceOutput({
+          path,
+          replaceAll: replaceAll === true,
+          occurrencesModified,
+        });
+      },
+    }),
+    { input: sdkStrReplaceArgs, output: sdkEditResult }
+  );
+}
+
+const deleteInputSchema = z.object({
+  path: z.string(),
+});
+
+function deleteTool(root: FileSystem): DiscoveredTool {
+  return discovered(
+    "Delete",
+    defineTool({
+      description: `Deletes a file at the specified path. The operation will fail gracefully if:
+    - The file doesn't exist
+    - The operation is rejected for security reasons
+    - The file cannot be deleted`,
+      inputSchema: deleteInputSchema,
+      effect: "write",
+      async execute({ path }) {
+        await root.delete(path);
+        return "";
+      },
+    }),
+    { input: sdkDeleteArgs, output: sdkDeleteResult }
+  );
+}
+
+const semanticSearchInputSchema = z.preprocess(
+  aliasKeys({ num_results: "numResults" }),
+  z.object({
+    query: z.string(),
+    targetDirectories: z.array(z.string()).optional(),
+    explanation: z.string().optional(),
+    numResults: z.number().optional(),
+  })
+);
+
+function semanticSearchTool(root: FileSystem): DiscoveredTool {
+  return discovered(
+    "SemanticSearch",
+    defineTool({
+      description:
+        "`SemanticSearch`: semantic search that finds code by meaning, not exact text",
+      inputSchema: semanticSearchInputSchema,
+      effect: "read",
+      async execute({ query, targetDirectories, numResults }) {
+        const cap =
+          numResults !== undefined && numResults > 0 ? numResults : undefined;
+        const hits: SearchResult[] = [];
+        for await (const hit of root.search({
+          query,
+          ...(targetDirectories === undefined ? {} : { targetDirectories }),
+          ...(cap === undefined ? {} : { maxResults: cap }),
+        })) {
+          hits.push(hit);
+          if (cap !== undefined && hits.length >= cap) {
+            break;
+          }
+        }
+        return hits.map((hit) => `${hit.path}: ${hit.snippet}`).join("\n");
+      },
+    }),
+    { input: sdkSemSearchArgs, output: sdkSemSearchResult }
+  );
+}
+
+const FILE_SYSTEM_TOOL_FACTORIES: Record<
+  FileSystemToolName,
+  (root: FileSystem) => DiscoveredTool
+> = {
+  Read: readTool,
+  LS: lsTool,
+  Glob: globTool,
+  Grep: grepTool,
+  Write: writeTool,
+  StrReplace: strReplaceTool,
+  Delete: deleteTool,
+  SemanticSearch: semanticSearchTool,
+};
+
+/**
+ * Look up the `defineTool` factory for a native or allowlist name.
+ * The only name that still inspects `input` is legacy `edit`:
+ * `fileText` / `contents` selects Write, otherwise StrReplace.
+ */
+export function fileSystemTool(
+  root: FileSystem,
+  name: string,
+  input: Record<string, unknown> = {}
+): DiscoveredTool | undefined {
+  if (name === "edit") {
+    return "fileText" in input || "contents" in input
+      ? writeTool(root)
+      : strReplaceTool(root);
+  }
+  const canonical = canonicalizeFileSystemToolName(name);
+  if (canonical === undefined) {
+    return undefined;
+  }
+  return FILE_SYSTEM_TOOL_FACTORIES[canonical](root);
+}
+
+/** Validate and run the same tool a turn or `callTool` would. */
+export async function runFileSystemTool(
+  root: FileSystem,
+  name: string,
+  input: Record<string, unknown> = {}
+): Promise<unknown> {
+  const tool = fileSystemTool(root, name, input);
+  if (tool === undefined) {
+    throw new Error(`Unknown file system tool: ${name}`);
+  }
+  const execute = tool.definition.execute;
+  if (typeof execute !== "function") {
+    throw new Error(`File system tool ${name} has no execute`);
+  }
+  const validation = validateToolInput(tool.definition.inputSchema, input);
+  if (!validation.ok) {
+    throw new Error(validation.message);
+  }
+  return execute(validation.value as never, {} as never);
+}
+
+export function synthesizeFileSystemTools(
+  root: FileSystem,
+  filter?: readonly FileSystemToolName[]
+): DiscoveredTool[] {
+  const tools: DiscoveredTool[] = [];
+  for (const name of SYNTHESIZED_FILE_SYSTEM_TOOL_NAMES) {
+    if (wantsTool(filter, name)) {
+      tools.push(FILE_SYSTEM_TOOL_FACTORIES[name](root));
+    }
+  }
+  return tools;
+}