@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/filesystem/tools.ts

@@ -1,804 +0,0 @@
-/**
- * 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,
-  FILE_SYSTEM_SCAN_LIMIT,
-  type FileSystem,
-  type FileSystemToolName,
-  fileSystemImage,
-  fileSystemText,
-  type GrepContentHit,
-  type GrepOutputMode,
-  type GrepResult,
-  InvalidGrepPatternError,
-  isFileNotFoundError,
-  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 { nearestNeighborMissHint } from "./nearest.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 }) {
-        let content: string | Uint8Array;
-        try {
-          content = await root.read(path);
-        } catch (error) {
-          if (isFileNotFoundError(error)) {
-            const hint = await nearestNeighborMissHint(root, path);
-            if (hint !== undefined) {
-              return hint;
-            }
-          }
-          throw error;
-        }
-        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") {
-          if (listed.error.message.startsWith("Path is not a directory:")) {
-            return `not a directory: ${path} — Read it.`;
-          }
-          if (listed.error.message.startsWith("Path does not exist:")) {
-            const hint = await nearestNeighborMissHint(root, path);
-            if (hint !== undefined) {
-              return hint;
-            }
-          }
-          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 }),
-            limit: FILE_SYSTEM_SCAN_LIMIT,
-          })
-        ).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;
-}