@cursor/bdk 0.2.1

package/src/filesystem.ts

@@ -0,0 +1,2005 @@
+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;
+      }
+    }
+  }
+}