@eum-agent/file-explorer 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,1327 @@
+import { AccessErrorSchema, FileBytesParamsSchema, FileEntrySchema, FileTargetSchema, ListParamsSchema, ListResultSchema, MkdirParamsSchema, MoveParamsSchema, OperationResultSchema, OperationStatusParamsSchema, PathSchema, RemoveParamsSchema, RenameParamsSchema, RootsParamsSchema, RootsResultSchema, SegmentSchema, StatParamsSchema, StatResultSchema } from "./schema.js";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import nodePath, { join } from "node:path";
+//#region src/errors.ts
+/** Bounded extension errors safe for transport and operation records. */
+var FileAccessError = class extends Error {
+	/** Stable business code, never raw host exception text. */
+	code;
+	/** HTTP status used by the generic resource boundary. */
+	status;
+	/** Context validated by the provider's ErrorDetailsSchema before publication. */
+	details;
+	/** Carries a business code and JSON context without raw host exceptions or content. */
+	constructor(code, status, details) {
+		super(`File access failed: ${code}`);
+		this.name = "FileAccessError";
+		this.code = code;
+		this.status = status;
+		this.details = details;
+	}
+};
+/** Preserves known business errors and maps host failures without exposing paths or file bytes. */
+function accessError(error) {
+	if (error instanceof FileAccessError) return error;
+	if (error instanceof Error && error.name === "AbortError") return new FileAccessError("unavailable", 503);
+	const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+	const business = {
+		ENOENT: "missing",
+		EEXIST: "exists",
+		EACCES: "io-failed",
+		EPERM: "io-failed",
+		EXDEV: "cross-device",
+		"too-large": "too-large-directory"
+	}[code] ?? code;
+	const status = {
+		missing: 404,
+		exists: 409,
+		stale: 409,
+		sealed: 403,
+		"outside-root": 403,
+		"cross-device": 409,
+		unavailable: 503,
+		"too-large-directory": 413,
+		"unsupported-name": 415,
+		"unsupported-type": 415,
+		"unsupported-platform": 503
+	};
+	return new FileAccessError(business in status ? business : "io-failed", status[business] ?? 500);
+}
+//#endregion
+//#region src/path-semantics.ts
+/** Host path syntax only; resolved object identity remains the platform's responsibility. */
+/** Requires an independent absolute root, excluding Windows drive-relative and root-relative forms. */
+function isFullAbsolute(value, paths = nodePath) {
+	if (value.includes("\0") || !paths.isAbsolute(value)) return false;
+	if (paths.sep !== "\\") return true;
+	if (/^[A-Za-z]:[\\/]/.test(value)) return true;
+	const unc = /^[\\/]{2}([^\\/]+)[\\/]([^\\/]+)(?:[\\/]|$)/.exec(value);
+	const server = unc?.[1];
+	const share = unc?.[2];
+	return server !== void 0 && share !== void 0 && ![
+		".",
+		"..",
+		"?"
+	].includes(server) && ![".", ".."].includes(share);
+}
+/** Compares canonical ancestor segments exactly; drive-letter syntax alone is case-insensitive. */
+function containsHostPath(root, value, paths = nodePath) {
+	if (!isFullAbsolute(root, paths) || !isFullAbsolute(value, paths)) return false;
+	const parts = (path) => {
+		const normalized = paths.normalize(path);
+		const { root } = paths.parse(normalized);
+		return {
+			root: paths.sep === "\\" && /^[A-Za-z]:\\$/.test(root) ? root.toUpperCase() : root,
+			segments: normalized.slice(root.length).split(paths.sep).filter(Boolean)
+		};
+	};
+	const parent = parts(root);
+	const child = parts(value);
+	return parent.root === child.root && parent.segments.length <= child.segments.length && parent.segments.every((segment, index) => segment === child.segments[index]);
+}
+/** Converts a contained host path to validated wire segments without changing filename content. */
+function toWirePath(root, value, paths = nodePath) {
+	if (!containsHostPath(root, value, paths)) throw new FileAccessError("outside-root", 403);
+	const relative = paths.relative(root, value);
+	const wire = relative === "" ? "" : relative.split(paths.sep).join("/");
+	if (!PathSchema.safeParse(wire).success) throw new FileAccessError("outside-root", 403);
+	return wire;
+}
+//#endregion
+//#region src/scope.ts
+/** Revalidates explicit workspace scope while all data/namespace operations remain anchored. */
+/** Tests lexical containment of canonical host paths, retaining exact object segment case. */
+function contains(parent, child, paths = nodePath) {
+	return containsHostPath(parent, child, paths);
+}
+/** Current root and managed-media policy, deliberately independent of Agent approvals. */
+var FileScope = class {
+	roots;
+	files;
+	signal;
+	instanceId;
+	/** Consistent host path operations throughout selection, links and mutations. */
+	referenceFormatter;
+	/** Host path operations retain exact observed segment spelling. */
+	paths;
+	/** Binds this policy to one owner and Gateway startup. */
+	constructor(roots, files, signal, instanceId, paths = nodePath, referenceFormatter) {
+		this.roots = roots;
+		this.files = files;
+		this.signal = signal;
+		this.instanceId = instanceId;
+		this.paths = paths;
+		this.referenceFormatter = referenceFormatter;
+	}
+	/** Uses the reader owner's sole reference revision semantics for ordinary files and links. */
+	fingerprint(observation, referent) {
+		if (!this.referenceFormatter) throw new FileAccessError("unavailable", 503);
+		return this.referenceFormatter.fingerprint(observation, referent);
+	}
+	/** Returns a current explicit snapshot, refusing unavailable/mismatched startup identity. */
+	async snapshot(workspaceId, request) {
+		try {
+			this.signal.throwIfAborted();
+			request?.throwIfAborted();
+			if (!this.roots.availability().available || !this.files.availability().available) throw new FileAccessError("unavailable", 503);
+			const snapshot = await this.roots.read(workspaceId);
+			this.signal.throwIfAborted();
+			request?.throwIfAborted();
+			snapshot.signal.throwIfAborted();
+			if (snapshot.instanceId !== this.instanceId) throw new FileAccessError("instance-mismatch", 409);
+			await snapshot.assertCurrent();
+			this.signal.throwIfAborted();
+			request?.throwIfAborted();
+			snapshot.signal.throwIfAborted();
+			return snapshot;
+		} catch (error) {
+			throw accessError(error);
+		}
+	}
+	/** Pins a parent and observes the literal final entry; missing final entries may be admitted for writes. */
+	async select(target, request, missing = false) {
+		FileTargetSchema.parse(target);
+		const snapshot = await this.snapshot(target.workspaceId, request);
+		const selected = snapshot.roots.find((root) => root.id === target.rootId);
+		if (!selected) throw new FileAccessError("missing", 404);
+		const signal = AbortSignal.any([
+			this.signal,
+			snapshot.signal,
+			...request ? [request] : []
+		]);
+		const root = await this.files.anchor(selected.path, {
+			sealedDirectories: snapshot.sealedDirectories,
+			signal
+		});
+		try {
+			const segments = target.path === "" ? [] : target.path.split("/");
+			let name = segments.pop() ?? "";
+			const parent = segments.length ? await root.openDirectory(segments) : root;
+			let observation;
+			let referent;
+			try {
+				if (name) {
+					const entry = await parent.entry(name);
+					name = entry.name;
+					observation = entry.observation;
+					referent = entry.referent;
+				} else observation = await parent.stat();
+			} catch (error) {
+				if (!missing || accessError(error).code !== "missing") throw error;
+			}
+			const path = name ? this.paths.join(parent.path, name) : parent.path;
+			let effectivePath = path;
+			let referentObservation;
+			if (observation?.kind === "symlink") {
+				if (!referent) throw new FileAccessError("outside-root", 403);
+				effectivePath = referent.path;
+				referentObservation = referent.observation;
+			}
+			const current = async () => {
+				signal.throwIfAborted();
+				await snapshot.assertCurrent();
+				signal.throwIfAborted();
+			};
+			await current();
+			return {
+				target,
+				snapshot,
+				root,
+				parent,
+				name,
+				path,
+				effectivePath,
+				observation,
+				referentObservation,
+				signal,
+				current,
+				close: () => root.close()
+			};
+		} catch (error) {
+			await root.close();
+			throw accessError(error);
+		}
+	}
+	/** Protects managed media itself, descendants, aliases and ancestors affected by mutation. */
+	mutation(selection) {
+		if (!selection.name) throw new FileAccessError("outside-root", 403);
+		for (const sealed of selection.snapshot.sealedDirectories) for (const path of [selection.path, selection.effectivePath]) if (contains(path, sealed, this.paths) || contains(sealed, path, this.paths)) throw new FileAccessError("sealed", 403);
+		for (const protectedPath of selection.snapshot.protectedDirectories) for (const path of [selection.path, selection.effectivePath]) if (contains(protectedPath, path, this.paths) || contains(path, protectedPath, this.paths)) throw new FileAccessError("managed-storage", 403);
+	}
+	/** Keeps literal link kind/size while fingerprinting both its revision and selected referent. */
+	entry(selection, observation = selection.observation) {
+		if (!observation) throw new FileAccessError("missing", 404);
+		if (selection.name && !SegmentSchema.safeParse(selection.name).success) throw new FileAccessError("unsupported-name", 415);
+		const size = Number(observation.size);
+		if (!Number.isSafeInteger(size)) throw new FileAccessError("too-large", 413);
+		let mutable = true;
+		try {
+			this.mutation(selection);
+		} catch {
+			mutable = false;
+		}
+		const revision = this.fingerprint(observation, selection.referentObservation);
+		const name = selection.name || selection.snapshot.roots.find((root) => root.id === selection.target.rootId)?.name;
+		if (name === void 0) throw new FileAccessError("missing", 404);
+		return {
+			name,
+			path: selection.target.path,
+			kind: observation.kind,
+			size,
+			modifiedAt: Number(BigInt(observation.modifiedNs) / 1000000n),
+			fingerprint: revision,
+			uri: this.referenceUri(selection),
+			referenceKind: "current",
+			mutable
+		};
+	}
+	referenceUri(selection) {
+		const formatted = this.referenceFormatter?.formatCurrent?.({
+			gatewayId: selection.snapshot.gatewayId,
+			...selection.target
+		});
+		if (!formatted) throw new FileAccessError("unavailable", 503);
+		return formatted.uri;
+	}
+	/** Reobserves a published destination, resolving links at their new location. */
+	async freshEntry(target, signal) {
+		const selection = await this.select(target, signal);
+		try {
+			return this.entry(selection);
+		} finally {
+			await selection.close();
+		}
+	}
+};
+//#endregion
+//#region src/listings.ts
+/** Owner-local bounded immutable directory snapshots and opaque page cursors. */
+/** Keeps at most eight sixty-second snapshots; every page still revalidates current scope. */
+var Listings = class {
+	scope;
+	now;
+	snapshots = /* @__PURE__ */ new Map();
+	/** Shares the provider's scope and clock without retaining host descriptors. */
+	constructor(scope, now) {
+		this.scope = scope;
+		this.now = now;
+	}
+	/** Returns a 200-entry page of one immutable generation or refuses an expired/cross-target cursor. */
+	async list(params, signal) {
+		const selection = await this.scope.select(params.target, signal);
+		try {
+			const directory = selection.name ? await selection.parent.openDirectory([selection.name]) : selection.parent;
+			const current = this.scope.fingerprint(await directory.stat());
+			const now = this.now();
+			for (const [id, snapshot] of this.snapshots) if (now - snapshot.snapshotAt >= 6e4) this.snapshots.delete(id);
+			let snapshot;
+			let offset = 0;
+			if (params.cursor !== void 0) {
+				for (const candidate of this.snapshots.values()) for (const [position, cursor] of candidate.cursors) if (cursor === params.cursor) {
+					snapshot = candidate;
+					offset = position;
+				}
+				if (!snapshot || snapshot.target !== JSON.stringify(params.target)) throw new FileAccessError("stale-cursor", 409);
+			} else {
+				const observed = await directory.list(1e4);
+				const entries = [];
+				for (const item of observed) {
+					const path = [params.target.path, item.name].filter(Boolean).join("/");
+					if (item.observation.kind === "symlink") {
+						const linked = await this.scope.select({
+							...params.target,
+							path
+						}, signal);
+						try {
+							entries.push(this.scope.entry(linked));
+						} finally {
+							await linked.close();
+						}
+					} else entries.push(this.scope.entry({
+						...selection,
+						parent: directory,
+						name: item.name,
+						path: join(directory.path, item.name),
+						effectivePath: join(directory.path, item.name),
+						target: {
+							...params.target,
+							path
+						},
+						observation: item.observation
+					}));
+				}
+				if (this.scope.fingerprint(await directory.stat()) !== current) throw new FileAccessError("stale", 409);
+				const order = {
+					directory: 0,
+					file: 1,
+					symlink: 2,
+					other: 3
+				};
+				entries.sort((a, b) => order[a.kind] - order[b.kind] || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+				if (this.snapshots.size === 8) this.snapshots.delete(this.snapshots.keys().next().value);
+				snapshot = {
+					target: JSON.stringify(params.target),
+					entries,
+					listingId: randomUUID(),
+					snapshotAt: now,
+					fingerprint: current,
+					cursors: /* @__PURE__ */ new Map()
+				};
+				this.snapshots.set(snapshot.listingId, snapshot);
+			}
+			await selection.current();
+			const next = offset + 200;
+			let nextCursor;
+			if (next < snapshot.entries.length) {
+				nextCursor = snapshot.cursors.get(next) ?? randomUUID();
+				snapshot.cursors.set(next, nextCursor);
+			}
+			return {
+				entries: snapshot.entries.slice(offset, next),
+				nextCursor,
+				fingerprint: snapshot.fingerprint,
+				listingId: snapshot.listingId,
+				snapshotAt: snapshot.snapshotAt,
+				stale: snapshot.fingerprint !== current
+			};
+		} catch (error) {
+			throw accessError(error);
+		} finally {
+			await selection.close();
+		}
+	}
+	/** Releases in-memory generations on owner shutdown. */
+	close() {
+		this.snapshots.clear();
+	}
+};
+//#endregion
+//#region src/locks.ts
+/** Atomic acquisition of ordered canonical path sets prevents opposing moves from deadlocking. */
+/** Serializes overlapping selected paths, including recursive ancestors. */
+var PathLocks = class {
+	/** Binds lock overlap to the same host syntax as its selections. */
+	constructor(paths = nodePath) {
+		this.paths = paths;
+	}
+	paths;
+	active = /* @__PURE__ */ new Set();
+	waiting = [];
+	/** Acquires all deduplicated paths in fixed order, refusing cancelled queued work. */
+	acquire(paths, signal) {
+		signal.throwIfAborted();
+		return new Promise((resolve, reject) => {
+			const item = {
+				paths: [...new Set(paths)].sort(),
+				signal,
+				resolve,
+				reject
+			};
+			const aborted = () => {
+				const index = this.waiting.indexOf(item);
+				if (index >= 0) this.waiting.splice(index, 1);
+				reject(new FileAccessError("unavailable", 503));
+				this.wake();
+			};
+			signal.addEventListener("abort", aborted, { once: true });
+			const originalResolve = item.resolve;
+			item.resolve = (release) => {
+				signal.removeEventListener("abort", aborted);
+				originalResolve(release);
+			};
+			this.waiting.push(item);
+			this.wake();
+		});
+	}
+	wake() {
+		for (const item of [...this.waiting]) {
+			if (item.signal.aborted) continue;
+			if ([...this.active].some((paths) => paths.some((a) => item.paths.some((b) => contains(a, b, this.paths) || contains(b, a, this.paths))))) continue;
+			this.waiting.splice(this.waiting.indexOf(item), 1);
+			this.active.add(item.paths);
+			let released = false;
+			item.resolve(() => {
+				if (!released) {
+					released = true;
+					this.active.delete(item.paths);
+					this.wake();
+				}
+			});
+		}
+	}
+};
+//#endregion
+//#region src/mutations.ts
+/** Observed namespace operations serialized across canonical physical selections. */
+/** Compares object identity without treating an observation as permanent permission. */
+function sameObject(a, b) {
+	return a.device === b.device && a.inode === b.inode;
+}
+/** Acquires all canonical targets atomically and rejects alias changes while waiting. */
+async function withSelections(scope, locks, targets, signal, work) {
+	const preliminary = [];
+	const selections = [];
+	let release;
+	try {
+		try {
+			for (const target of targets) {
+				const selected = await scope.select(target, signal, true);
+				preliminary.push(selected);
+				scope.mutation(selected);
+			}
+			release = await locks.acquire(preliminary.flatMap((selected) => [selected.path, selected.effectivePath]), AbortSignal.any(preliminary.map((selected) => selected.signal)));
+		} finally {
+			await Promise.all(preliminary.map((selected) => selected.close()));
+		}
+		for (const [index, target] of targets.entries()) {
+			const selected = await scope.select(target, signal, true);
+			selections.push(selected);
+			if (selected.path !== preliminary[index]?.path || selected.effectivePath !== preliminary[index]?.effectivePath) throw new FileAccessError("stale", 409);
+			scope.mutation(selected);
+		}
+		return await work(selections);
+	} finally {
+		try {
+			await Promise.all(selections.map((selected) => selected.close()));
+		} finally {
+			release?.();
+		}
+	}
+}
+/** Rejects lexical containment and physical aliases/mount-root ancestry before any staging. */
+async function rejectOverlap(source, destination, paths = nodePath) {
+	const observed = source.observation;
+	if (!observed) throw new FileAccessError("missing", 404);
+	if (source.path === destination.path || source.effectivePath === destination.effectivePath || destination.observation && sameObject(observed, destination.observation) || observed.kind === "directory" && contains(source.effectivePath, destination.effectivePath, paths) || destination.observation?.kind === "directory" && contains(destination.effectivePath, source.effectivePath, paths)) throw new FileAccessError("path-overlap", 409);
+	const ancestorIncludes = async (selection, observation) => {
+		const parts = paths.relative(selection.root.path, selection.parent.path).split(paths.sep).filter(Boolean);
+		for (let length = 0; length <= parts.length; length++) {
+			const directory = await selection.root.openDirectory(parts.slice(0, length));
+			try {
+				if (sameObject(await directory.stat(), observation)) return true;
+			} finally {
+				await directory.close();
+			}
+		}
+		return false;
+	};
+	if (observed.kind === "directory" && await ancestorIncludes(destination, observed) || destination.observation?.kind === "directory" && await ancestorIncludes(source, destination.observation)) throw new FileAccessError("path-overlap", 409);
+}
+/** Requires the source revision and explicit, current replacement observation. */
+function observations(scope, source, expected, destination, replace = false, targetFingerprint) {
+	if (!source.observation) throw new FileAccessError("missing", 404);
+	if (scope.entry(source).fingerprint !== expected) throw new FileAccessError("stale", 409);
+	if (!destination) return void 0;
+	if (replace) {
+		if (!targetFingerprint || !destination.observation || scope.entry(destination).fingerprint !== targetFingerprint) throw new FileAccessError("stale", 409, destination.observation ? { existing: scope.entry(destination) } : void 0);
+		return destination.observation;
+	}
+	if (destination.observation) throw new FileAccessError("exists", 409, { existing: scope.entry(destination) });
+}
+/** Basic observed mutations; recursive and cross-device behavior compose through the same lock set. */
+var Mutations = class {
+	scope;
+	records;
+	locks;
+	trees;
+	/** Shares owner-local records and fixed-order locks with uploads. */
+	constructor(scope, records, locks, trees) {
+		this.scope = scope;
+		this.records = records;
+		this.locks = locks;
+		this.trees = trees;
+	}
+	/** Creates one exclusive directory and records the actual commit before cleanup. */
+	mkdir(params, signal) {
+		return this.records.run(params.operationId, {
+			method: "mkdir",
+			...params
+		}, (commit) => withSelections(this.scope, this.locks, [params.target], signal, async ([target]) => {
+			const selected = target;
+			if (selected.observation) throw new FileAccessError("exists", 409, { existing: this.scope.entry(selected) });
+			await selected.current();
+			this.scope.mutation(selected);
+			const observed = await selected.parent.mkdir(selected.name);
+			const entry = this.scope.entry(selected, observed);
+			commit(entry);
+			return entry;
+		}));
+	}
+	/** Renames within one root, refusing stale source/target or physical containment. */
+	rename(params, signal) {
+		const segments = params.source.path.split("/");
+		segments.pop();
+		const destination = {
+			...params.source,
+			path: [...segments, params.name].join("/")
+		};
+		return this.records.run(params.operationId, {
+			method: "rename",
+			...params,
+			replace: params.replace ?? false
+		}, (commit) => withSelections(this.scope, this.locks, [params.source, destination], signal, async ([from, to]) => {
+			await rejectOverlap(from, to, this.scope.paths);
+			const replacement = observations(this.scope, from, params.sourceFingerprint, to, params.replace, params.targetFingerprint);
+			const tree = await this.trees.scan(from);
+			await from.current();
+			await to.current();
+			this.scope.mutation(from);
+			this.scope.mutation(to);
+			await this.trees.verify(from, tree);
+			await from.parent.rename(from.name, from.observation, to.parent, to.name, replacement);
+			commit();
+			const entry = await this.scope.freshEntry(to.target, to.signal);
+			commit(entry);
+			return entry;
+		}));
+	}
+	/** Removes exactly one selected object unless explicit recursive behavior is requested. */
+	remove(params, signal) {
+		return this.records.run(params.operationId, {
+			method: "remove",
+			...params
+		}, (commit) => withSelections(this.scope, this.locks, [params.target], signal, async ([target]) => {
+			const selected = target;
+			observations(this.scope, selected, params.fingerprint);
+			if (params.recursive && selected.observation?.kind === "directory") {
+				const records = await this.trees.scan(selected);
+				await this.trees.remove(selected, records);
+				commit();
+				return;
+			}
+			await selected.current();
+			this.scope.mutation(selected);
+			await selected.parent.remove(selected.name, selected.observation);
+			commit();
+		}));
+	}
+};
+//#endregion
+//#region src/moves.ts
+/** Moves within one workspace, preferring anchored rename and explicitly handling EXDEV. */
+var Moves = class {
+	scope;
+	records;
+	locks;
+	trees;
+	/** Shares operation records and ordered locks with all other writes. */
+	constructor(scope, records, locks, trees) {
+		this.scope = scope;
+		this.records = records;
+		this.locks = locks;
+		this.trees = trees;
+	}
+	/** Rejects overlap and stale selections before changing either namespace. */
+	move(params, signal) {
+		return this.records.run(params.operationId, {
+			method: "move",
+			...params,
+			replace: params.replace ?? false
+		}, (commit) => withSelections(this.scope, this.locks, [params.source, params.destination], signal, async ([source, destination]) => {
+			if (params.source.workspaceId !== params.destination.workspaceId) throw new FileAccessError("outside-root", 403);
+			const from = source, to = destination;
+			await rejectOverlap(from, to, this.scope.paths);
+			const replacement = observations(this.scope, from, params.sourceFingerprint, to, params.replace, params.targetFingerprint);
+			const copied = await this.trees.scan(from);
+			await from.current();
+			await to.current();
+			this.scope.mutation(from);
+			this.scope.mutation(to);
+			await this.trees.verify(from, copied);
+			try {
+				await from.parent.rename(from.name, from.observation, to.parent, to.name, replacement);
+			} catch (error) {
+				if (accessError(error).code !== "cross-device") throw error;
+				let destinationCommitted = false;
+				let entry;
+				try {
+					await this.copy(from, to, copied, replacement, () => {
+						destinationCommitted = true;
+					});
+					entry = await this.scope.freshEntry(to.target, to.signal);
+					await from.current();
+					await to.current();
+					await this.trees.remove(from, copied);
+				} catch (failure) {
+					if (!destinationCommitted) throw failure;
+					let retained = true;
+					try {
+						await from.parent.stat(from.name);
+					} catch (failure) {
+						if (accessError(failure).code === "missing") retained = false;
+					}
+					throw new FileAccessError("move-incomplete", 500, {
+						destinationCommitted: true,
+						sourceRetained: retained,
+						retainedPaths: retained ? [from.target.path] : []
+					});
+				}
+				commit(entry);
+				return entry;
+			}
+			commit();
+			const entry = await this.scope.freshEntry(to.target, to.signal);
+			commit(entry);
+			return entry;
+		}));
+	}
+	async copyFile(from, parts, observation, stage) {
+		const reader = await from.root.openRead([...from.target.path.split("/"), ...parts]);
+		try {
+			if (this.scope.fingerprint(await reader.stat()) !== this.scope.fingerprint(observation)) throw new FileAccessError("stale", 409);
+			const size = Number(observation.size);
+			if (!Number.isSafeInteger(size)) throw new FileAccessError("too-large", 413);
+			for (let position = 0; position < size;) {
+				await from.current();
+				const bytes = await reader.read(position, Math.min(65536, size - position));
+				if (!bytes.byteLength) throw new FileAccessError("stale", 409);
+				await stage.write(bytes);
+				position += bytes.byteLength;
+			}
+			if (this.scope.fingerprint(await reader.stat()) !== this.scope.fingerprint(observation)) throw new FileAccessError("stale", 409);
+			if (observation.mode !== void 0) await stage.setMode(observation.mode);
+			await stage.sync();
+		} finally {
+			await reader.close();
+		}
+	}
+	async copiedLink(from, parent, parts) {
+		const sourceParent = await from.root.openDirectory([...from.target.path.split("/"), ...parts.slice(0, -1)]);
+		const name = parts.at(-1);
+		try {
+			const link = await sourceParent.readLink(name);
+			await parent.symlink(name, link);
+		} finally {
+			await sourceParent.close();
+		}
+	}
+	async copy(from, to, records, replacement, onPublished) {
+		const kind = from.observation?.kind;
+		if (kind === "other") throw new FileAccessError("unsupported-type", 415);
+		if (kind === "file") {
+			const stage = await to.parent.stage();
+			try {
+				await this.copyFile(from, [], from.observation, stage);
+				await this.trees.verify(from, records);
+				await from.current();
+				await to.current();
+				this.scope.mutation(from);
+				this.scope.mutation(to);
+				const observation = await stage.publish(to.name, replacement);
+				onPublished();
+				return observation;
+			} finally {
+				if (stage.published) onPublished();
+				await stage.close();
+			}
+		}
+		if (kind === "symlink") {
+			const link = await from.parent.readLink(from.name);
+			const stage = await to.parent.stageSymlink(link);
+			try {
+				const linked = await this.scope.select({
+					...to.target,
+					path: toWirePath(to.root.path, stage.path, this.scope.paths)
+				}, to.signal);
+				try {
+					this.scope.mutation(linked);
+				} finally {
+					await linked.close();
+				}
+				await this.trees.verify(from, records);
+				await from.current();
+				await to.current();
+				this.scope.mutation(from);
+				this.scope.mutation(to);
+				const observation = await stage.publish(to.name, replacement);
+				onPublished();
+				return observation;
+			} finally {
+				if (stage.published) onPublished();
+				await stage.close();
+			}
+		}
+		const stage = await to.parent.stageDirectory();
+		try {
+			for (const record of records.filter((item) => item.parts.length && item.observation.kind === "directory")) {
+				const parent = await stage.directory.openDirectory(record.parts.slice(0, -1));
+				try {
+					await parent.mkdir(record.parts.at(-1));
+				} finally {
+					await parent.close();
+				}
+			}
+			const nonDirectories = records.filter((item) => item.observation.kind !== "directory").sort((a, b) => Number(a.observation.kind === "symlink") - Number(b.observation.kind === "symlink"));
+			for (const record of nonDirectories) {
+				await from.current();
+				await to.current();
+				const parent = await stage.directory.openDirectory(record.parts.slice(0, -1));
+				try {
+					if (record.observation.kind === "symlink") await this.copiedLink(from, parent, record.parts);
+					else if (record.observation.kind === "file") {
+						const file = await parent.stage();
+						try {
+							await this.copyFile(from, record.parts, record.observation, file);
+							await file.publish(record.parts.at(-1));
+						} finally {
+							await file.close();
+						}
+					} else throw new FileAccessError("unsupported-type", 415);
+				} finally {
+					await parent.close();
+				}
+			}
+			for (const record of records.filter((item) => item.observation.kind === "symlink")) {
+				const linked = await this.scope.select({
+					...to.target,
+					path: toWirePath(to.root.path, this.scope.paths.join(stage.directory.path, ...record.parts), this.scope.paths)
+				}, to.signal);
+				try {
+					this.scope.mutation(linked);
+				} finally {
+					await linked.close();
+				}
+			}
+			await this.trees.verify(from, records);
+			await from.current();
+			await to.current();
+			this.scope.mutation(from);
+			this.scope.mutation(to);
+			for (const record of records.filter((item) => item.observation.kind === "directory").sort((a, b) => b.parts.length - a.parts.length)) if (record.observation.mode !== void 0) await stage.setDirectoryMode(record.parts, record.observation.mode);
+			await from.current();
+			await to.current();
+			this.scope.mutation(from);
+			this.scope.mutation(to);
+			const observation = await stage.publish(to.name, replacement);
+			onPublished();
+			return observation;
+		} finally {
+			if (stage.published) onPublished();
+			await stage.close();
+		}
+	}
+};
+//#endregion
+//#region src/operation-records.ts
+/** Short-lived facts and in-flight deduplication; eviction never implies replay safety. */
+/** Canonical JSON makes equivalent property ordering share one operation key. */
+function canonicalRequest(value) {
+	if (Array.isArray(value)) return `[${value.map(canonicalRequest).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonicalRequest(item)}`).join(",")}}`;
+	return JSON.stringify(value);
+}
+/** Retains at most 1000 records, with ten-minute settled facts and no eviction of active work. */
+var OperationRecords = class {
+	instanceId;
+	now;
+	records = /* @__PURE__ */ new Map();
+	/** Uses actual Gateway startup identity and a clock shared with snapshots. */
+	constructor(instanceId, now) {
+		this.instanceId = instanceId;
+		this.now = now;
+	}
+	expire() {
+		for (const [id, record] of this.records) if (!record.pending && record.settledAt !== void 0 && this.now() - record.settledAt >= 6e5) this.records.delete(id);
+	}
+	/** Queries an existing fact only; cross-startup, expired and evicted records return unknown. */
+	status(instanceId, operationId) {
+		this.expire();
+		return instanceId === this.instanceId ? this.records.get(operationId)?.result ?? {
+			operationId,
+			instanceId,
+			status: "unknown"
+		} : {
+			operationId,
+			instanceId,
+			status: "unknown"
+		};
+	}
+	/** Executes once while retained; an explicit commit records a fact before asynchronous release. */
+	run(operationId, request, work) {
+		this.expire();
+		const key = canonicalRequest(request);
+		const existing = this.records.get(operationId);
+		if (existing) {
+			if (existing.key !== key) throw new FileAccessError("operation-conflict", 409);
+			return existing.promise;
+		}
+		if (this.records.size >= 1e3) {
+			const settled = [...this.records.entries()].filter(([, record]) => !record.pending).sort(([, a], [, b]) => (a.settledAt ?? 0) - (b.settledAt ?? 0))[0];
+			if (!settled) throw new FileAccessError("capacity", 429);
+			this.records.delete(settled[0]);
+		}
+		const record = {
+			key,
+			result: {
+				operationId,
+				instanceId: this.instanceId,
+				status: "pending"
+			},
+			pending: true,
+			promise: Promise.resolve({
+				operationId,
+				instanceId: this.instanceId,
+				status: "pending"
+			})
+		};
+		this.records.set(operationId, record);
+		const commit = (entry) => {
+			record.result = {
+				operationId,
+				instanceId: this.instanceId,
+				status: "succeeded",
+				...entry ? { entry } : {}
+			};
+		};
+		record.promise = Promise.resolve().then(async () => {
+			try {
+				const entry = await work(commit);
+				if (record.result.status === "pending") commit(entry);
+			} catch (error) {
+				if (record.result.status !== "succeeded") {
+					const failure = accessError(error);
+					const wire = AccessErrorSchema.parse({
+						code: failure.code,
+						message: failure.message,
+						...failure.details ? { details: failure.details } : {}
+					});
+					record.result = {
+						operationId,
+						instanceId: this.instanceId,
+						status: "failed",
+						error: wire
+					};
+				}
+			} finally {
+				record.pending = false;
+				record.settledAt = this.now();
+			}
+			return record.result;
+		});
+		return record.promise;
+	}
+	/** Waits for active work; cancellation is supplied by the owning provider. */
+	async drain() {
+		await Promise.allSettled([...this.records.values()].filter((record) => record.pending).map((record) => record.promise));
+	}
+};
+//#endregion
+//#region src/transfers.ts
+async function nextChunk(iterator, signal) {
+	if (signal.aborted) throw new FileAccessError("unavailable", 503);
+	return new Promise((resolve, reject) => {
+		const aborted = () => {
+			signal.removeEventListener("abort", aborted);
+			reject(new FileAccessError("unavailable", 503));
+		};
+		signal.addEventListener("abort", aborted, { once: true });
+		Promise.resolve().then(() => iterator.next()).then(resolve, reject).finally(() => signal.removeEventListener("abort", aborted)).catch(() => {});
+	});
+}
+/** Resolves one inclusive range from the opened object's actual safe-integer length. */
+function byteRange(total, request) {
+	if (!request) return void 0;
+	const start = request.kind === "suffix" ? Math.max(0, total - request.length) : request.start;
+	const end = request.kind === "suffix" ? total - 1 : Math.min(request.end ?? total - 1, total - 1);
+	if (total === 0 || !Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || start >= total || end < start || request.kind === "suffix" && (!Number.isSafeInteger(request.length) || request.length <= 0)) throw new FileAccessError("invalid-range", 416, { contentLength: total });
+	return {
+		start,
+		end,
+		total
+	};
+}
+/** Reads the current selected regular file without buffering the full response. */
+async function readFileResource(scope, params, call) {
+	const selection = await scope.select(params.target, call.signal);
+	try {
+		const entry = scope.entry(selection);
+		if (params.expectedFingerprint && params.expectedFingerprint !== entry.fingerprint) throw new FileAccessError("stale", 409);
+		const reader = await selection.root.openRead(params.target.path.split("/").filter(Boolean));
+		const observation = await reader.stat();
+		if (scope.fingerprint(observation) !== scope.fingerprint(selection.referentObservation ?? selection.observation) || scope.fingerprint(await selection.parent.stat(selection.name)) !== scope.fingerprint(selection.observation)) throw new FileAccessError("stale", 409);
+		const total = Number(observation.size);
+		if (!Number.isSafeInteger(total)) throw new FileAccessError("too-large", 413);
+		const range = call.method === "GET" ? byteRange(total, call.range) : void 0;
+		const bytes = {
+			contentType: "application/octet-stream",
+			contentLength: range ? range.end - range.start + 1 : total,
+			contentDisposition: {
+				filename: entry.name,
+				disposition: "attachment"
+			},
+			range
+		};
+		let closed = false;
+		const close = async () => {
+			if (!closed) {
+				closed = true;
+				await selection.close();
+			}
+		};
+		if (call.method === "HEAD") {
+			await close();
+			return {
+				kind: "head",
+				bytes,
+				metadata: entry
+			};
+		}
+		return {
+			kind: "bytes",
+			bytes,
+			metadata: entry,
+			body: (async function* () {
+				try {
+					let position = range?.start ?? 0;
+					const end = range ? range.end + 1 : total;
+					while (position < end) {
+						if (closed) throw new FileAccessError("unavailable", 503);
+						await selection.current();
+						const chunk = await reader.read(position, Math.min(65536, end - position));
+						await selection.current();
+						if (chunk.byteLength === 0) throw new FileAccessError("stale", 409);
+						position += chunk.byteLength;
+						yield chunk;
+					}
+				} catch (error) {
+					throw accessError(error);
+				} finally {
+					await close();
+				}
+			})(),
+			close
+		};
+	} catch (error) {
+		await selection.close();
+		throw accessError(error);
+	}
+}
+/** Streams a bounded upload into same-directory staging, recording publication before release. */
+async function uploadResource(scope, records, locks, params, call) {
+	if (!params.operationId || !params.source) throw new FileAccessError("invalid-params", 400);
+	const source = params.source;
+	const result = await records.run(params.operationId, {
+		method: "upload",
+		...params,
+		replace: params.replace ?? false
+	}, async (commit) => {
+		if (source.size > 268435456) throw new FileAccessError("too-large", 413);
+		const preliminary = await scope.select(params.target, call.signal, true);
+		const selectedPath = preliminary.path;
+		let release;
+		try {
+			try {
+				scope.mutation(preliminary);
+				release = await locks.acquire([preliminary.path], preliminary.signal);
+			} finally {
+				await preliminary.close();
+			}
+			const selection = await scope.select(params.target, call.signal, true);
+			try {
+				if (selection.path !== selectedPath) throw new FileAccessError("stale", 409);
+				scope.mutation(selection);
+				const existing = selection.observation;
+				if (params.replace) {
+					if (!params.targetFingerprint || !existing || scope.entry(selection).fingerprint !== params.targetFingerprint) throw new FileAccessError("stale", 409, existing ? { existing: scope.entry(selection) } : void 0);
+				} else if (existing) throw new FileAccessError("exists", 409, { existing: scope.entry(selection) });
+				const stage = await selection.parent.stage();
+				let publishedEntry;
+				const iterator = call.body[Symbol.asyncIterator]();
+				try {
+					let total = 0;
+					for (;;) {
+						const next = await nextChunk(iterator, selection.signal);
+						if (next.done) break;
+						const chunk = next.value;
+						await selection.current();
+						total += chunk.byteLength;
+						if (total > 268435456) throw new FileAccessError("too-large", 413);
+						if (total > source.size) throw new FileAccessError("size-mismatch", 400);
+						for (let offset = 0; offset < chunk.byteLength; offset += 65536) {
+							await stage.write(chunk.subarray(offset, offset + 65536));
+							await selection.current();
+						}
+					}
+					if (total !== source.size) throw new FileAccessError("size-mismatch", 400);
+					if (existing?.mode !== void 0) await stage.setMode(existing.mode);
+					await stage.sync();
+					await selection.current();
+					scope.mutation(selection);
+					const observation = await stage.publish(selection.name, params.replace ? existing : void 0);
+					const entry = scope.entry(selection, observation);
+					publishedEntry = entry;
+					commit(entry);
+					return entry;
+				} finally {
+					if (stage.published) commit(publishedEntry);
+					try {
+						const returned = iterator.return?.();
+						if (selection.signal.aborted) Promise.resolve(returned).catch(() => {});
+						else await returned;
+					} finally {
+						await stage.close();
+					}
+				}
+			} finally {
+				await selection.close();
+			}
+		} finally {
+			release?.();
+		}
+	});
+	return {
+		kind: "json",
+		result,
+		...result.entry ? { metadata: result.entry } : {}
+	};
+}
+//#endregion
+//#region src/trees.ts
+/** Records all selected objects before side effects, then checks each pending deletion separately. */
+var Trees = class {
+	scope;
+	budget;
+	/** Test budgets may be smaller; production cannot exceed the declared maximum. */
+	constructor(scope, budget = {
+		maxObjects: 1e4,
+		maxDepth: 256
+	}) {
+		if (!Number.isInteger(budget.maxObjects) || budget.maxObjects < 1 || budget.maxObjects > 1e4 || !Number.isInteger(budget.maxDepth) || budget.maxDepth < 0 || budget.maxDepth > 256) throw new Error("Invalid recursive tree budget");
+		this.scope = scope;
+		this.budget = budget;
+	}
+	/** Scans an entire tree before staging/deletion, refusing excess, protected entries or changes. */
+	async scan(selection) {
+		const result = [];
+		const visit = async (parent, name, observation, parts) => {
+			if (!SegmentSchema.safeParse(name).success) throw new FileAccessError("unsupported-name", 415);
+			if (parts.length > this.budget.maxDepth || result.length >= this.budget.maxObjects) throw new FileAccessError("too-large-directory", 413);
+			await selection.current();
+			const path = [selection.target.path, ...parts].filter(Boolean).join("/");
+			if (observation.kind === "symlink") {
+				const linked = await this.scope.select({
+					...selection.target,
+					path
+				}, selection.signal);
+				try {
+					this.scope.mutation(linked);
+				} finally {
+					await linked.close();
+				}
+			} else this.scope.mutation({
+				...selection,
+				name,
+				path: this.scope.paths.join(parent.path, name),
+				effectivePath: this.scope.paths.join(parent.path, name),
+				target: {
+					...selection.target,
+					path
+				}
+			});
+			if (observation.kind !== "directory") {
+				result.push({
+					parts,
+					observation
+				});
+				return;
+			}
+			const directory = await parent.openDirectory([name]);
+			try {
+				if (this.scope.fingerprint(await directory.stat()) !== this.scope.fingerprint(observation)) throw new FileAccessError("stale", 409);
+				const entries = [...await directory.list(1e4, { strict: true })].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+				result.push({
+					parts,
+					observation,
+					children: entries.map((entry) => entry.name)
+				});
+				for (const entry of entries) await visit(directory, entry.name, entry.observation, [...parts, entry.name]);
+				if (this.scope.fingerprint(await directory.stat()) !== this.scope.fingerprint(observation)) throw new FileAccessError("stale", 409);
+			} finally {
+				await directory.close();
+			}
+		};
+		if (!selection.observation) throw new FileAccessError("missing", 404);
+		await visit(selection.parent, selection.name, selection.observation, []);
+		return result;
+	}
+	/** Rechecks every selected object and directory child set before publication or source cleanup. */
+	async verify(selection, records) {
+		const current = await this.scan(selection);
+		if (current.length !== records.length || current.some((item, index) => item.parts.join("/") !== records[index]?.parts.join("/") || this.scope.fingerprint(item.observation) !== this.scope.fingerprint(records[index]?.observation))) throw new FileAccessError("stale", 409);
+	}
+	/** Deletes copied versions in postorder, stopping immediately on new or changed pending content. */
+	async remove(selection, records) {
+		await this.verify(selection, records);
+		const byPath = new Map(records.map((record) => [record.parts.join("/"), record]));
+		const visit = async (parent, name, record) => {
+			await selection.current();
+			this.scope.mutation(selection);
+			if (this.scope.fingerprint(await parent.stat(name)) !== this.scope.fingerprint(record.observation)) throw new FileAccessError("stale", 409);
+			if (record.observation.kind !== "directory") {
+				await parent.remove(name, record.observation);
+				return;
+			}
+			const directory = await parent.openDirectory([name]);
+			try {
+				let expected = record.observation;
+				const remaining = [...record.children];
+				for (const child of record.children) {
+					if (this.scope.fingerprint(await directory.stat()) !== this.scope.fingerprint(expected)) throw new FileAccessError("stale", 409);
+					const actual = (await directory.list(1e4, { strict: true })).map((entry) => entry.name).sort();
+					if (JSON.stringify(actual) !== JSON.stringify(remaining)) throw new FileAccessError("stale", 409);
+					await visit(directory, child, byPath.get([...record.parts, child].join("/")));
+					remaining.splice(remaining.indexOf(child), 1);
+					expected = await directory.stat();
+				}
+				if ((await directory.list(1e4, { strict: true })).length !== 0 || this.scope.fingerprint(await directory.stat()) !== this.scope.fingerprint(expected)) throw new FileAccessError("stale", 409);
+				await selection.current();
+				this.scope.mutation(selection);
+				await parent.remove(name, expected);
+			} finally {
+				await directory.close();
+			}
+		};
+		await visit(selection.parent, selection.name, records[0]);
+	}
+};
+//#endregion
+//#region src/provider.ts
+/** Creates an owner-local provider with bounded transient state. */
+function createFileExplorer(dependencies) {
+	const abort = new AbortController();
+	const signal = AbortSignal.any([abort.signal, dependencies.signal]);
+	const scope = new FileScope(dependencies.roots, dependencies.files, signal, dependencies.instanceId, void 0, dependencies.referenceFormatter);
+	const listings = new Listings(scope, dependencies.now ?? Date.now);
+	const records = new OperationRecords(dependencies.instanceId, dependencies.now ?? Date.now);
+	const locks = new PathLocks();
+	const trees = new Trees(scope, dependencies.treeBudget);
+	const mutations = new Mutations(scope, records, locks, trees);
+	const moves = new Moves(scope, records, locks, trees);
+	const current = () => {
+		if (signal.aborted) throw new FileAccessError("unavailable", 503);
+	};
+	const active = /* @__PURE__ */ new Set();
+	let closing;
+	const track = (work) => {
+		try {
+			current();
+		} catch (error) {
+			return Promise.reject(error);
+		}
+		const promise = Promise.resolve().then(() => {
+			current();
+			return work();
+		});
+		active.add(promise);
+		promise.then(() => active.delete(promise), () => active.delete(promise));
+		return promise;
+	};
+	return {
+		/** Returns explicit root display metadata for the named workspace. */
+		roots: (workspaceId, request) => track(async () => {
+			return { roots: (await scope.snapshot(workspaceId, request)).roots };
+		}),
+		/** Observes one current object and its resolved host display path. */
+		stat: (target, request) => track(async () => {
+			const selection = await scope.select(target, request);
+			try {
+				return {
+					entry: scope.entry(selection),
+					realPath: selection.effectivePath
+				};
+			} finally {
+				await selection.close();
+			}
+		}),
+		/** Pages immutable bounded snapshots while rechecking current scope. */
+		list: (params, request) => track(() => listings.list(params, request)),
+		/** Streams current GET/HEAD bytes or a staged bounded PUT upload. */
+		fileBytes: (params, call) => track(() => call.method === "PUT" ? uploadResource(scope, records, locks, params, call) : readFileResource(scope, params, call)),
+		/** Queries retained execution facts without replaying any work. */
+		operationStatus: (params) => {
+			current();
+			return records.status(params.instanceId, params.operationId);
+		},
+		/** Creates one directory exclusively with operation deduplication. */
+		mkdir: (params, request) => track(() => mutations.mkdir(params, request)),
+		/** Renames an observed object within its current root. */
+		rename: (params, request) => track(() => mutations.rename(params, request)),
+		/** Removes only the selected revision; recursive removal scans every descendant. */
+		remove: (params, request) => track(() => mutations.remove(params, request)),
+		/** Moves within one workspace, preserving committed-destination facts on cleanup failure. */
+		move: (params, request) => track(() => moves.move(params, request)),
+		/** Rejects new work and joins cleanup; failed physical cleanup remains retryable. */
+		close() {
+			closing ??= (async () => {
+				abort.abort();
+				listings.close();
+				await Promise.allSettled([...active]);
+				await records.drain();
+				await dependencies.files.close();
+			})().catch((error) => {
+				closing = void 0;
+				throw error;
+			});
+			return closing;
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+/** Workspace browsing provider registration; never contributes Agent tools or approvals. */
+/** Registers one activation's provider and awaited shutdown drain. */
+function registerFileExplorer(ctx) {
+	const roots = ctx.services.get("workspace-roots");
+	const identity = roots.availability();
+	if (!identity.available) throw new FileAccessError("unavailable", 503);
+	const provider = createFileExplorer({
+		files: ctx.services.get("client-files"),
+		referenceFormatter: ctx.services.get("file-reference-formatter"),
+		roots,
+		signal: ctx.signal,
+		instanceId: identity.instanceId
+	});
+	const drain = () => provider.close();
+	const unbind = ctx.services.get("work-lifecycle").register(drain);
+	ctx.onDispose(async () => {
+		await drain();
+		unbind();
+	});
+	ctx.client.registerMethod({
+		name: "roots",
+		params: RootsParamsSchema,
+		result: RootsResultSchema,
+		handle: (params, call) => provider.roots(params.workspaceId, call.signal)
+	});
+	ctx.client.registerMethod({
+		name: "list",
+		params: ListParamsSchema,
+		result: ListResultSchema,
+		handle: (params, call) => provider.list(params, call.signal)
+	});
+	ctx.client.registerMethod({
+		name: "stat",
+		params: StatParamsSchema,
+		result: StatResultSchema,
+		handle: (params, call) => provider.stat(params.target, call.signal)
+	});
+	ctx.client.registerMethod({
+		name: "mkdir",
+		params: MkdirParamsSchema,
+		result: OperationResultSchema,
+		handle: (params, call) => provider.mkdir(params, call.signal)
+	});
+	ctx.client.registerMethod({
+		name: "rename",
+		params: RenameParamsSchema,
+		result: OperationResultSchema,
+		handle: (params, call) => provider.rename(params, call.signal)
+	});
+	ctx.client.registerMethod({
+		name: "move",
+		params: MoveParamsSchema,
+		result: OperationResultSchema,
+		handle: (params, call) => provider.move(params, call.signal)
+	});
+	ctx.client.registerMethod({
+		name: "remove",
+		params: RemoveParamsSchema,
+		result: OperationResultSchema,
+		handle: (params, call) => provider.remove(params, call.signal)
+	});
+	ctx.client.registerMethod({
+		name: "operationStatus",
+		params: OperationStatusParamsSchema,
+		result: OperationResultSchema,
+		handle: (params) => provider.operationStatus(params)
+	});
+	ctx.client.registerResource({
+		name: "fileBytes",
+		methods: [
+			"GET",
+			"HEAD",
+			"PUT"
+		],
+		params: FileBytesParamsSchema,
+		result: OperationResultSchema,
+		metadata: FileEntrySchema.optional(),
+		handle: (params, call) => provider.fileBytes(params, call)
+	});
+	const module = fileURLToPath(new URL("../ui/ui.js", import.meta.url));
+	if (existsSync(module)) ctx.client.registerUi({ module });
+}
+const plugin = {
+	name: "@eum-agent/file-explorer",
+	dependencies: { "@eum-agent/file-references": "1.0.0" },
+	requires: [
+		"client-files",
+		"workspace-roots",
+		"work-lifecycle",
+		"file-reference-formatter"
+	],
+	apply: registerFileExplorer
+};
+//#endregion
+export { plugin as default, registerFileExplorer };