@cursor/bdk 0.2.1

package/dist/filesystem.js

@@ -0,0 +1,1698 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+import { Buffer } from "node:buffer";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+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";
+/**
+ * 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 = 1000;
+export const FILE_SYSTEM_TOOL_NAMES = [
+    "Read",
+    "LS",
+    "Glob",
+    "Grep",
+    "Write",
+    "StrReplace",
+    "Delete",
+    "SemanticSearch",
+];
+const FILE_SYSTEM_TOOL_NAME_SET = new Set(FILE_SYSTEM_TOOL_NAMES);
+const FILE_SYSTEM_TOOL_ALIASES = {
+    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) {
+    return FILE_SYSTEM_TOOL_ALIASES[name];
+}
+export function isFileSystemToolName(name) {
+    return FILE_SYSTEM_TOOL_NAME_SET.has(name);
+}
+export function isFileSystemToolAlias(name) {
+    return canonicalizeFileSystemToolName(name) !== undefined;
+}
+/** Direct `callTool` names that mutate the tree and must wait on a busy turn. */
+export function isMutatingFileSystemTool(name) {
+    const canonical = canonicalizeFileSystemToolName(name);
+    return canonical === "Write" || canonical === "StrReplace" || canonical === "Delete";
+}
+export function isFileSystemMethodPresent(root, method) {
+    return typeof root[method] === "function";
+}
+const ADVERTISED_FILE_SYSTEM_TOOL_NAMES = [
+    "Read",
+    "LS",
+    "Glob",
+    "Grep",
+    "Write",
+    "StrReplace",
+    "Delete",
+    "SemanticSearch",
+];
+export function fileSystemToolNames(_root) {
+    return [...ADVERTISED_FILE_SYSTEM_TOOL_NAMES];
+}
+function fileSystemMethodForTool(name) {
+    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, name) {
+    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) {
+        super(message);
+        this.name = "FileSystemConfigError";
+    }
+}
+function allowlistHas(tools, ...names) {
+    return tools.some(name => names.includes(name));
+}
+export function resolveRootHarnessAllowlist(tools) {
+    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) {
+    const harness = resolveRootHarnessAllowlist(options.tools);
+    if (options.tools === undefined) {
+        return harness;
+    }
+    const implemented = fileSystemToolNames(options.root);
+    const missing = [];
+    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) {
+    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 = [
+    "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) {
+    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) {
+    const canonical = canonicalizeFileSystemToolName(name);
+    return canonical !== undefined && canonical !== "SemanticSearch";
+}
+/** Decode a {@link FileSystem.read} result as UTF-8 text. */
+export function fileSystemText(content) {
+    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, filePath) {
+    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, path) {
+    if (!(content instanceof Uint8Array)) {
+        return undefined;
+    }
+    const mimeType = detectImageMimeType(content, path);
+    if (mimeType === undefined) {
+        return undefined;
+    }
+    return { mimeType, bytes: content };
+}
+function compileGrepPattern(pattern, caseInsensitive, path = "/") {
+    try {
+        return new RegExp(pattern, caseInsensitive === true ? "i" : undefined);
+    }
+    catch (_a) {
+        throw new InvalidGrepPatternError(pattern, path);
+    }
+}
+function* grepFileContent(args) {
+    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) {
+    if (maxResults === undefined || !Number.isFinite(maxResults)) {
+        return undefined;
+    }
+    return Math.max(0, Math.floor(maxResults));
+}
+function limitResults(source, maxResults) {
+    return __asyncGenerator(this, arguments, function* limitResults_1() {
+        var _a, e_1, _b, _c;
+        const cap = normalizeMaxResults(maxResults);
+        if (cap === 0) {
+            return yield __await(void 0);
+        }
+        let n = 0;
+        try {
+            for (var _d = true, source_1 = __asyncValues(source), source_1_1; source_1_1 = yield __await(source_1.next()), _a = source_1_1.done, !_a; _d = true) {
+                _c = source_1_1.value;
+                _d = false;
+                const item = _c;
+                yield yield __await(item);
+                n++;
+                if (cap !== undefined && n >= cap) {
+                    return yield __await(void 0);
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = source_1.return)) yield __await(_b.call(source_1));
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    });
+}
+function grepPushdownLimit(query, opts) {
+    // 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, right) {
+    return left.path < right.path
+        ? -1
+        : left.path > right.path
+            ? 1
+            : left.lineNumber - right.lineNumber;
+}
+function compareSearchResult(left, right) {
+    if (right.score !== left.score) {
+        return right.score - left.score;
+    }
+    return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
+}
+export function collectGrepMatches(root, query, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, e_2, _b, _c;
+        const matches = [];
+        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();
+        const acceptedFiles = new Set();
+        let skippedItems = 0;
+        let takenItems = 0;
+        const pushdown = grepPushdownLimit(query, Object.assign({ outputMode: opts.outputMode, offset }, (opts.headLimit === undefined ? {} : { headLimit: opts.headLimit })));
+        const grepQuery = pushdown === undefined ? query : Object.assign(Object.assign({}, query), { maxResults: pushdown });
+        try {
+            for (var _d = true, _e = __asyncValues(root.grep(grepQuery)), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                _c = _f.value;
+                _d = false;
+                const match = _c;
+                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);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        return matches;
+    });
+}
+export function shapeGrepUnion(matches, outputMode) {
+    var _a;
+    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();
+        for (const match of matches) {
+            counts.set(match.path, ((_a = counts.get(match.path)) !== null && _a !== void 0 ? _a : 0) + 1);
+        }
+        return {
+            type: "count",
+            output: {
+                counts: [...counts].map(([file, count]) => ({ file, count })),
+                total: matches.length,
+            },
+        };
+    }
+    return {
+        type: "content",
+        output: {
+            matches: matches.map(match => (Object.assign(Object.assign({ 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) {
+    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) {
+    const p = normalizeFsPath(args.path);
+    const pre = normalizeFsPath(args.prefix);
+    if (pre === "/") {
+        return true;
+    }
+    return p === pre || p.startsWith(`${pre}/`);
+}
+function matchGlob(relativePath, globPattern) {
+    return minimatch(relativePath, globPattern, { dot: true, nocase: false });
+}
+function pathMatchesGlob(filePath, dir, globPattern, options = {}) {
+    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) {
+    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 function writeWorkspaceFilesToRoot(root, files) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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 {
+                yield root.write(relativeDest, fileText);
+            }
+            catch (error) {
+                throw new FileSystemConfigError(`workspaceFiles failed to write ${relativePath}: ${error instanceof Error ? error.message : "write failed"}`);
+            }
+        }
+    });
+}
+function replaceLiteral(args) {
+    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, needle) {
+    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) {
+    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 function strReplaceOnFileSystem(root, query) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const existing = yield 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,
+        });
+        yield 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, offset, limit) {
+    if (offset === undefined && limit === undefined) {
+        return content;
+    }
+    const lines = content === "" ? [] : content.split("\n");
+    const total = lines.length;
+    const effectiveOffset = offset !== null && offset !== void 0 ? offset : 1;
+    const effectiveLimit = limit !== null && limit !== void 0 ? 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");
+}
+function emptySearch(_query) { return __asyncGenerator(this, arguments, function* emptySearch_1() { }); }
+function emptyStream() { return __asyncGenerator(this, arguments, function* emptyStream_1() { }); }
+/**
+ * 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() {
+    return {
+        list: () => emptyStream(),
+        glob: () => emptyStream(),
+        grep(query) {
+            return __asyncGenerator(this, arguments, function* grep_1() {
+                compileGrepPattern(query.pattern, query.caseInsensitive, query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path));
+                yield __await(yield* __asyncDelegator(__asyncValues(emptyStream())));
+            });
+        },
+        search: emptySearch,
+        stat(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return statFromFilePaths([], path);
+            });
+        },
+        read(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                throw new FileNotFoundError(normalizeFsPath(path));
+            });
+        },
+        write(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                throw new ReadOnlyMountError(normalizeFsPath(path));
+            });
+        },
+        delete(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                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 = {}) {
+    const store = new Map();
+    for (const [path, content] of Object.entries(files)) {
+        store.set(normalizeFsPath(path), content);
+    }
+    const listed = {
+        list(prefix, options) {
+            return listFilesFromPaths([...store.entries()].map(([filePath, content]) => ({
+                path: filePath,
+                size: typeof content === "string" ? content.length : content.byteLength,
+            })), prefix, options);
+        },
+        stat(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return statFromFilePaths(store.keys(), path);
+            });
+        },
+    };
+    return {
+        list(prefix, options) {
+            return listed.list(prefix, options);
+        },
+        stat(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return listed.stat(path);
+            });
+        },
+        read(inputPath) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const path = normalizeFsPath(inputPath);
+                const content = store.get(path);
+                if (content === undefined) {
+                    throw new FileNotFoundError(path);
+                }
+                return content;
+            });
+        },
+        grep(query) {
+            return __asyncGenerator(this, arguments, function* grep_2() {
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(uncapped(), query.maxResults))));
+                function uncapped() {
+                    return __asyncGenerator(this, arguments, function* uncapped_1() {
+                        var _a, e_3, _b, _c;
+                        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 yield __await(void 0);
+                            }
+                            if (isExcludedPath(scope, query.excludes)) {
+                                return yield __await(void 0);
+                            }
+                            yield __await(yield* __asyncDelegator(__asyncValues(grepFileContent({
+                                path: scope,
+                                content: fileSystemText(exact),
+                                regex,
+                            }))));
+                            return yield __await(void 0);
+                        }
+                        try {
+                            for (var _d = true, _e = __asyncValues(listed.list(scope === "/" ? undefined : scope, query.excludes === undefined ? undefined : { excludes: query.excludes })), _f; _f = yield __await(_e.next()), _a = _f.done, !_a; _d = true) {
+                                _c = _f.value;
+                                _d = false;
+                                const entry = _c;
+                                if (query.glob !== undefined &&
+                                    !pathMatchesGlob(entry.path, scope, query.glob, {
+                                        matchBasename: true,
+                                    })) {
+                                    continue;
+                                }
+                                const content = store.get(entry.path);
+                                if (content === undefined) {
+                                    continue;
+                                }
+                                yield __await(yield* __asyncDelegator(__asyncValues(grepFileContent({
+                                    path: entry.path,
+                                    content: fileSystemText(content),
+                                    regex,
+                                }))));
+                            }
+                        }
+                        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                        finally {
+                            try {
+                                if (!_d && !_a && (_b = _e.return)) yield __await(_b.call(_e));
+                            }
+                            finally { if (e_3) throw e_3.error; }
+                        }
+                    });
+                }
+            });
+        },
+        glob(pattern, dir, options) {
+            return __asyncGenerator(this, arguments, function* glob_1() {
+                const scope = dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
+                yield __await(yield* __asyncDelegator(__asyncValues(globFromList(listed.list(scope === "/" ? undefined : scope), Object.assign({ pattern, dir: scope }, ((options === null || options === void 0 ? void 0 : options.limit) === undefined ? {} : { limit: options.limit }))))));
+            });
+        },
+        write(inputPath, contents) {
+            return __awaiter(this, void 0, void 0, function* () {
+                store.set(normalizeFsPath(inputPath), contents);
+            });
+        },
+        delete(inputPath) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const path = normalizeFsPath(inputPath);
+                if (!store.has(path)) {
+                    throw new FileNotFoundError(path);
+                }
+                store.delete(path);
+            });
+        },
+        search: emptySearch,
+    };
+}
+function fsErrorMessage(error, fallback) {
+    return error instanceof Error ? error.message : fallback;
+}
+function throwLocalReadError(error, filePath) {
+    throw new FileNotFoundError(filePath, fsErrorMessage(error, `not found: ${filePath}`));
+}
+function skipWalkDir(name) {
+    return name === ".git" || name === "node_modules";
+}
+function walkLocalFiles(rootDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const found = [];
+        const stack = [rootDir];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (current === undefined) {
+                break;
+            }
+            let entries;
+            try {
+                entries = yield readdir(current, { withFileTypes: true });
+            }
+            catch (_a) {
+                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;
+    });
+}
+function listLocalFiles(rootDir) {
+    return __asyncGenerator(this, arguments, function* listLocalFiles_1() {
+        for (const filePath of yield __await(walkLocalFiles(rootDir))) {
+            yield yield __await({ 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) {
+    const cwd = path.resolve(options.cwd);
+    const resolvePath = (input) => path.isAbsolute(input) ? path.resolve(input) : path.resolve(cwd, input);
+    return {
+        list(prefix, options) {
+            return __asyncGenerator(this, arguments, function* list_1() {
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(uncapped(), options === null || options === void 0 ? void 0 : options.limit))));
+                function uncapped() {
+                    return __asyncGenerator(this, arguments, function* uncapped_2() {
+                        var _a, e_4, _b, _c;
+                        const dirPath = prefix === undefined || prefix === "" || prefix === "." ? cwd : resolvePath(prefix);
+                        try {
+                            for (var _d = true, _e = __asyncValues(listLocalFiles(dirPath)), _f; _f = yield __await(_e.next()), _a = _f.done, !_a; _d = true) {
+                                _c = _f.value;
+                                _d = false;
+                                const entry = _c;
+                                if (!isExcludedPath(entry.path, options === null || options === void 0 ? void 0 : options.excludes)) {
+                                    yield yield __await(entry);
+                                }
+                            }
+                        }
+                        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+                        finally {
+                            try {
+                                if (!_d && !_a && (_b = _e.return)) yield __await(_b.call(_e));
+                            }
+                            finally { if (e_4) throw e_4.error; }
+                        }
+                    });
+                }
+            });
+        },
+        stat(probePath) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const filePath = resolvePath(probePath);
+                try {
+                    const info = yield stat(filePath);
+                    return { kind: info.isDirectory() ? "directory" : "file" };
+                }
+                catch (_a) {
+                    return { kind: "missing" };
+                }
+            });
+        },
+        read(inputPath) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const filePath = resolvePath(inputPath);
+                try {
+                    const bytes = yield readFile(filePath);
+                    if (detectImageMimeType(bytes, filePath) !== undefined) {
+                        return new Uint8Array(bytes);
+                    }
+                    return bytes.toString("utf8");
+                }
+                catch (error) {
+                    throwLocalReadError(error, filePath);
+                }
+            });
+        },
+        grep(query) {
+            return __asyncGenerator(this, arguments, function* grep_3() {
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(uncapped(), query.maxResults))));
+                function uncapped() {
+                    return __asyncGenerator(this, arguments, function* uncapped_3() {
+                        var _a;
+                        const searchRoot = resolvePath((_a = query.path) !== null && _a !== void 0 ? _a : cwd);
+                        const regex = compileGrepPattern(query.pattern, query.caseInsensitive, searchRoot);
+                        let filesToSearch;
+                        try {
+                            const info = yield __await(stat(searchRoot));
+                            filesToSearch = info.isFile() ? [searchRoot] : yield __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;
+                            try {
+                                content = yield __await(readFile(filePath, "utf8"));
+                            }
+                            catch (_b) {
+                                continue;
+                            }
+                            yield __await(yield* __asyncDelegator(__asyncValues(grepFileContent({ path: filePath, content, regex }))));
+                        }
+                    });
+                }
+            });
+        },
+        glob(pattern, dir, options) {
+            return __asyncGenerator(this, arguments, function* glob_2() {
+                const dirPath = dir === undefined || dir === "" || dir === "." ? cwd : resolvePath(dir);
+                yield __await(yield* __asyncDelegator(__asyncValues(globFromList(listLocalFiles(dirPath), Object.assign({ pattern, dir: dirPath }, ((options === null || options === void 0 ? void 0 : options.limit) === undefined ? {} : { limit: options.limit }))))));
+            });
+        },
+        write(inputPath, contents) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const filePath = resolvePath(inputPath);
+                try {
+                    yield mkdir(path.dirname(filePath), { recursive: true });
+                    yield writeFile(filePath, contents, "utf8");
+                }
+                catch (error) {
+                    throw new WriteFailedError(filePath, fsErrorMessage(error, `write failed: ${filePath}`));
+                }
+            });
+        },
+        delete(inputPath) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const filePath = resolvePath(inputPath);
+                try {
+                    yield rm(filePath);
+                }
+                catch (error) {
+                    throwLocalReadError(error, filePath);
+                }
+            });
+        },
+        search: emptySearch,
+    };
+}
+function longestMount(path, mounts) {
+    let best;
+    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, prefix) {
+    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, prefix) {
+    if (prefix === "/") {
+        return path;
+    }
+    if (path === "/" || path === "") {
+        return prefix;
+    }
+    return path.startsWith("/") ? `${prefix}${path}` : `${prefix}/${path}`;
+}
+function mapMountEntries(source, prefix) {
+    return __asyncGenerator(this, arguments, function* mapMountEntries_1() {
+        var _a, e_5, _b, _c;
+        try {
+            try {
+                for (var _d = true, source_2 = __asyncValues(source), source_2_1; source_2_1 = yield __await(source_2.next()), _a = source_2_1.done, !_a; _d = true) {
+                    _c = source_2_1.value;
+                    _d = false;
+                    const entry = _c;
+                    yield yield __await(Object.assign(Object.assign({}, entry), { path: toParentPath(entry.path, prefix) }));
+                }
+            }
+            catch (e_5_1) { e_5 = { error: e_5_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = source_2.return)) yield __await(_b.call(source_2));
+                }
+                finally { if (e_5) throw e_5.error; }
+            }
+        }
+        catch (error) {
+            throw remapPathError(error, prefix);
+        }
+    });
+}
+function mapMountGrep(source, prefix) {
+    return __asyncGenerator(this, arguments, function* mapMountGrep_1() {
+        var _a, e_6, _b, _c;
+        try {
+            try {
+                for (var _d = true, source_3 = __asyncValues(source), source_3_1; source_3_1 = yield __await(source_3.next()), _a = source_3_1.done, !_a; _d = true) {
+                    _c = source_3_1.value;
+                    _d = false;
+                    const hit = _c;
+                    yield yield __await(Object.assign(Object.assign({}, hit), { path: toParentPath(hit.path, prefix) }));
+                }
+            }
+            catch (e_6_1) { e_6 = { error: e_6_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = source_3.return)) yield __await(_b.call(source_3));
+                }
+                finally { if (e_6) throw e_6.error; }
+            }
+        }
+        catch (error) {
+            throw remapPathError(error, prefix);
+        }
+    });
+}
+function mapMountSearch(source, prefix) {
+    return __asyncGenerator(this, arguments, function* mapMountSearch_1() {
+        var _a, e_7, _b, _c;
+        try {
+            try {
+                for (var _d = true, source_4 = __asyncValues(source), source_4_1; source_4_1 = yield __await(source_4.next()), _a = source_4_1.done, !_a; _d = true) {
+                    _c = source_4_1.value;
+                    _d = false;
+                    const hit = _c;
+                    yield yield __await(Object.assign(Object.assign({}, hit), { path: toParentPath(hit.path, prefix) }));
+                }
+            }
+            catch (e_7_1) { e_7 = { error: e_7_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = source_4.return)) yield __await(_b.call(source_4));
+                }
+                finally { if (e_7) throw e_7.error; }
+            }
+        }
+        catch (error) {
+            throw remapPathError(error, prefix);
+        }
+    });
+}
+function childSearchQuery(query, prefix) {
+    if (query.targetDirectories === undefined || query.targetDirectories.length === 0) {
+        return query;
+    }
+    const dirs = [];
+    for (const dir of query.targetDirectories) {
+        const normalized = normalizeFsPath(dir);
+        // `/` is every mount, the same way grep at `/` fans out.
+        if (normalized === "/") {
+            return Object.assign(Object.assign({}, query), { targetDirectories: undefined });
+        }
+        if (!pathHasSegmentPrefix({ path: normalized, prefix })) {
+            continue;
+        }
+        const child = toChildPath(normalized, prefix);
+        if (child === "/") {
+            return Object.assign(Object.assign({}, query), { targetDirectories: undefined });
+        }
+        dirs.push(child);
+    }
+    if (dirs.length === 0) {
+        return undefined;
+    }
+    return Object.assign(Object.assign({}, 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) {
+    const entries = Object.entries(mounts).map(([prefix, fs]) => ({
+        prefix: normalizeFsPath(prefix),
+        fs,
+    }));
+    entries.sort((a, b) => b.prefix.length - a.prefix.length);
+    const noMount = (path) => {
+        throw new NoMountError(path);
+    };
+    const forward = (path, run) => __awaiter(this, void 0, void 0, function* () {
+        const mount = longestMount(path, entries);
+        if (mount === undefined) {
+            return noMount(path);
+        }
+        const childPath = toChildPath(path, mount.prefix);
+        try {
+            return yield run(mount.fs, childPath);
+        }
+        catch (error) {
+            throw remapPathError(error, mount.prefix);
+        }
+    });
+    const isRootPath = (value) => value === undefined || value === "" || value === "/";
+    return {
+        list(prefix, options) {
+            return __asyncGenerator(this, arguments, function* list_2() {
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(uncapped(), options === null || options === void 0 ? void 0 : options.limit))));
+                function uncapped() {
+                    return __asyncGenerator(this, arguments, function* uncapped_4() {
+                        if (isRootPath(prefix)) {
+                            yield __await(yield* __asyncDelegator(__asyncValues(mergeSortedByPath(entries.map(mount => mapMountEntries(mount.fs.list(undefined, options), mount.prefix)), { unique: true }))));
+                            return yield __await(void 0);
+                        }
+                        const path = normalizeFsPath(prefix !== null && prefix !== void 0 ? prefix : "/");
+                        const mount = longestMount(path, entries);
+                        if (mount === undefined) {
+                            return yield __await(void 0);
+                        }
+                        const childPath = toChildPath(path, mount.prefix);
+                        yield __await(yield* __asyncDelegator(__asyncValues(mapMountEntries(mount.fs.list(childPath === "/" ? undefined : childPath, options), mount.prefix))));
+                    });
+                }
+            });
+        },
+        stat(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const normalized = normalizeFsPath(path);
+                if (normalized === "/") {
+                    return { kind: "directory" };
+                }
+                if (entries.some(entry => entry.prefix === normalized)) {
+                    return { kind: "directory" };
+                }
+                const mount = longestMount(normalized, entries);
+                if (mount === undefined) {
+                    return { kind: "missing" };
+                }
+                return mount.fs.stat(toChildPath(normalized, mount.prefix));
+            });
+        },
+        read(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const normalized = normalizeFsPath(path);
+                return forward(normalized, (fs, childPath) => fs.read(childPath));
+            });
+        },
+        write(path, contents) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const normalized = normalizeFsPath(path);
+                return forward(normalized, (fs, childPath) => fs.write(childPath, contents));
+            });
+        },
+        delete(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const normalized = normalizeFsPath(path);
+                return forward(normalized, (fs, childPath) => fs.delete(childPath));
+            });
+        },
+        grep(query) {
+            return __asyncGenerator(this, arguments, function* grep_4() {
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(uncapped(), query.maxResults))));
+                function uncapped() {
+                    return __asyncGenerator(this, arguments, function* uncapped_5() {
+                        const scope = query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path);
+                        if (scope === "/") {
+                            yield __await(yield* __asyncDelegator(__asyncValues(mergeSorted(entries.map(mount => mapMountGrep(mount.fs.grep(Object.assign(Object.assign({}, query), { path: undefined })), mount.prefix)), { compare: compareGrepResult }))));
+                            return yield __await(void 0);
+                        }
+                        const mount = longestMount(scope, entries);
+                        if (mount === undefined) {
+                            return yield __await(void 0);
+                        }
+                        const childPath = toChildPath(scope, mount.prefix);
+                        yield __await(yield* __asyncDelegator(__asyncValues(mapMountGrep(mount.fs.grep(Object.assign(Object.assign({}, query), { path: childPath === "/" ? undefined : childPath })), mount.prefix))));
+                    });
+                }
+            });
+        },
+        search(query) {
+            return __asyncGenerator(this, arguments, function* search_1() {
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(uncapped(), query.maxResults))));
+                function uncapped() {
+                    return __asyncGenerator(this, arguments, function* uncapped_6() {
+                        const sources = [];
+                        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 __await(yield* __asyncDelegator(__asyncValues(mergeSorted(sources, { compare: compareSearchResult }))));
+                    });
+                }
+            });
+        },
+        glob(pattern, dir, options) {
+            return __asyncGenerator(this, arguments, function* glob_3() {
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(uncapped(), options === null || options === void 0 ? void 0 : options.limit))));
+                function uncapped() {
+                    return __asyncGenerator(this, arguments, function* uncapped_7() {
+                        const scope = dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
+                        if (scope === "/") {
+                            yield __await(yield* __asyncDelegator(__asyncValues(mergeSortedByPath(entries.map(mount => mapMountEntries(mount.fs.glob(pattern, undefined, options), mount.prefix)), { unique: true }))));
+                            return yield __await(void 0);
+                        }
+                        const mount = longestMount(scope, entries);
+                        if (mount === undefined) {
+                            return yield __await(void 0);
+                        }
+                        const childPath = toChildPath(scope, mount.prefix);
+                        yield __await(yield* __asyncDelegator(__asyncValues(mapMountEntries(mount.fs.glob(pattern, childPath === "/" ? undefined : childPath, options), mount.prefix))));
+                    });
+                }
+            });
+        },
+    };
+}
+function collectLayerPaths(layer) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, e_8, _b, _c;
+        const paths = [];
+        try {
+            try {
+                for (var _d = true, _e = __asyncValues(layer.list()), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const entry = _c;
+                    paths.push(entry.path);
+                }
+            }
+            catch (e_8_1) { e_8 = { error: e_8_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                }
+                finally { if (e_8) throw e_8.error; }
+            }
+        }
+        catch (_g) {
+            // 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) {
+    if (layers.length === 0) {
+        throw new Error("overlayFs needs at least one layer.");
+    }
+    const walkLayers = (collect) => __awaiter(this, void 0, void 0, function* () {
+        var _a, e_9, _b, _c;
+        const streams = [];
+        let failure;
+        let served = false;
+        for (const layer of layers) {
+            const collected = [];
+            try {
+                try {
+                    for (var _d = true, _e = (e_9 = void 0, __asyncValues(yield collect(layer))), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                        _c = _f.value;
+                        _d = false;
+                        const entry = _c;
+                        collected.push(entry);
+                    }
+                }
+                catch (e_9_1) { e_9 = { error: e_9_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                    }
+                    finally { if (e_9) throw e_9.error; }
+                }
+            }
+            catch (error) {
+                failure !== null && failure !== void 0 ? failure : (failure = error);
+                continue;
+            }
+            served = true;
+            streams.push(collected);
+        }
+        return { streams, failure, served };
+    });
+    const collectOverlayHits = (queryFn, rethrow) => __awaiter(this, void 0, void 0, function* () {
+        var _a, e_10, _b, _c;
+        const streams = [];
+        const shadowed = new Set();
+        let failure;
+        let served = false;
+        for (const layer of layers) {
+            const collected = [];
+            try {
+                try {
+                    for (var _d = true, _e = (e_10 = void 0, __asyncValues(queryFn(layer))), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                        _c = _f.value;
+                        _d = false;
+                        const hit = _c;
+                        if (!shadowed.has(hit.path)) {
+                            collected.push(hit);
+                        }
+                    }
+                }
+                catch (e_10_1) { e_10 = { error: e_10_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                    }
+                    finally { if (e_10) throw e_10.error; }
+                }
+                served = true;
+            }
+            catch (error) {
+                if ((rethrow === null || rethrow === void 0 ? void 0 : rethrow(error)) === true) {
+                    throw error;
+                }
+                failure !== null && failure !== void 0 ? failure : (failure = error);
+                continue;
+            }
+            streams.push(collected);
+            for (const path of yield collectLayerPaths(layer)) {
+                shadowed.add(path);
+            }
+        }
+        if (!served && failure !== undefined) {
+            throw failure;
+        }
+        return streams;
+    });
+    return {
+        list(prefix, options) {
+            return __asyncGenerator(this, arguments, function* list_3() {
+                const { streams, failure, served } = yield __await(walkLayers(layer => layer.list(prefix, options)));
+                if (!served && failure !== undefined) {
+                    throw failure;
+                }
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(mergeSortedByPath(streams, { unique: true }), options === null || options === void 0 ? void 0 : options.limit))));
+            });
+        },
+        stat(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                let failure;
+                let sawMissing = false;
+                for (const layer of layers) {
+                    try {
+                        const info = yield layer.stat(path);
+                        if (info.kind !== "missing") {
+                            return info;
+                        }
+                        sawMissing = true;
+                    }
+                    catch (error) {
+                        failure !== null && failure !== void 0 ? failure : (failure = error);
+                    }
+                }
+                if (!sawMissing && failure !== undefined) {
+                    throw failure;
+                }
+                return { kind: "missing" };
+            });
+        },
+        glob(pattern, dir, options) {
+            return __asyncGenerator(this, arguments, function* glob_4() {
+                const { streams, failure, served } = yield __await(walkLayers(layer => layer.glob(pattern, dir, options)));
+                if (!served && failure !== undefined) {
+                    throw failure;
+                }
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(mergeSortedByPath(streams, { unique: true }), options === null || options === void 0 ? void 0 : options.limit))));
+            });
+        },
+        read(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                let failure;
+                for (const layer of layers) {
+                    try {
+                        return yield layer.read(path);
+                    }
+                    catch (error) {
+                        if (isFileNotFoundError(error)) {
+                            continue;
+                        }
+                        failure !== null && failure !== void 0 ? failure : (failure = error);
+                    }
+                }
+                if (failure !== undefined) {
+                    throw failure;
+                }
+                throw new FileNotFoundError(path);
+            });
+        },
+        grep(query) {
+            return __asyncGenerator(this, arguments, function* grep_5() {
+                const { maxResults } = query, uncappedQuery = __rest(query, ["maxResults"]);
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(mergeSorted(yield __await(collectOverlayHits(layer => layer.grep(uncappedQuery), error => isInvalidGrepPatternError(error))), { compare: compareGrepResult }), maxResults))));
+            });
+        },
+        write(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                throw new ReadOnlyMountError(path);
+            });
+        },
+        delete(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                throw new ReadOnlyMountError(path);
+            });
+        },
+        search(query) {
+            return __asyncGenerator(this, arguments, function* search_2() {
+                const { maxResults } = query, uncappedQuery = __rest(query, ["maxResults"]);
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(mergeSorted(yield __await(collectOverlayHits(layer => layer.search(uncappedQuery))), {
+                    compare: compareSearchResult,
+                }), maxResults))));
+            });
+        },
+    };
+}
+function hostKey(path) {
+    const normalized = normalizeFsPath(path);
+    return normalized === "/" ? "" : normalized.slice(1);
+}
+function isHostConflict(error) {
+    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, scope) {
+    const callOptions = { scope };
+    const readEtags = new Map();
+    const listed = {
+        list(prefix, options) {
+            return __asyncGenerator(this, arguments, function* list_4() {
+                const entries = yield __await(files.list(undefined, callOptions));
+                yield __await(yield* __asyncDelegator(__asyncValues(listFilesFromPaths(entries.map(entry => ({
+                    path: normalizeFsPath(entry.path),
+                    size: entry.size,
+                })), prefix, options))));
+            });
+        },
+        stat(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const entries = yield files.list(undefined, callOptions);
+                return statFromFilePaths(entries.map(entry => normalizeFsPath(entry.path)), path);
+            });
+        },
+    };
+    const readText = (inputPath) => __awaiter(this, void 0, void 0, function* () {
+        const path = normalizeFsPath(inputPath);
+        const key = hostKey(path);
+        if (key === "") {
+            throw new FileNotFoundError(path);
+        }
+        const [content, stat] = yield Promise.all([
+            files.read(key, callOptions),
+            files.stat(key, callOptions),
+        ]);
+        if (content === undefined) {
+            throw new FileNotFoundError(path);
+        }
+        if ((stat === null || stat === void 0 ? void 0 : stat.etag) !== undefined) {
+            readEtags.set(key, stat.etag);
+        }
+        return content;
+    });
+    const writeHost = (inputPath, contents) => __awaiter(this, void 0, void 0, function* () {
+        const path = normalizeFsPath(inputPath);
+        const key = hostKey(path);
+        if (key === "") {
+            throw new FileNotFoundError(path);
+        }
+        try {
+            if (files.capabilities.conflictDetection) {
+                const etag = readEtags.get(key);
+                yield files.write(key, contents, Object.assign(Object.assign({}, callOptions), (etag === undefined ? {} : { ifMatch: etag })));
+            }
+            else {
+                yield 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 = yield files.stat(key, callOptions);
+        if ((stat === null || stat === void 0 ? void 0 : stat.etag) !== undefined) {
+            readEtags.set(key, stat.etag);
+        }
+        else {
+            readEtags.delete(key);
+        }
+    });
+    return {
+        list(prefix, options) {
+            return listed.list(prefix, options);
+        },
+        stat(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return listed.stat(path);
+            });
+        },
+        read(path) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return readText(path);
+            });
+        },
+        grep(query) {
+            return __asyncGenerator(this, arguments, function* grep_6() {
+                yield __await(yield* __asyncDelegator(__asyncValues(limitResults(uncapped(), query.maxResults))));
+                function uncapped() {
+                    return __asyncGenerator(this, arguments, function* uncapped_8() {
+                        var _a, e_11, _b, _c;
+                        const scopePath = query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path);
+                        const regex = compileGrepPattern(query.pattern, query.caseInsensitive, scopePath);
+                        const info = yield __await(listed.stat(scopePath));
+                        if (scopePath !== "/" && info.kind === "file") {
+                            if (query.glob !== undefined &&
+                                !pathMatchesGlob(scopePath, scopePath, query.glob, {
+                                    matchBasename: true,
+                                })) {
+                                return yield __await(void 0);
+                            }
+                            if (isExcludedPath(scopePath, query.excludes)) {
+                                return yield __await(void 0);
+                            }
+                            yield __await(yield* __asyncDelegator(__asyncValues(grepFileContent({
+                                path: scopePath,
+                                content: yield __await(readText(scopePath)),
+                                regex,
+                            }))));
+                            return yield __await(void 0);
+                        }
+                        try {
+                            for (var _d = true, _e = __asyncValues(listed.list(scopePath === "/" ? undefined : scopePath, query.excludes === undefined ? undefined : { excludes: query.excludes })), _f; _f = yield __await(_e.next()), _a = _f.done, !_a; _d = true) {
+                                _c = _f.value;
+                                _d = false;
+                                const entry = _c;
+                                if (query.glob !== undefined &&
+                                    !pathMatchesGlob(entry.path, scopePath, query.glob, {
+                                        matchBasename: true,
+                                    })) {
+                                    continue;
+                                }
+                                yield __await(yield* __asyncDelegator(__asyncValues(grepFileContent({
+                                    path: entry.path,
+                                    content: yield __await(readText(entry.path)),
+                                    regex,
+                                }))));
+                            }
+                        }
+                        catch (e_11_1) { e_11 = { error: e_11_1 }; }
+                        finally {
+                            try {
+                                if (!_d && !_a && (_b = _e.return)) yield __await(_b.call(_e));
+                            }
+                            finally { if (e_11) throw e_11.error; }
+                        }
+                    });
+                }
+            });
+        },
+        glob(pattern, dir, options) {
+            return __asyncGenerator(this, arguments, function* glob_5() {
+                const dirPath = dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
+                yield __await(yield* __asyncDelegator(__asyncValues(globFromList(listed.list(dirPath === "/" ? undefined : dirPath), Object.assign({ pattern, dir: dirPath }, ((options === null || options === void 0 ? void 0 : options.limit) === undefined ? {} : { limit: options.limit }))))));
+            });
+        },
+        write(inputPath, contents) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield writeHost(inputPath, contents);
+            });
+        },
+        delete(inputPath) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const path = normalizeFsPath(inputPath);
+                const key = hostKey(path);
+                if (key === "" || !(yield files.exists(key, callOptions))) {
+                    throw new FileNotFoundError(path);
+                }
+                yield files.remove(key, callOptions);
+                readEtags.delete(key);
+            });
+        },
+        search: emptySearch,
+    };
+}
+function globFromList(source, options) {
+    return __asyncGenerator(this, arguments, function* globFromList_1() {
+        yield __await(yield* __asyncDelegator(__asyncValues(limitResults(uncapped(), options.limit))));
+        function uncapped() {
+            return __asyncGenerator(this, arguments, function* uncapped_9() {
+                var _a, e_12, _b, _c;
+                try {
+                    for (var _d = true, source_5 = __asyncValues(source), source_5_1; source_5_1 = yield __await(source_5.next()), _a = source_5_1.done, !_a; _d = true) {
+                        _c = source_5_1.value;
+                        _d = false;
+                        const entry = _c;
+                        if (pathMatchesGlob(entry.path, options.dir, options.pattern)) {
+                            yield yield __await(entry);
+                        }
+                    }
+                }
+                catch (e_12_1) { e_12 = { error: e_12_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = source_5.return)) yield __await(_b.call(source_5));
+                    }
+                    finally { if (e_12) throw e_12.error; }
+                }
+            });
+        }
+    });
+}