@cursor/bdk 0.2.3 → 0.2.4

package/src/filesystem.ts

@@ -1,2005 +0,0 @@
-import { Buffer } from "node:buffer";
-import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import path from "node:path";
-import type { ToolName } from "@cursor/sdk";
-import { minimatch } from "minimatch";
-import { FileConflictError } from "./files.js";
-import {
-  EditError,
-  FileNotFoundError,
-  InvalidGrepPatternError,
-  isFileNotFoundError,
-  isInvalidGrepPatternError,
-  NoMountError,
-  PathError,
-  ReadOnlyMountError,
-  remapPathError,
-  WriteFailedError,
-} from "./internal/filesystem/errors.js";
-import { MEMORY_DIR_NAME } from "./memory.js";
-
-export {
-  DeleteNotSupportedError,
-  EditError,
-  FileNotFoundError,
-  InvalidGrepPatternError,
-  isFileNotFoundError,
-  isInvalidGrepPatternError,
-  NoMountError,
-  PathError,
-  ReadOnlyMountError,
-  WriteFailedError,
-} from "./internal/filesystem/errors.js";
-
-import { mergeSorted } from "./internal/filesystem/merge.js";
-import {
-  isExcludedPath,
-  listFilesFromPaths,
-  mergeSortedByPath,
-  statFromFilePaths,
-} from "./internal/filesystem/walk.js";
-import type { HostFilesApi, HostFilesScope } from "./types.js";
-
-/**
- * Status envelope used by walk helpers such as `lsFromList`.
- * FileSystem methods throw; they do not return this.
- * `@cursor/bdk` does not export it.
- */
-export type FileSystemResult<T> =
-  | { status: "success"; value: T }
-  | { status: "error"; error: { message: string } };
-
-/**
- * One file in a `list` / `glob` stream.
- *
- * `path` is an absolute posix path (`/src/a.ts`). No trailing slash
- * except `/`. `size` is optional byte length of the file contents.
- */
-export interface DirEntry {
-  path: string;
-  size?: number;
-}
-
-/**
- * Existence probe. `directory` means this path is a prefix of at
- * least one file (virtual trees infer directories) or a real
- * directory on disk. `missing` is a value, not an error.
- */
-export type FileInfo = { kind: "file" } | { kind: "directory" } | { kind: "missing" };
-
-/**
- * Native Grep `output_mode` envelope. Not a FileSystem method
- * result. The `grep` verb yields {@link GrepResult}; synthesis
- * shapes this union after draining the stream.
- */
-export type GrepUnionResult =
-  | {
-      type: "content";
-      output: {
-        matches: Array<{
-          file: string;
-          lineNumber?: number;
-          line: string;
-          beforeContext?: string[];
-          afterContext?: string[];
-        }>;
-        totalMatches: number;
-      };
-    }
-  | { type: "files"; output: { files: string[]; count: number } }
-  | {
-      type: "count";
-      output: {
-        counts: Array<{ file: string; count: number }>;
-        total: number;
-      };
-    };
-
-/**
- * One content hit from `grep`. `path` is absolute posix.
- * `lineNumber` is 1-indexed. `line` is the full matching line,
- * without the trailing newline.
- */
-export interface GrepResult {
-  path: string;
-  lineNumber: number;
-  line: string;
-}
-
-/**
- * Optional filters for {@link FileSystem.list}.
- *
- * `excludes` are ignore globs in the same language as native LS
- * `ignore`: a slash-free pattern matches at any depth, and a
- * directory match drops that tree. Implementations that can push
- * them to a backend should; others filter the yielded files.
- * Native LS still applies `ignore` after `list` so a mount that
- * ignores this argument still honors it.
- */
-export interface ListOptions {
-  excludes?: readonly string[];
-  /**
-   * Optional result cap, lexicographic. Omitted means no
-   * FileSystem-level cap. `0` yields nothing.
-   */
-  limit?: number;
-}
-
-/**
- * Optional filters for {@link FileSystem.glob}.
- *
- * `limit` is the same lexicographic cap as {@link ListOptions.limit}.
- */
-export interface GlobOptions {
-  limit?: number;
-}
-
-/**
- * Default scan cap for synthesized LS / Glob and for Origin
- * `ListRepoPaths` from `/repo`. Smaller than Origin's 10k default
- * so a recursive listing does not materialize a huge response.
- */
-export const FILE_SYSTEM_SCAN_LIMIT = 1_000;
-
-/**
- * Content-search query. No `output_mode` or `offset` (those
- * belong to the native Grep tool).
- *
- * `pattern` is a JavaScript regular expression source. Invalid
- * source must throw {@link InvalidGrepPatternError} with message
- * `invalid grep pattern: ${pattern}`. `path` omitted / `""` /
- * `"/"` searches the whole tree; a file path searches that file
- * only. A slash-free `glob` (`*.ts`) matches the basename at any
- * depth under `path`.
- *
- * `excludes` are optional ignore globs (same language as
- * {@link ListOptions.excludes}). Implementations that can push
- * them to a backend should; others skip matching files. Native
- * Grep has no ignore field; this is FileSystem-only pushdown.
- *
- * `maxResults` is optional predicate pushdown: stop after this
- * many hits so a remote or large tree does not materialize a
- * full scan. Native Grep still applies `head_limit` / `offset`
- * after the merge. Omitted means no FileSystem-level cap.
- */
-export interface GrepQuery {
-  pattern: string;
-  path?: string;
-  glob?: string;
-  excludes?: readonly string[];
-  caseInsensitive?: boolean;
-  maxResults?: number;
-}
-
-/**
- * One semantic hit from `search`. `path` is absolute posix.
- * `score` is higher-is-better. Trees without an index yield
- * nothing; they do not invent lexical stand-ins.
- */
-export interface SearchResult {
-  path: string;
-  snippet: string;
-  score: number;
-}
-
-/**
- * Semantic-search query. `targetDirectories` limits the scan
- * when an index exists; omitted means the whole tree.
- *
- * `maxResults` is optional predicate pushdown: stop after this
- * many hits so an index does not retrieve a large recall set.
- * Native SemanticSearch still applies `numResults` after the
- * merge. Omitted means no FileSystem-level cap.
- */
-export interface SearchQuery {
-  query: string;
-  targetDirectories?: string[];
-  maxResults?: number;
-}
-
-/**
- * Exact, non-overlapping str-replace. `oldText` / `newText` are
- * literal strings, not regex. Splice must keep `$`, `$&`, `$1`
- * in `newText` as written (`String.prototype.replace` must not
- * be used).
- */
-export interface EditQuery {
-  path: string;
-  oldText: string;
-  newText: string;
-  replaceAll?: boolean;
-}
-
-/**
- * StrReplace success. `occurrencesModified` is the number of
- * non-overlapping replacements (1 unless `replaceAll`).
- */
-export interface EditResult {
-  occurrencesModified: number;
-}
-
-/**
- * Path verbs for the tree the agent runs on.
- *
- * Every method is required. Trees without an index implement
- * `search` as an empty iterator. Methods do not fall back to the
- * host tree. Diagnostics are not a FileSystem concern.
- *
- * Paths are a single posix namespace rooted at `/`. Query paths
- * and yielded paths are absolute (`/src/a.ts`). No trailing
- * slash except `/`. `""`, `"/"`, and an omitted `prefix` / `dir`
- * / `path` (where optional) mean the root. Prefix tests are
- * path-segment: `/agent` matches `/agent/skills`, not
- * `/agent-tools`.
- *
- * Async iterators are already sorted. `unionFs` k-way merges
- * them and does not re-sort a source.
- *
- * - `list` / `glob`: lexicographic by `path`. Paths are unique.
- * - `grep`: by `path`, then `lineNumber` ascending. Keep every hit.
- * - `search`: by `score` descending, then `path` ascending.
- *
- * Native-tool pagination (`head_limit`, `offset`, `output_mode`,
- * `numResults`) stays on the synthesized tools. `grep` /
- * `search` take optional `maxResults` as predicate pushdown so
- * a tree can stop retrieving once the tool's cap is known.
- * Native `LS` is built from `list` + `stat`; there is no `ls`
- * method.
- *
- * Errors (authors must follow these, not invent parallel
- * spellings):
- *
- * - `list` / `stat` / `glob` must not throw for a missing path.
- *   Missing is an empty iterator or `{ kind: "missing" }`.
- * - `read` / `write` / `delete` throw {@link PathError}
- *   for recoverable failures. `error.message` is the string the
- *   synthesized native tool shows the model. `error.path` is the
- *   absolute posix path the composer remaps.
- * - `grep` throws for an invalid regex (and a missing host
- *   search root). A missing virtual path yields nothing.
- * - `search` yields nothing when there is no index. An index
- *   failure may throw.
- * - Missing-file message on `read` / `delete` is
- *   `not found: ${path}` (normalized absolute posix).
- */
-export interface FileSystem {
-  /**
-   * Recursive file scan under `prefix`. Files only; directories
-   * are inferred from path prefixes. A file is not under itself,
-   * so listing a file path is empty. Empty is not "missing"
-   * (`stat` answers that). Yields lexicographic unique
-   * {@link DirEntry} rows. Omitted / `""` / `"/"` means the root.
-   *
-   * Errors: none. A missing or file-path prefix yields an empty
-   * iterator. Do not throw.
-   *
-   * `options.excludes` / `options.limit` are optional pushdown.
-   * See {@link ListOptions}.
-   */
-  list(prefix?: string, options?: ListOptions): AsyncIterable<DirEntry>;
-  /**
-   * Existence probe: exact file, a prefix that has files, or
-   * missing. Does not throw. Native LS lists first and calls
-   * this only when the iterator is empty.
-   *
-   * Errors: none. Unknown paths are `{ kind: "missing" }`.
-   */
-  stat(path: string): Promise<FileInfo>;
-  /**
-   * Same scan as `list`, filtered by `pattern` relative to
-   * `dir`. Yields lexicographic unique {@link DirEntry} rows.
-   * `dir` omitted / `""` / `"/"` means the tree root. Matching
-   * is relative to `dir`, not basename-anywhere (`*.ts` under
-   * `/src` is `/src/a.ts`, not `/src/nested/c.ts`).
-   *
-   * Errors: none. A missing `dir` or a pattern that matches
-   * nothing yields an empty iterator. Do not throw for a bad
-   * glob (it matches nothing).
-   *
-   * `options.limit` is optional result-cap pushdown. See
-   * {@link GlobOptions}.
-   */
-  glob(pattern: string, dir?: string, options?: GlobOptions): AsyncIterable<DirEntry>;
-  /**
-   * Read the whole file. Text files return a string. Image
-   * bytes (`jpeg` / `png` / `gif` / `webp`) return a
-   * `Uint8Array` so native Read can base64 them into an image
-   * content part. Native Read applies `offset` / `limit` and
-   * numbers lines on text only.
-   *
-   * Errors (throw `Error`):
-   * - Missing file, or a virtual directory with no file inode:
-   *   `not found: ${path}`.
-   * - Host I/O (EISDIR, EACCES, …): the OS message, or the same
-   *   `not found: ${path}` fallback.
-   * - `unionFs` with no mount: `no mount for path: ${path}`.
-   */
-  read(path: string): Promise<string | Uint8Array>;
-  /**
-   * Content matches. No output-mode or offset. Honor
-   * `maxResults` when set. Yields {@link GrepResult} ordered
-   * by path, then line number.
-   *
-   * Errors (throw `Error`):
-   * - Invalid `pattern`: `invalid grep pattern: ${pattern}`.
-   * - Host search root does not exist: the OS message, or
-   *   `not found: ${searchRoot}`. Native Grep turns the throw
-   *   into `{ status: "error" }`.
-   *
-   * A missing virtual `path` yields nothing (not an error).
-   */
-  grep(query: GrepQuery): AsyncIterable<GrepResult>;
-  /**
-   * Create or overwrite a file. Parents are created as needed.
-   * Native Write formats `Wrote contents to ${path}` from the
-   * path. The Write tool maps native `fileText` onto `contents`.
-   *
-   * Errors (throw `Error`):
-   * - Host I/O: the OS message, or `write failed: ${path}`.
-   * - `unionFs` with no mount: `no mount for path: ${path}`.
-   * - A read-only mount may use `read-only mount` or
-   *   `read-only mount: ${path}`.
-   *
-   * Missing parents are not an error; create them. There is no
-   * `not found` for `write`.
-   */
-  write(path: string, contents: string): Promise<void>;
-  /**
-   * Remove one file. Directories are not deleted; listing them
-   * is empty and they have no inode of their own on a virtual
-   * tree.
-   *
-   * Errors (throw `Error`):
-   * - Missing file, or a virtual directory: `not found: ${path}`.
-   * - Host I/O: the OS message, or `not found: ${path}`.
-   * - `unionFs` with no mount: `no mount for path: ${path}`.
-   */
-  delete(path: string): Promise<void>;
-  /**
-   * Semantic hits. Trees without an index yield nothing (do
-   * not register the host index). Honor `maxResults` when set.
-   * Ordered by score descending, then path.
-   *
-   * Errors: none for a tree without an index (empty iterator).
-   * An index that fails mid-scan may throw; native
-   * SemanticSearch turns that into `{ status: "error" }` with
-   * the thrown message or `search failed`.
-   */
-  search(query: SearchQuery): AsyncIterable<SearchResult>;
-}
-
-export const FILE_SYSTEM_TOOL_NAMES = [
-  "Read",
-  "LS",
-  "Glob",
-  "Grep",
-  "Write",
-  "StrReplace",
-  "Delete",
-  "SemanticSearch",
-] as const;
-
-export type FileSystemToolName = (typeof FILE_SYSTEM_TOOL_NAMES)[number];
-
-const FILE_SYSTEM_TOOL_NAME_SET = new Set<string>(FILE_SYSTEM_TOOL_NAMES);
-
-const FILE_SYSTEM_TOOL_ALIASES: Readonly<Record<string, FileSystemToolName>> = {
-  read: "Read",
-  Read: "Read",
-  ls: "LS",
-  LS: "LS",
-  glob: "Glob",
-  Glob: "Glob",
-  grep: "Grep",
-  Grep: "Grep",
-  write: "Write",
-  Write: "Write",
-  edit: "StrReplace",
-  StrReplace: "StrReplace",
-  delete: "Delete",
-  Delete: "Delete",
-  semSearch: "SemanticSearch",
-  SemanticSearch: "SemanticSearch",
-};
-
-export function canonicalizeFileSystemToolName(name: string): FileSystemToolName | undefined {
-  return FILE_SYSTEM_TOOL_ALIASES[name];
-}
-
-export function isFileSystemToolName(name: string): name is FileSystemToolName {
-  return FILE_SYSTEM_TOOL_NAME_SET.has(name);
-}
-
-export function isFileSystemToolAlias(name: string): boolean {
-  return canonicalizeFileSystemToolName(name) !== undefined;
-}
-
-/** Direct `callTool` names that mutate the tree and must wait on a busy turn. */
-export function isMutatingFileSystemTool(name: string): boolean {
-  const canonical = canonicalizeFileSystemToolName(name);
-  return canonical === "Write" || canonical === "StrReplace" || canonical === "Delete";
-}
-
-export function isFileSystemMethodPresent(root: FileSystem, method: keyof FileSystem): boolean {
-  return typeof root[method] === "function";
-}
-
-const ADVERTISED_FILE_SYSTEM_TOOL_NAMES: FileSystemToolName[] = [
-  "Read",
-  "LS",
-  "Glob",
-  "Grep",
-  "Write",
-  "StrReplace",
-  "Delete",
-  "SemanticSearch",
-];
-
-export function fileSystemToolNames(_root?: FileSystem): FileSystemToolName[] {
-  return [...ADVERTISED_FILE_SYSTEM_TOOL_NAMES];
-}
-
-function fileSystemMethodForTool(name: FileSystemToolName): keyof FileSystem | undefined {
-  switch (name) {
-    case "Read":
-      return "read";
-    case "LS":
-      return "list";
-    case "Glob":
-      return "glob";
-    case "Grep":
-      return "grep";
-    case "Write":
-    case "StrReplace":
-      return "write";
-    case "Delete":
-      return "delete";
-    case "SemanticSearch":
-      return "search";
-  }
-}
-
-function fileSystemSatisfiesFileTool(root: FileSystem, name: string): boolean {
-  const canonical = canonicalizeFileSystemToolName(name);
-  if (canonical === undefined) {
-    return true;
-  }
-  const method = fileSystemMethodForTool(canonical);
-  return method !== undefined && isFileSystemMethodPresent(root, method);
-}
-
-export class FileSystemConfigError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "FileSystemConfigError";
-  }
-}
-
-function allowlistHas(tools: readonly ToolName[], ...names: string[]): boolean {
-  return tools.some(name => names.includes(name));
-}
-
-export function resolveRootHarnessAllowlist(tools?: readonly ToolName[]): ToolName[] {
-  if (tools === undefined) {
-    // File verbs are synthesized, including SemanticSearch from
-    // `search`. Web tools are safe under the `/tmp` scratch
-    // overlay. Todos are harness conversation state. Do not
-    // unlock shell or task.
-    return ["webSearch", "webFetch", "updateTodos", "readTodos", "mcp"];
-  }
-  if (allowlistHas(tools, "shell", "Shell")) {
-    throw new FileSystemConfigError(
-      '`root` cannot be combined with `tools` containing `"shell"`. ' +
-        "Shell is not a FileSystem method and must not bind the host shell onto a virtual tree.",
-    );
-  }
-  if (allowlistHas(tools, "task", "Task")) {
-    throw new FileSystemConfigError(
-      "`root` cannot list `task`: a child keeps the host toolset and " +
-        "would read the real workspace. Sharing `root` with subagents " +
-        "needs a Cursor SDK inherit, not an overridden Task tool.",
-    );
-  }
-  if (allowlistHas(tools, "readLints", "ReadLints")) {
-    throw new FileSystemConfigError(
-      "`root` cannot list `readLints`: FileSystem has no diagnostics " +
-        "verb, so the host language service would run against the real workspace.",
-    );
-  }
-  const extras = tools.filter(name => !isFileSystemToolAlias(name));
-  return withMcpGrant(extras);
-}
-
-export function resolveFileSystemTools(options: {
-  root: FileSystem;
-  tools?: readonly ToolName[];
-}): ToolName[] {
-  const harness = resolveRootHarnessAllowlist(options.tools);
-  if (options.tools === undefined) {
-    return harness;
-  }
-  const implemented = fileSystemToolNames(options.root);
-  const missing: string[] = [];
-  for (const name of options.tools) {
-    if (!fileSystemSatisfiesFileTool(options.root, name)) {
-      missing.push(name);
-    }
-  }
-  if (missing.length > 0) {
-    throw new FileSystemConfigError(
-      `\`tools\` names FileSystem method(s) that are not implemented: ${missing.join(", ")}. ` +
-        `Implemented file tools: ${implemented.length > 0 ? implemented.join(", ") : "(none)"}.`,
-    );
-  }
-  return harness;
-}
-
-export function withMcpGrant(tools: readonly ToolName[]): ToolName[] {
-  return tools.includes("mcp") ? [...tools] : [...tools, "mcp"];
-}
-
-/**
- * Native Cursor SDK file tools replaced by synthesized FileSystem tools
- * on every local turn. SDK allowlist names (`edit`, not `Write`).
- */
-export const REPLACED_NATIVE_FILE_TOOLS: ToolName[] = [
-  "read",
-  "ls",
-  "grep",
-  "glob",
-  "edit",
-  "delete",
-];
-
-/**
- * Host-default harness options: keep shell / webSearch / sandbox, but
- * hide the native file tools the synthesized FileSystem now owns.
- *
- * Omitted `tools` leaves the SDK default set and only excludes the
- * replaced natives. `[]` stays empty. A non-empty allowlist drops file
- * aliases (those ride synthesized tools) and grants `mcp`.
- */
-export function resolveHostHarnessToolOptions(tools?: readonly ToolName[]): {
-  tools?: ToolName[];
-  disallowedTools?: ToolName[];
-} {
-  if (tools === undefined) {
-    return { disallowedTools: [...REPLACED_NATIVE_FILE_TOOLS] };
-  }
-  if (tools.length === 0) {
-    return { tools: [] };
-  }
-  return {
-    tools: withMcpGrant(tools.filter(name => !isReplacedHostFileAlias(name))),
-  };
-}
-
-/** File aliases host-default synthesizes. Native `semSearch` stays. */
-function isReplacedHostFileAlias(name: string): boolean {
-  const canonical = canonicalizeFileSystemToolName(name);
-  return canonical !== undefined && canonical !== "SemanticSearch";
-}
-
-export type GrepOutputMode = "content" | "files_with_matches" | "count";
-
-/** Decode a {@link FileSystem.read} result as UTF-8 text. */
-export function fileSystemText(content: string | Uint8Array): string {
-  return typeof content === "string" ? content : Buffer.from(content).toString("utf8");
-}
-
-/**
- * Native Read image formats. Magic bytes first, then extension.
- * Returns undefined for text (and for any other binary).
- */
-export function detectImageMimeType(bytes: Uint8Array, filePath?: string): string | undefined {
-  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
-    return "image/jpeg";
-  }
-  if (
-    bytes.length >= 8 &&
-    bytes[0] === 0x89 &&
-    bytes[1] === 0x50 &&
-    bytes[2] === 0x4e &&
-    bytes[3] === 0x47
-  ) {
-    return "image/png";
-  }
-  if (bytes.length >= 6 && bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) {
-    return "image/gif";
-  }
-  if (
-    bytes.length >= 12 &&
-    bytes[0] === 0x52 &&
-    bytes[1] === 0x49 &&
-    bytes[2] === 0x46 &&
-    bytes[3] === 0x46 &&
-    bytes[8] === 0x57 &&
-    bytes[9] === 0x45 &&
-    bytes[10] === 0x42 &&
-    bytes[11] === 0x50
-  ) {
-    return "image/webp";
-  }
-  if (filePath === undefined) {
-    return undefined;
-  }
-  const lower = filePath.toLowerCase();
-  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) {
-    return "image/jpeg";
-  }
-  if (lower.endsWith(".png")) {
-    return "image/png";
-  }
-  if (lower.endsWith(".gif")) {
-    return "image/gif";
-  }
-  if (lower.endsWith(".webp")) {
-    return "image/webp";
-  }
-  return undefined;
-}
-
-export function fileSystemImage(
-  content: string | Uint8Array,
-  path: string,
-): { mimeType: string; bytes: Uint8Array } | undefined {
-  if (!(content instanceof Uint8Array)) {
-    return undefined;
-  }
-  const mimeType = detectImageMimeType(content, path);
-  if (mimeType === undefined) {
-    return undefined;
-  }
-  return { mimeType, bytes: content };
-}
-
-function compileGrepPattern(pattern: string, caseInsensitive?: boolean, path = "/"): RegExp {
-  try {
-    return new RegExp(pattern, caseInsensitive === true ? "i" : undefined);
-  } catch {
-    throw new InvalidGrepPatternError(pattern, path);
-  }
-}
-
-function* grepFileContent(args: {
-  path: string;
-  content: string;
-  regex: RegExp;
-}): Generator<GrepResult> {
-  const lines = args.content.split("\n");
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]!;
-    if (args.regex.test(line)) {
-      yield { path: args.path, lineNumber: i + 1, line };
-    }
-  }
-}
-
-function normalizeMaxResults(maxResults: number | undefined): number | undefined {
-  if (maxResults === undefined || !Number.isFinite(maxResults)) {
-    return undefined;
-  }
-  return Math.max(0, Math.floor(maxResults));
-}
-
-async function* limitResults<T>(
-  source: AsyncIterable<T>,
-  maxResults: number | undefined,
-): AsyncGenerator<T> {
-  const cap = normalizeMaxResults(maxResults);
-  if (cap === 0) {
-    return;
-  }
-  let n = 0;
-  for await (const item of source) {
-    yield item;
-    n++;
-    if (cap !== undefined && n >= cap) {
-      return;
-    }
-  }
-}
-
-function grepPushdownLimit(
-  query: GrepQuery,
-  opts: { outputMode: GrepOutputMode; headLimit?: number; offset: number },
-): number | undefined {
-  // Count and files_with_matches paginate after grouping by file.
-  // A line-level cap would hide later files once one file fills the window.
-  if (opts.outputMode === "count" || opts.outputMode === "files_with_matches") {
-    return query.maxResults;
-  }
-  const headLimit = opts.headLimit !== undefined && opts.headLimit > 0 ? opts.headLimit : undefined;
-  if (headLimit === undefined) {
-    return query.maxResults;
-  }
-  const toolCap = opts.offset + headLimit;
-  return query.maxResults === undefined ? toolCap : Math.min(query.maxResults, toolCap);
-}
-
-function compareGrepResult(left: GrepResult, right: GrepResult): number {
-  return left.path < right.path
-    ? -1
-    : left.path > right.path
-      ? 1
-      : left.lineNumber - right.lineNumber;
-}
-
-function compareSearchResult(left: SearchResult, right: SearchResult): number {
-  if (right.score !== left.score) {
-    return right.score - left.score;
-  }
-  return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
-}
-
-export async function collectGrepMatches(
-  root: FileSystem,
-  query: GrepQuery,
-  opts: { outputMode: GrepOutputMode; headLimit?: number; offset?: number },
-): Promise<GrepResult[]> {
-  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;
-  const skippedFiles = new Set<string>();
-  const acceptedFiles = new Set<string>();
-  let skippedItems = 0;
-  let takenItems = 0;
-  const pushdown = grepPushdownLimit(query, {
-    outputMode: opts.outputMode,
-    offset,
-    ...(opts.headLimit === undefined ? {} : { headLimit: opts.headLimit }),
-  });
-  const grepQuery = pushdown === undefined ? query : { ...query, maxResults: pushdown };
-  for await (const match of root.grep(grepQuery)) {
-    if (opts.outputMode === "content") {
-      if (skippedItems < offset) {
-        skippedItems++;
-        continue;
-      }
-      matches.push(match);
-      takenItems++;
-      if (headLimit !== undefined && takenItems >= headLimit) {
-        break;
-      }
-      continue;
-    }
-    if (skippedFiles.has(match.path)) {
-      continue;
-    }
-    if (!acceptedFiles.has(match.path)) {
-      if (skippedItems < offset) {
-        skippedFiles.add(match.path);
-        skippedItems++;
-        continue;
-      }
-      if (headLimit !== undefined && takenItems >= headLimit) {
-        break;
-      }
-      acceptedFiles.add(match.path);
-      takenItems++;
-    }
-    matches.push(match);
-  }
-  return matches;
-}
-
-export type GrepContentHit = GrepResult & {
-  beforeContext?: string[];
-  afterContext?: string[];
-};
-
-export function shapeGrepUnion(
-  matches: GrepContentHit[],
-  outputMode: GrepOutputMode,
-): GrepUnionResult {
-  if (outputMode === "files_with_matches") {
-    const files = [...new Set(matches.map(match => match.path))];
-    return { type: "files", output: { files, count: files.length } };
-  }
-  if (outputMode === "count") {
-    const counts = new Map<string, number>();
-    for (const match of matches) {
-      counts.set(match.path, (counts.get(match.path) ?? 0) + 1);
-    }
-    return {
-      type: "count",
-      output: {
-        counts: [...counts].map(([file, count]) => ({ file, count })),
-        total: matches.length,
-      },
-    };
-  }
-  return {
-    type: "content",
-    output: {
-      matches: matches.map(match => ({
-        file: match.path,
-        lineNumber: match.lineNumber,
-        line: match.line,
-        ...(match.beforeContext === undefined ? {} : { beforeContext: match.beforeContext }),
-        ...(match.afterContext === undefined ? {} : { afterContext: match.afterContext }),
-      })),
-      totalMatches: matches.length,
-    },
-  };
-}
-
-export function normalizeFsPath(input: string): string {
-  const slashes = input.replace(/\\/g, "/");
-  if (slashes === "") {
-    return "/";
-  }
-  const withSlash = slashes.startsWith("/") ? slashes : `/${slashes}`;
-  const resolved = path.posix.normalize(withSlash);
-  if (resolved.length > 1 && resolved.endsWith("/")) {
-    return resolved.slice(0, -1);
-  }
-  return resolved === "." || resolved === "" ? "/" : resolved;
-}
-
-/** Path-segment prefix: `/agent` matches `/agent/skills`, not `/agent-tools`. */
-export function pathHasSegmentPrefix(args: { path: string; prefix: string }): boolean {
-  const p = normalizeFsPath(args.path);
-  const pre = normalizeFsPath(args.prefix);
-  if (pre === "/") {
-    return true;
-  }
-  return p === pre || p.startsWith(`${pre}/`);
-}
-
-function matchGlob(relativePath: string, globPattern: string): boolean {
-  return minimatch(relativePath, globPattern, { dot: true, nocase: false });
-}
-
-function pathMatchesGlob(
-  filePath: string,
-  dir: string,
-  globPattern: string,
-  options: { matchBasename?: boolean } = {},
-): boolean {
-  const posixFile = filePath.replace(/\\/g, "/");
-  const posixDir = dir.replace(/\\/g, "/");
-  const relative =
-    posixDir === "/" || posixFile.startsWith(`${posixDir}/`)
-      ? posixDir === "/"
-        ? posixFile.replace(/^\//, "")
-        : posixFile.slice(posixDir.length + 1)
-      : posixFile.replace(/^\//, "");
-  if (matchGlob(relative, globPattern) || matchGlob(posixFile.replace(/^\//, ""), globPattern)) {
-    return true;
-  }
-  // Native grep `--glob '*.ts'` matches the basename at any depth.
-  // Glob `*.ts` stays relative to `targetDirectory` and does not.
-  if (options.matchBasename === true && !globPattern.includes("/")) {
-    const slash = relative.lastIndexOf("/");
-    const base = slash === -1 ? relative : relative.slice(slash + 1);
-    return matchGlob(base, globPattern);
-  }
-  return false;
-}
-
-/**
- * Resolve a per-send `workspaceFiles` key onto the virtual `/` namespace.
- * Refuses paths that escape the root, and the reserved `memory` name.
- * Host-default workspaces symlink `memory/` to durable agent state, so a
- * seed under that name would write through the link.
- */
-export function virtualWorkspaceWritePath(relativePath: string): string {
-  if (relativePath.includes("\0")) {
-    throw new FileSystemConfigError(`Refusing to write outside the virtual root: ${relativePath}`);
-  }
-  const posix = relativePath.replaceAll("\\", "/");
-  const base = "/virtual-root";
-  const target = path.posix.normalize(path.posix.join(base, posix));
-  if (target !== base && !target.startsWith(`${base}/`)) {
-    throw new FileSystemConfigError(`Refusing to write outside the virtual root: ${relativePath}`);
-  }
-  const sliced = target.slice(base.length);
-  const dest = sliced === "" ? "/" : sliced;
-  if (
-    pathHasSegmentPrefix({
-      path: dest,
-      prefix: `/${MEMORY_DIR_NAME}`,
-    })
-  ) {
-    throw new FileSystemConfigError(
-      `"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to write ${relativePath}`,
-    );
-  }
-  return dest;
-}
-
-export async function writeWorkspaceFilesToRoot(
-  root: FileSystem,
-  files: Record<string, string | { encoding: "base64"; data: string; mimeType?: string }>,
-): Promise<void> {
-  for (const [relativePath, contents] of Object.entries(files)) {
-    // Refuse escapes, then write the sanitized relative dest so
-    // `localFileSystem` joins against cwd and `tempFs` still normalizes
-    // `a.txt` → `/a.txt`. Never forward an absolute host path.
-    const dest = virtualWorkspaceWritePath(relativePath);
-    const relativeDest = dest.replace(/^\//, "");
-    if (relativeDest === "") {
-      throw new FileSystemConfigError(`Refusing to write the virtual root: ${relativePath}`);
-    }
-    const fileText =
-      typeof contents === "string"
-        ? contents
-        : Buffer.from(contents.data, "base64").toString("utf8");
-    try {
-      await root.write(relativeDest, fileText);
-    } catch (error) {
-      throw new FileSystemConfigError(
-        `workspaceFiles failed to write ${relativePath}: ${
-          error instanceof Error ? error.message : "write failed"
-        }`,
-      );
-    }
-  }
-}
-
-function replaceLiteral(args: {
-  existing: string;
-  oldText: string;
-  newText: string;
-  replaceAll: boolean;
-}): string {
-  if (args.replaceAll) {
-    return args.existing.split(args.oldText).join(args.newText);
-  }
-  const index = args.existing.indexOf(args.oldText);
-  if (index === -1) {
-    return args.existing;
-  }
-  return (
-    args.existing.slice(0, index) + args.newText + args.existing.slice(index + args.oldText.length)
-  );
-}
-
-function countNonOverlapping(haystack: string, needle: string): number {
-  let count = 0;
-  let from = 0;
-  while (from <= haystack.length - needle.length) {
-    const index = haystack.indexOf(needle, from);
-    if (index === -1) {
-      break;
-    }
-    count++;
-    from = index + needle.length;
-  }
-  return count;
-}
-
-/**
- * Exact, non-overlapping str-replace. Uniqueness is the FileSystem
- * contract: more than one match fails unless `replaceAll`.
- */
-function applyExactEdit(args: {
-  existing: string;
-  oldText: string;
-  newText: string;
-  replaceAll: boolean;
-  path: string;
-}): { contents: string; occurrencesModified: number } {
-  if (args.oldText === "") {
-    throw new EditError(args.path, "oldText is empty");
-  }
-  if (args.oldText === args.newText) {
-    throw new EditError(args.path, "oldText and newText are exactly the same");
-  }
-  const occurrences = countNonOverlapping(args.existing, args.oldText);
-  if (occurrences === 0) {
-    throw new EditError(args.path, "The string to replace was not found in the file");
-  }
-  if (occurrences > 1 && !args.replaceAll) {
-    throw new EditError(
-      args.path,
-      "The string to replace was found multiple times in the file. Use replace_all to replace all occurrences, or include more context to only edit one occurrence.",
-    );
-  }
-  return {
-    contents: replaceLiteral({
-      existing: args.existing,
-      oldText: args.oldText,
-      newText: args.newText,
-      replaceAll: args.replaceAll,
-    }),
-    occurrencesModified: occurrences,
-  };
-}
-
-/**
- * Exact str-replace as `read` + apply + `write`. Uniqueness is
- * this helper's contract; FileSystem implementations do not
- * implement edit. Native StrReplace calls this.
- */
-export async function strReplaceOnFileSystem(
-  root: Pick<FileSystem, "read" | "write">,
-  query: EditQuery,
-): Promise<EditResult> {
-  const existing = await root.read(query.path);
-  if (typeof existing !== "string") {
-    throw new EditError(query.path, `${query.path} is not text`);
-  }
-  const applied = applyExactEdit({
-    existing,
-    oldText: query.oldText,
-    newText: query.newText,
-    replaceAll: query.replaceAll === true,
-    path: query.path,
-  });
-  await root.write(query.path, applied.contents);
-  return { occurrencesModified: applied.occurrencesModified };
-}
-
-/** Native Read offset/limit: 1-indexed, negative offset counts from the end. */
-export function sliceReadContent(content: string, offset?: number, limit?: number): string {
-  if (offset === undefined && limit === undefined) {
-    return content;
-  }
-  const lines = content === "" ? [] : content.split("\n");
-  const total = lines.length;
-  const effectiveOffset = offset ?? 1;
-  const effectiveLimit = limit ?? (effectiveOffset < 0 ? Math.abs(effectiveOffset) : total);
-  const startIndex =
-    effectiveOffset < 0 ? Math.max(0, total + effectiveOffset) : Math.max(0, effectiveOffset - 1);
-  const endIndex = Math.min(total, startIndex + effectiveLimit);
-  return lines.slice(startIndex, endIndex).join("\n");
-}
-
-async function* emptySearch(_query: SearchQuery): AsyncGenerator<SearchResult> {}
-
-async function* emptyStream(): AsyncGenerator<never> {}
-
-/**
- * A FileSystem with no files. Use as an overlay leaf or a missing
- * catalog so a miss stays {@link FileNotFoundError} instead of
- * {@link NoMountError}. Writes and deletes throw
- * {@link ReadOnlyMountError} — an empty tree is never a sink.
- */
-export function emptyFs(): FileSystem {
-  return {
-    list: () => emptyStream(),
-    glob: () => emptyStream(),
-    async *grep(query) {
-      compileGrepPattern(
-        query.pattern,
-        query.caseInsensitive,
-        query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path),
-      );
-      yield* emptyStream();
-    },
-    search: emptySearch,
-    async stat(path) {
-      return statFromFilePaths([], path);
-    },
-    async read(path) {
-      throw new FileNotFoundError(normalizeFsPath(path));
-    },
-    async write(path) {
-      throw new ReadOnlyMountError(normalizeFsPath(path));
-    },
-    async delete(path) {
-      throw new ReadOnlyMountError(normalizeFsPath(path));
-    },
-  };
-}
-
-/**
- * In-memory FileSystem for tests and fixtures. Keys are absolute
- * posix paths (`/a.txt`) and are normalized on ingest. Honors the
- * {@link FileSystem} order and path contracts.
- * `search` is empty. Creates `/agent-tools` on first scratch
- * write the same way any other path is created.
- */
-export function tempFs(files: Record<string, string | Uint8Array> = {}): FileSystem {
-  const store = new Map<string, string | Uint8Array>();
-  for (const [path, content] of Object.entries(files)) {
-    store.set(normalizeFsPath(path), content);
-  }
-
-  const listed = {
-    list(prefix?: string, options?: ListOptions) {
-      return listFilesFromPaths(
-        [...store.entries()].map(([filePath, content]) => ({
-          path: filePath,
-          size: typeof content === "string" ? content.length : content.byteLength,
-        })),
-        prefix,
-        options,
-      );
-    },
-    async stat(path: string) {
-      return statFromFilePaths(store.keys(), path);
-    },
-  };
-
-  return {
-    list(prefix, options) {
-      return listed.list(prefix, options);
-    },
-    async stat(path) {
-      return listed.stat(path);
-    },
-    async read(inputPath) {
-      const path = normalizeFsPath(inputPath);
-      const content = store.get(path);
-      if (content === undefined) {
-        throw new FileNotFoundError(path);
-      }
-      return content;
-    },
-    async *grep(query) {
-      yield* limitResults(uncapped(), query.maxResults);
-      async function* uncapped() {
-        const regex = compileGrepPattern(
-          query.pattern,
-          query.caseInsensitive,
-          query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path),
-        );
-        const scope =
-          query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path);
-        const exact = store.get(scope);
-        if (scope !== "/" && exact !== undefined) {
-          if (
-            query.glob !== undefined &&
-            !pathMatchesGlob(scope, scope, query.glob, {
-              matchBasename: true,
-            })
-          ) {
-            return;
-          }
-          if (isExcludedPath(scope, query.excludes)) {
-            return;
-          }
-          yield* grepFileContent({
-            path: scope,
-            content: fileSystemText(exact),
-            regex,
-          });
-          return;
-        }
-        for await (const entry of listed.list(
-          scope === "/" ? undefined : scope,
-          query.excludes === undefined ? undefined : { excludes: query.excludes },
-        )) {
-          if (
-            query.glob !== undefined &&
-            !pathMatchesGlob(entry.path, scope, query.glob, {
-              matchBasename: true,
-            })
-          ) {
-            continue;
-          }
-          const content = store.get(entry.path);
-          if (content === undefined) {
-            continue;
-          }
-          yield* grepFileContent({
-            path: entry.path,
-            content: fileSystemText(content),
-            regex,
-          });
-        }
-      }
-    },
-    async *glob(pattern, dir, options) {
-      const scope = dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
-      yield* globFromList(listed.list(scope === "/" ? undefined : scope), {
-        pattern,
-        dir: scope,
-        ...(options?.limit === undefined ? {} : { limit: options.limit }),
-      });
-    },
-    async write(inputPath, contents) {
-      store.set(normalizeFsPath(inputPath), contents);
-    },
-    async delete(inputPath) {
-      const path = normalizeFsPath(inputPath);
-      if (!store.has(path)) {
-        throw new FileNotFoundError(path);
-      }
-      store.delete(path);
-    },
-    search: emptySearch,
-  };
-}
-
-function fsErrorMessage(error: unknown, fallback: string): string {
-  return error instanceof Error ? error.message : fallback;
-}
-
-function throwLocalReadError(error: unknown, filePath: string): never {
-  throw new FileNotFoundError(filePath, fsErrorMessage(error, `not found: ${filePath}`));
-}
-
-function skipWalkDir(name: string): boolean {
-  return name === ".git" || name === "node_modules";
-}
-
-async function walkLocalFiles(rootDir: string): Promise<string[]> {
-  const found: string[] = [];
-  const stack = [rootDir];
-  while (stack.length > 0) {
-    const current = stack.pop();
-    if (current === undefined) {
-      break;
-    }
-    let entries: Array<{
-      name: string;
-      isDirectory(): boolean;
-      isFile(): boolean;
-    }>;
-    try {
-      entries = await readdir(current, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      const full = path.join(current, entry.name);
-      // Same as the pre-root host walk and native LS/Glob/Grep: Dirent
-      // isDirectory/isFile do not follow links, so workspace `memory/`
-      // and other symlinks are not enumerated. Exact-path read/stat still
-      // follow.
-      if (entry.isDirectory()) {
-        if (!skipWalkDir(entry.name)) {
-          stack.push(full);
-        }
-      } else if (entry.isFile()) {
-        found.push(full);
-      }
-    }
-  }
-  found.sort((left, right) => left.localeCompare(right));
-  return found;
-}
-
-async function* listLocalFiles(rootDir: string): AsyncGenerator<DirEntry> {
-  for (const filePath of await walkLocalFiles(rootDir)) {
-    yield { path: filePath };
-  }
-}
-
-/**
- * Host-disk FileSystem. Relative paths resolve against `cwd`; absolute
- * paths are used as-is — the same contract as Cursor SDK native file
- * tools. `search` yields empty results (no host index).
- *
- * Internal. Not part of the public Agent SDK surface.
- */
-export function localFileSystem(options: { cwd: string }): FileSystem {
-  const cwd = path.resolve(options.cwd);
-
-  const resolvePath = (input: string): string =>
-    path.isAbsolute(input) ? path.resolve(input) : path.resolve(cwd, input);
-
-  return {
-    async *list(prefix, options) {
-      yield* limitResults(uncapped(), options?.limit);
-      async function* uncapped() {
-        const dirPath =
-          prefix === undefined || prefix === "" || prefix === "." ? cwd : resolvePath(prefix);
-        for await (const entry of listLocalFiles(dirPath)) {
-          if (!isExcludedPath(entry.path, options?.excludes)) {
-            yield entry;
-          }
-        }
-      }
-    },
-    async stat(probePath) {
-      const filePath = resolvePath(probePath);
-      try {
-        const info = await stat(filePath);
-        return { kind: info.isDirectory() ? "directory" : "file" } as const;
-      } catch {
-        return { kind: "missing" } as const;
-      }
-    },
-    async read(inputPath) {
-      const filePath = resolvePath(inputPath);
-      try {
-        const bytes = await readFile(filePath);
-        if (detectImageMimeType(bytes, filePath) !== undefined) {
-          return new Uint8Array(bytes);
-        }
-        return bytes.toString("utf8");
-      } catch (error) {
-        throwLocalReadError(error, filePath);
-      }
-    },
-    async *grep(query) {
-      yield* limitResults(uncapped(), query.maxResults);
-      async function* uncapped() {
-        const searchRoot = resolvePath(query.path ?? cwd);
-        const regex = compileGrepPattern(query.pattern, query.caseInsensitive, searchRoot);
-        let filesToSearch: string[];
-        try {
-          const info = await stat(searchRoot);
-          filesToSearch = info.isFile() ? [searchRoot] : await walkLocalFiles(searchRoot);
-        } catch (error) {
-          throwLocalReadError(error, searchRoot);
-        }
-        for (const filePath of filesToSearch) {
-          if (
-            query.glob !== undefined &&
-            !pathMatchesGlob(filePath, searchRoot, query.glob, {
-              matchBasename: true,
-            })
-          ) {
-            continue;
-          }
-          if (isExcludedPath(filePath, query.excludes)) {
-            continue;
-          }
-          let content: string;
-          try {
-            content = await readFile(filePath, "utf8");
-          } catch {
-            continue;
-          }
-          yield* grepFileContent({ path: filePath, content, regex });
-        }
-      }
-    },
-    async *glob(pattern, dir, options) {
-      const dirPath = dir === undefined || dir === "" || dir === "." ? cwd : resolvePath(dir);
-      yield* globFromList(listLocalFiles(dirPath), {
-        pattern,
-        dir: dirPath,
-        ...(options?.limit === undefined ? {} : { limit: options.limit }),
-      });
-    },
-    async write(inputPath, contents) {
-      const filePath = resolvePath(inputPath);
-      try {
-        await mkdir(path.dirname(filePath), { recursive: true });
-        await writeFile(filePath, contents, "utf8");
-      } catch (error) {
-        throw new WriteFailedError(filePath, fsErrorMessage(error, `write failed: ${filePath}`));
-      }
-    },
-    async delete(inputPath) {
-      const filePath = resolvePath(inputPath);
-      try {
-        await rm(filePath);
-      } catch (error) {
-        throwLocalReadError(error, filePath);
-      }
-    },
-    search: emptySearch,
-  };
-}
-
-interface MountEntry {
-  prefix: string;
-  fs: FileSystem;
-}
-
-function longestMount(path: string, mounts: MountEntry[]): MountEntry | undefined {
-  let best: MountEntry | undefined;
-  for (const mount of mounts) {
-    if (!pathHasSegmentPrefix({ path, prefix: mount.prefix })) {
-      continue;
-    }
-    if (best === undefined || mount.prefix.length > best.prefix.length) {
-      best = mount;
-    }
-  }
-  return best;
-}
-
-/** Namespace path → child path. `/host/a.md` on `/host` is `/a.md`. */
-function toChildPath(path: string, prefix: string): string {
-  if (prefix === "/") {
-    return path;
-  }
-  if (path === prefix) {
-    return "/";
-  }
-  if (path.startsWith(`${prefix}/`)) {
-    return path.slice(prefix.length);
-  }
-  return path;
-}
-
-/** Child path → namespace path. `/a.md` on `/host` is `/host/a.md`. */
-function toParentPath(path: string, prefix: string): string {
-  if (prefix === "/") {
-    return path;
-  }
-  if (path === "/" || path === "") {
-    return prefix;
-  }
-  return path.startsWith("/") ? `${prefix}${path}` : `${prefix}/${path}`;
-}
-
-async function* mapMountEntries(
-  source: AsyncIterable<DirEntry>,
-  prefix: string,
-): AsyncIterable<DirEntry> {
-  try {
-    for await (const entry of source) {
-      yield { ...entry, path: toParentPath(entry.path, prefix) };
-    }
-  } catch (error) {
-    throw remapPathError(error, prefix);
-  }
-}
-
-async function* mapMountGrep(
-  source: AsyncIterable<GrepResult>,
-  prefix: string,
-): AsyncIterable<GrepResult> {
-  try {
-    for await (const hit of source) {
-      yield { ...hit, path: toParentPath(hit.path, prefix) };
-    }
-  } catch (error) {
-    throw remapPathError(error, prefix);
-  }
-}
-
-async function* mapMountSearch(
-  source: AsyncIterable<SearchResult>,
-  prefix: string,
-): AsyncIterable<SearchResult> {
-  try {
-    for await (const hit of source) {
-      yield { ...hit, path: toParentPath(hit.path, prefix) };
-    }
-  } catch (error) {
-    throw remapPathError(error, prefix);
-  }
-}
-
-function childSearchQuery(query: SearchQuery, prefix: string): SearchQuery | undefined {
-  if (query.targetDirectories === undefined || query.targetDirectories.length === 0) {
-    return query;
-  }
-  const dirs: string[] = [];
-  for (const dir of query.targetDirectories) {
-    const normalized = normalizeFsPath(dir);
-    // `/` is every mount, the same way grep at `/` fans out.
-    if (normalized === "/") {
-      return { ...query, targetDirectories: undefined };
-    }
-    if (!pathHasSegmentPrefix({ path: normalized, prefix })) {
-      continue;
-    }
-    const child = toChildPath(normalized, prefix);
-    if (child === "/") {
-      return { ...query, targetDirectories: undefined };
-    }
-    dirs.push(child);
-  }
-  if (dirs.length === 0) {
-    return undefined;
-  }
-  return { ...query, targetDirectories: dirs };
-}
-
-/**
- * Longest-prefix compose, path-segment match. Every verb is
- * defined. Does not synthesize `shell`. `/agent` is not a
- * prefix of `/agent-tools`.
- *
- * The record keys are mount points. Each child is a FileSystem
- * rooted at `/`. `unionFs` strips the prefix on the way in and
- * re-prefixes yields (and error paths) on the way out:
- * `unionFs({ "/host": hostFs(...) })` — the child never sees
- * `/host`.
- *
- * A path with no mount:
- * - `read` / `write` / `delete`: throw
- *   `no mount for path: ${path}`
- * - `list` / `glob` / `grep`: empty iterator
- * - `stat`: `{ kind: "missing" }` (`/` and exact mount prefixes
- *   are `{ kind: "directory" }`)
- *
- * Root `list` / `glob` / `grep` / `search` k-way merge already
- * sorted sources. List and glob use `unique` so an earlier
- * mount shadows a later one; grep and search keep every hit.
- */
-export function unionFs(mounts: Record<string, FileSystem>): FileSystem {
-  const entries: MountEntry[] = Object.entries(mounts).map(([prefix, fs]) => ({
-    prefix: normalizeFsPath(prefix),
-    fs,
-  }));
-  entries.sort((a, b) => b.prefix.length - a.prefix.length);
-
-  const noMount = (path: string): never => {
-    throw new NoMountError(path);
-  };
-
-  const forward = async <T>(
-    path: string,
-    run: (fs: FileSystem, childPath: string) => Promise<T>,
-  ): Promise<T> => {
-    const mount = longestMount(path, entries);
-    if (mount === undefined) {
-      return noMount(path);
-    }
-    const childPath = toChildPath(path, mount.prefix);
-    try {
-      return await run(mount.fs, childPath);
-    } catch (error) {
-      throw remapPathError(error, mount.prefix);
-    }
-  };
-
-  const isRootPath = (value: string | undefined): boolean =>
-    value === undefined || value === "" || value === "/";
-
-  return {
-    async *list(prefix, options) {
-      yield* limitResults(uncapped(), options?.limit);
-      async function* uncapped() {
-        if (isRootPath(prefix)) {
-          yield* mergeSortedByPath(
-            entries.map(mount => mapMountEntries(mount.fs.list(undefined, options), mount.prefix)),
-            { unique: true },
-          );
-          return;
-        }
-        const path = normalizeFsPath(prefix ?? "/");
-        const mount = longestMount(path, entries);
-        if (mount === undefined) {
-          return;
-        }
-        const childPath = toChildPath(path, mount.prefix);
-        yield* mapMountEntries(
-          mount.fs.list(childPath === "/" ? undefined : childPath, options),
-          mount.prefix,
-        );
-      }
-    },
-    async stat(path) {
-      const normalized = normalizeFsPath(path);
-      if (normalized === "/") {
-        return { kind: "directory" } as const;
-      }
-      if (entries.some(entry => entry.prefix === normalized)) {
-        return { kind: "directory" } as const;
-      }
-      const mount = longestMount(normalized, entries);
-      if (mount === undefined) {
-        return { kind: "missing" } as const;
-      }
-      return mount.fs.stat(toChildPath(normalized, mount.prefix));
-    },
-    async read(path) {
-      const normalized = normalizeFsPath(path);
-      return forward(normalized, (fs, childPath) => fs.read(childPath));
-    },
-    async write(path, contents) {
-      const normalized = normalizeFsPath(path);
-      return forward(normalized, (fs, childPath) => fs.write(childPath, contents));
-    },
-    async delete(path) {
-      const normalized = normalizeFsPath(path);
-      return forward(normalized, (fs, childPath) => fs.delete(childPath));
-    },
-    async *grep(query) {
-      yield* limitResults(uncapped(), query.maxResults);
-      async function* uncapped() {
-        const scope =
-          query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path);
-        if (scope === "/") {
-          yield* mergeSorted(
-            entries.map(mount =>
-              mapMountGrep(mount.fs.grep({ ...query, path: undefined }), mount.prefix),
-            ),
-            { compare: compareGrepResult },
-          );
-          return;
-        }
-        const mount = longestMount(scope, entries);
-        if (mount === undefined) {
-          return;
-        }
-        const childPath = toChildPath(scope, mount.prefix);
-        yield* mapMountGrep(
-          mount.fs.grep({
-            ...query,
-            path: childPath === "/" ? undefined : childPath,
-          }),
-          mount.prefix,
-        );
-      }
-    },
-    async *search(query) {
-      yield* limitResults(uncapped(), query.maxResults);
-      async function* uncapped() {
-        const sources: AsyncIterable<SearchResult>[] = [];
-        for (const mount of entries) {
-          const childQuery = childSearchQuery(query, mount.prefix);
-          if (childQuery === undefined) {
-            continue;
-          }
-          sources.push(mapMountSearch(mount.fs.search(childQuery), mount.prefix));
-        }
-        yield* mergeSorted(sources, { compare: compareSearchResult });
-      }
-    },
-    async *glob(pattern, dir, options) {
-      yield* limitResults(uncapped(), options?.limit);
-      async function* uncapped() {
-        const scope = dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
-        if (scope === "/") {
-          yield* mergeSortedByPath(
-            entries.map(mount =>
-              mapMountEntries(mount.fs.glob(pattern, undefined, options), mount.prefix),
-            ),
-            { unique: true },
-          );
-          return;
-        }
-        const mount = longestMount(scope, entries);
-        if (mount === undefined) {
-          return;
-        }
-        const childPath = toChildPath(scope, mount.prefix);
-        yield* mapMountEntries(
-          mount.fs.glob(pattern, childPath === "/" ? undefined : childPath, options),
-          mount.prefix,
-        );
-      }
-    },
-  };
-}
-
-async function collectLayerPaths(layer: FileSystem): Promise<string[]> {
-  const paths: string[] = [];
-  try {
-    for await (const entry of layer.list()) {
-      paths.push(entry.path);
-    }
-  } catch {
-    // A layer that cannot list also cannot own paths.
-  }
-  return paths;
-}
-
-/**
- * Same-root overlay: earlier layers win. Read-only.
- *
- * A downed layer costs its own files, not the overlay. Mutations
- * throw `read-only mount` / `read-only mount: ${path}`. Empty
- * `layers` throws `overlayFs needs at least one layer.`
- */
-export function overlayFs(layers: readonly FileSystem[]): FileSystem {
-  if (layers.length === 0) {
-    throw new Error("overlayFs needs at least one layer.");
-  }
-
-  const walkLayers = async <T>(
-    collect: (layer: FileSystem) => AsyncIterable<T> | Promise<AsyncIterable<T>>,
-  ): Promise<{ streams: T[][]; failure: unknown; served: boolean }> => {
-    const streams: T[][] = [];
-    let failure: unknown;
-    let served = false;
-    for (const layer of layers) {
-      const collected: T[] = [];
-      try {
-        for await (const entry of await collect(layer)) {
-          collected.push(entry);
-        }
-      } catch (error) {
-        failure ??= error;
-        continue;
-      }
-      served = true;
-      streams.push(collected);
-    }
-    return { streams, failure, served };
-  };
-
-  const collectOverlayHits = async <T extends { path: string }>(
-    queryFn: (layer: FileSystem) => AsyncIterable<T>,
-    rethrow?: (error: unknown) => boolean,
-  ): Promise<T[][]> => {
-    const streams: T[][] = [];
-    const shadowed = new Set<string>();
-    let failure: unknown;
-    let served = false;
-    for (const layer of layers) {
-      const collected: T[] = [];
-      try {
-        for await (const hit of queryFn(layer)) {
-          if (!shadowed.has(hit.path)) {
-            collected.push(hit);
-          }
-        }
-        served = true;
-      } catch (error) {
-        if (rethrow?.(error) === true) {
-          throw error;
-        }
-        failure ??= error;
-        continue;
-      }
-      streams.push(collected);
-      for (const path of await collectLayerPaths(layer)) {
-        shadowed.add(path);
-      }
-    }
-    if (!served && failure !== undefined) {
-      throw failure;
-    }
-    return streams;
-  };
-
-  return {
-    async *list(prefix, options) {
-      const { streams, failure, served } = await walkLayers(layer => layer.list(prefix, options));
-      if (!served && failure !== undefined) {
-        throw failure;
-      }
-      yield* limitResults(mergeSortedByPath(streams, { unique: true }), options?.limit);
-    },
-    async stat(path) {
-      let failure: unknown;
-      let sawMissing = false;
-      for (const layer of layers) {
-        try {
-          const info = await layer.stat(path);
-          if (info.kind !== "missing") {
-            return info;
-          }
-          sawMissing = true;
-        } catch (error) {
-          failure ??= error;
-        }
-      }
-      if (!sawMissing && failure !== undefined) {
-        throw failure;
-      }
-      return { kind: "missing" } as const;
-    },
-    async *glob(pattern, dir, options) {
-      const { streams, failure, served } = await walkLayers(layer =>
-        layer.glob(pattern, dir, options),
-      );
-      if (!served && failure !== undefined) {
-        throw failure;
-      }
-      yield* limitResults(mergeSortedByPath(streams, { unique: true }), options?.limit);
-    },
-    async read(path) {
-      let failure: unknown;
-      for (const layer of layers) {
-        try {
-          return await layer.read(path);
-        } catch (error) {
-          if (isFileNotFoundError(error)) {
-            continue;
-          }
-          failure ??= error;
-        }
-      }
-      if (failure !== undefined) {
-        throw failure;
-      }
-      throw new FileNotFoundError(path);
-    },
-    async *grep(query) {
-      const { maxResults, ...uncappedQuery } = query;
-      yield* limitResults(
-        mergeSorted(
-          await collectOverlayHits(
-            layer => layer.grep(uncappedQuery),
-            error => isInvalidGrepPatternError(error),
-          ),
-          { compare: compareGrepResult },
-        ),
-        maxResults,
-      );
-    },
-    async write(path) {
-      throw new ReadOnlyMountError(path);
-    },
-    async delete(path) {
-      throw new ReadOnlyMountError(path);
-    },
-    async *search(query) {
-      const { maxResults, ...uncappedQuery } = query;
-      yield* limitResults(
-        mergeSorted(await collectOverlayHits(layer => layer.search(uncappedQuery)), {
-          compare: compareSearchResult,
-        }),
-        maxResults,
-      );
-    },
-  };
-}
-
-function hostKey(path: string): string {
-  const normalized = normalizeFsPath(path);
-  return normalized === "/" ? "" : normalized.slice(1);
-}
-
-function isHostConflict(error: unknown): boolean {
-  return (
-    error instanceof FileConflictError ||
-    (error instanceof Error &&
-      (error.name === "FileConflictError" || error.message.includes("lost a race")))
-  );
-}
-
-/**
- * `HostFilesApi` as a FileSystem rooted at `/`.
- *
- * Mount it with `unionFs({ "/host": hostFs(files, scope) })`. The
- * child never sees `/host` — `unionFs` owns the prefix. `scope` is
- * the HostFiles partition, not a path prefix. `search` is empty
- * (HostFiles is not an index).
- */
-export function hostFs(files: HostFilesApi, scope: HostFilesScope): FileSystem {
-  const callOptions = { scope };
-  const readEtags = new Map<string, string>();
-
-  const listed = {
-    async *list(prefix?: string, options?: ListOptions) {
-      const entries = await files.list(undefined, callOptions);
-      yield* listFilesFromPaths(
-        entries.map(entry => ({
-          path: normalizeFsPath(entry.path),
-          size: entry.size,
-        })),
-        prefix,
-        options,
-      );
-    },
-    async stat(path: string) {
-      const entries = await files.list(undefined, callOptions);
-      return statFromFilePaths(
-        entries.map(entry => normalizeFsPath(entry.path)),
-        path,
-      );
-    },
-  };
-
-  const readText = async (inputPath: string): Promise<string> => {
-    const path = normalizeFsPath(inputPath);
-    const key = hostKey(path);
-    if (key === "") {
-      throw new FileNotFoundError(path);
-    }
-    const [content, stat] = await Promise.all([
-      files.read(key, callOptions),
-      files.stat(key, callOptions),
-    ]);
-    if (content === undefined) {
-      throw new FileNotFoundError(path);
-    }
-    if (stat?.etag !== undefined) {
-      readEtags.set(key, stat.etag);
-    }
-    return content;
-  };
-
-  const writeHost = async (inputPath: string, contents: string): Promise<void> => {
-    const path = normalizeFsPath(inputPath);
-    const key = hostKey(path);
-    if (key === "") {
-      throw new FileNotFoundError(path);
-    }
-    try {
-      if (files.capabilities.conflictDetection) {
-        const etag = readEtags.get(key);
-        await files.write(key, contents, {
-          ...callOptions,
-          // No cached etag: unconditional create/overwrite. After a
-          // successful read or write, CAS on that etag.
-          ...(etag === undefined ? {} : { ifMatch: etag }),
-        });
-      } else {
-        await files.write(key, contents, callOptions);
-      }
-    } catch (error) {
-      if (isHostConflict(error)) {
-        throw new PathError(path, `${path} changed since you read it — read it again and rewrite.`);
-      }
-      throw error;
-    }
-    const stat = await files.stat(key, callOptions);
-    if (stat?.etag !== undefined) {
-      readEtags.set(key, stat.etag);
-    } else {
-      readEtags.delete(key);
-    }
-  };
-
-  return {
-    list(prefix, options) {
-      return listed.list(prefix, options);
-    },
-    async stat(path) {
-      return listed.stat(path);
-    },
-    async read(path) {
-      return readText(path);
-    },
-    async *grep(query) {
-      yield* limitResults(uncapped(), query.maxResults);
-      async function* uncapped() {
-        const scopePath =
-          query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path);
-        const regex = compileGrepPattern(query.pattern, query.caseInsensitive, scopePath);
-        const info = await listed.stat(scopePath);
-        if (scopePath !== "/" && info.kind === "file") {
-          if (
-            query.glob !== undefined &&
-            !pathMatchesGlob(scopePath, scopePath, query.glob, {
-              matchBasename: true,
-            })
-          ) {
-            return;
-          }
-          if (isExcludedPath(scopePath, query.excludes)) {
-            return;
-          }
-          yield* grepFileContent({
-            path: scopePath,
-            content: await readText(scopePath),
-            regex,
-          });
-          return;
-        }
-        for await (const entry of listed.list(
-          scopePath === "/" ? undefined : scopePath,
-          query.excludes === undefined ? undefined : { excludes: query.excludes },
-        )) {
-          if (
-            query.glob !== undefined &&
-            !pathMatchesGlob(entry.path, scopePath, query.glob, {
-              matchBasename: true,
-            })
-          ) {
-            continue;
-          }
-          yield* grepFileContent({
-            path: entry.path,
-            content: await readText(entry.path),
-            regex,
-          });
-        }
-      }
-    },
-    async *glob(pattern, dir, options) {
-      const dirPath = dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
-      yield* globFromList(listed.list(dirPath === "/" ? undefined : dirPath), {
-        pattern,
-        dir: dirPath,
-        ...(options?.limit === undefined ? {} : { limit: options.limit }),
-      });
-    },
-    async write(inputPath, contents) {
-      await writeHost(inputPath, contents);
-    },
-    async delete(inputPath) {
-      const path = normalizeFsPath(inputPath);
-      const key = hostKey(path);
-      if (key === "" || !(await files.exists(key, callOptions))) {
-        throw new FileNotFoundError(path);
-      }
-      await files.remove(key, callOptions);
-      readEtags.delete(key);
-    },
-    search: emptySearch,
-  };
-}
-
-async function* globFromList(
-  source: AsyncIterable<DirEntry>,
-  options: { pattern: string; dir: string; limit?: number },
-): AsyncGenerator<DirEntry> {
-  yield* limitResults(uncapped(), options.limit);
-  async function* uncapped() {
-    for await (const entry of source) {
-      if (pathMatchesGlob(entry.path, options.dir, options.pattern)) {
-        yield entry;
-      }
-    }
-  }
-}