@deepseek-ai/dsh-tool-fs 0.0.1-rc.1

package/lib/index.js

@@ -0,0 +1,979 @@
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { ESCALATION_TARGETS, approveEscalation, canonicalPath, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
+import { structuredPatch } from "diff";
+//#region lib/types/read-render.js
+/**
+* Pure read presentation: turn provider-decoded text into a bounded, line-numbered window and
+* model-facing envelope. Chunk scanning caps the current line, so even one newline-free giant
+* line cannot grow memory without bound.
+* @module @deepseek-ai/dsh-tool-fs/read-render
+*/
+/** Default maximum characters returned for a single line (the `readMaxLineLength` config). */
+const READ_MAX_LINE_LENGTH = 2e3;
+/** Default maximum bytes returned for selected file lines (the `readMaxBytes` config). */
+const READ_MAX_BYTES = 50 * 1024;
+function newAccumulator() {
+	return {
+		lines: [],
+		totalLines: 0,
+		outputBytes: 0,
+		truncatedByBytes: false
+	};
+}
+function truncateLine(line, maxLineLength) {
+	return line.length > maxLineLength ? `${line.substring(0, maxLineLength)}... (line truncated to ${maxLineLength} chars)` : line;
+}
+function lineByteSize(line, currentLineCount) {
+	return Buffer.byteLength(line, "utf8") + (currentLineCount > 0 ? 1 : 0);
+}
+function consumeLine(acc, rawLine, request) {
+	acc.totalLines += 1;
+	if (acc.truncatedByBytes || acc.totalLines < request.offset || acc.lines.length >= request.limit) return;
+	const text = truncateLine(rawLine, request.maxLineLength);
+	const bytes = lineByteSize(text, acc.lines.length);
+	if (acc.outputBytes + bytes > request.maxBytes) {
+		acc.truncatedByBytes = true;
+		return;
+	}
+	acc.outputBytes += bytes;
+	acc.lines.push({
+		number: acc.totalLines,
+		text
+	});
+}
+function stripCarriageReturn(line) {
+	return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+function finish(acc, request, displayPath) {
+	if (!acc.truncatedByBytes && request.offset > acc.totalLines && !(acc.totalLines === 0 && request.offset === 1)) throw new FsError(`offset ${request.offset} is out of range for "${displayPath}" (${acc.totalLines} lines)`, "FS_NOT_FOUND");
+	return {
+		lines: acc.lines,
+		totalLines: acc.totalLines,
+		truncatedByBytes: acc.truncatedByBytes
+	};
+}
+/**
+* Build one window from streamed or whole-file chunks, enforcing line and byte caps while still
+* scanning to an exact total line count, and throwing `FS_NOT_FOUND` when the requested offset is
+* past EOF.
+* @param chunks - decoded text chunks in file order; chunk boundaries carry no meaning.
+* @param request - the resolved window; the caller has already applied its defaults and caps.
+* @param displayPath - the caller-facing path used in the offset-out-of-range error.
+* @returns the numbered window lines, the total line count seen, and the byte-cap truncation flag.
+*/
+async function buildWindow(chunks, request, displayPath) {
+	const acc = newAccumulator();
+	const lineBufferCap = request.maxLineLength + 1;
+	let lineBuffer = "";
+	function appendToLineBuffer(segment) {
+		if (lineBuffer.length >= lineBufferCap) return;
+		lineBuffer += segment;
+		if (lineBuffer.length > lineBufferCap) lineBuffer = lineBuffer.slice(0, lineBufferCap);
+	}
+	function flushLine() {
+		consumeLine(acc, stripCarriageReturn(lineBuffer), request);
+		lineBuffer = "";
+	}
+	for await (const chunk of chunks) {
+		let startPos = 0;
+		let newlinePos;
+		while ((newlinePos = chunk.indexOf("\n", startPos)) !== -1) {
+			appendToLineBuffer(chunk.slice(startPos, newlinePos));
+			flushLine();
+			startPos = newlinePos + 1;
+		}
+		appendToLineBuffer(chunk.slice(startPos));
+	}
+	if (lineBuffer.length > 0) flushLine();
+	return finish(acc, request, displayPath);
+}
+/**
+* Format a read outcome as one OpenCode-style line-numbered text block body.
+* @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+* @param outcome - the windowed read to render.
+* @returns the model-facing envelope: numbered lines plus a continuation or end-of-file footer.
+*/
+function formatReadOutput(displayPath, outcome) {
+	const endLine = outcome.lines.at(-1)?.number ?? Math.max(0, outcome.offset - 1);
+	let footer;
+	if (outcome.truncatedByBytes) footer = `(Output capped. Showing lines ${outcome.offset}-${endLine}. Use offset=${endLine + 1} to continue.)`;
+	else if (endLine < outcome.totalLines) footer = `(Showing lines ${outcome.offset}-${endLine} of ${outcome.totalLines}. Use offset=${endLine + 1} to continue.)`;
+	else footer = `(End of file - total ${outcome.totalLines} lines)`;
+	return `<path>${displayPath}</path>
+<type>file</type>
+<content>
+${outcome.lines.length > 0 ? `${outcome.lines.map((line) => `${line.number}: ${line.text}`).join("\n")}\n\n${footer}` : footer}
+</content>`;
+}
+/**
+* Lowercased file-extension to syntax-highlighting language hint. Keys are the
+* extension without its dot; a UI treats an absent key as plain text. The map is
+* intentionally small — common source, config, and markup extensions a
+* line-numbered code view benefits from highlighting — not an exhaustive registry.
+*/
+const LANG_BY_EXTENSION = {
+	ts: "ts",
+	tsx: "tsx",
+	mts: "ts",
+	cts: "ts",
+	js: "js",
+	jsx: "jsx",
+	mjs: "js",
+	cjs: "js",
+	json: "json",
+	jsonc: "json",
+	py: "py",
+	rb: "rb",
+	go: "go",
+	rs: "rs",
+	java: "java",
+	c: "c",
+	h: "c",
+	cc: "cpp",
+	cpp: "cpp",
+	hpp: "cpp",
+	cxx: "cpp",
+	cs: "cs",
+	kt: "kotlin",
+	swift: "swift",
+	php: "php",
+	sh: "sh",
+	bash: "sh",
+	zsh: "sh",
+	yaml: "yaml",
+	yml: "yaml",
+	toml: "toml",
+	ini: "ini",
+	md: "md",
+	markdown: "md",
+	mdx: "mdx",
+	html: "html",
+	htm: "html",
+	css: "css",
+	scss: "scss",
+	less: "less",
+	sql: "sql",
+	xml: "xml",
+	lua: "lua"
+};
+/**
+* Derive a syntax-highlighting language hint from a read path's file extension.
+* Pure and case-insensitive on the extension; a dotfile with no extension
+* (`.gitignore`) and an unknown extension both yield `undefined`.
+* @param path - the model-facing path the read reported.
+* @returns the language hint for {@link LANG_BY_EXTENSION}, or `undefined` when the extension maps to none.
+*/
+function langFromPath(path) {
+	const base = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
+	const dot = base.lastIndexOf(".");
+	if (dot <= 0) return void 0;
+	const ext = base.slice(dot + 1).toLowerCase();
+	return Object.hasOwn(LANG_BY_EXTENSION, ext) ? LANG_BY_EXTENSION[ext] : void 0;
+}
+/**
+* Whether `value` is a valid {@link FileTextLine} (defensive narrowing from
+* opaque `meta`). `number` must be a 1-based integer line number, since a card
+* rendered from a zero, fractional, or non-finite line number would violate the
+* 1-based numbering contract the read window promises.
+*/
+function isFileTextLine(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const { number, text } = value;
+	return typeof number === "number" && Number.isInteger(number) && number >= 1 && typeof text === "string";
+}
+/**
+* Narrow opaque live or replayed result metadata to a structured read window.
+* Malformed metadata returns `undefined` so presentation can fall back to the
+* generic text card instead of throwing during replay. Beyond shape, the
+* semantic contract of a read window is enforced against replayed JSON that is
+* well-typed but out of range: `offset` must be a 1-based integer, `totalLines`
+* must be a non-negative integer, each line number must be a 1-based integer no
+* less than `offset`, the line numbers must strictly increase, and no line number
+* may exceed `totalLines`. Any violation declines to the generic fallback rather
+* than emitting a card that misnumbers or overcounts.
+* @param meta - result metadata.
+* @returns the validated read window, or `undefined` for absent, malformed, or semantically invalid data.
+*/
+function readMetaFromMeta(meta) {
+	if (typeof meta !== "object" || meta === null || Array.isArray(meta)) return void 0;
+	const { path, offset, lines, totalLines, lang } = meta;
+	if (typeof path !== "string" || typeof totalLines !== "number" || typeof offset !== "number") return void 0;
+	if (!Number.isInteger(offset) || offset < 1) return void 0;
+	if (!Number.isInteger(totalLines) || totalLines < 0) return void 0;
+	if (!Array.isArray(lines) || !lines.every(isFileTextLine)) return void 0;
+	if (lang !== void 0 && typeof lang !== "string") return void 0;
+	let previous = offset - 1;
+	for (const { number } of lines) {
+		if (number <= previous || number > totalLines) return void 0;
+		previous = number;
+	}
+	return {
+		path,
+		offset,
+		lines,
+		totalLines,
+		...lang === void 0 ? {} : { lang }
+	};
+}
+//#endregion
+//#region lib/types/session-cwd.js
+/**
+* Derive the working directory a filesystem tool resolves relative paths against: the calling
+* agent's per-session workspace (`exec.agent.session.header.cwd`), so each session's
+* `read`/`write`/`edit` act on ITS workspace, not the server's launch dir — mirroring how
+* `dsh-tool-bash` defaults a bash `workdir` to the session cwd.
+* Non-agent calls return `undefined`, leaving the fallback in the provider rather than reading
+* `process.cwd()` at the tool boundary.
+* @module @deepseek-ai/dsh-tool-fs/session-cwd
+*/
+const PARENT_PATH_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
+/**
+* The session workspace cwd for this call, or `undefined` when none applies.
+* @param exec - the tool-execution context; only its optional `agent` is read.
+* @param requestedPath - the path the provider will resolve; parent traversal
+*   makes a symlinked cwd's filesystem identity observable.
+* @returns the calling agent's session cwd, or undefined for a non-agent caller (the backend then applies its own default).
+*/
+function sessionCwd(exec, requestedPath) {
+	const cwd = exec.agent?.session.header.cwd;
+	if (cwd === void 0 || !PARENT_PATH_SEGMENT.test(cwd) && !PARENT_PATH_SEGMENT.test(requestedPath)) return cwd;
+	return canonicalPath(cwd);
+}
+/**
+* Resolution options shared by all model-facing filesystem tools.
+* @param exec - the tool-execution context supplying session cwd and cancellation.
+* @param requestedPath - the path the provider will resolve.
+* @param policyWorkspaceRoot - resolved per-call root, when a mutation carries sandbox policy.
+* @returns provider resolution options for the current tool call.
+*/
+function sessionResolveOptions(exec, requestedPath, policyWorkspaceRoot) {
+	const cwd = policyWorkspaceRoot ?? sessionCwd(exec, requestedPath);
+	return {
+		...cwd !== void 0 ? { cwd } : {},
+		signal: exec.signal
+	};
+}
+//#endregion
+//#region lib/types/read.js
+/**
+* Model-facing UTF-8 read. It performs one provider stat for type, routing, and observed version,
+* streams large or size-unknown files, renders a bounded window, then emits the observation.
+* @module @deepseek-ai/dsh-tool-fs/src/read
+*/
+/** Default and maximum number of lines returned by one `read` call (the `readLimit` config). */
+const READ_LIMIT = 2e3;
+/**
+* Default streaming threshold (the `readStreamMinSize` config): files at or
+* above this size stream; smaller files read whole into memory.
+*/
+const STREAM_MIN_SIZE = 10 * 1024 * 1024;
+function parsePositiveInteger(value, name) {
+	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) throw new Error(`${name} must be a positive integer`);
+	return value;
+}
+/**
+* Validate value constraints the schema DSL can't express. `maxLimit` is the deployment's line cap.
+* @param args - the schema-validated raw tool arguments; `offset`/`limit` must be positive integers when given.
+* @param maxLimit - the configured line cap: both the default `limit` and the largest one accepted.
+* @returns the validated input with `offset` defaulted to 1 and `limit` to `maxLimit`.
+*/
+function parseReadArgs(args, maxLimit) {
+	if (args.file_path.trim().length === 0) throw new Error("file_path must be a non-empty string");
+	const offset = args.offset === void 0 ? 1 : parsePositiveInteger(args.offset, "offset");
+	const limit = args.limit === void 0 ? maxLimit : parsePositiveInteger(args.limit, "limit");
+	if (limit > maxLimit) throw new Error(`limit must be less than or equal to ${maxLimit}`);
+	return {
+		filePath: args.file_path,
+		offset,
+		limit
+	};
+}
+/**
+* Register the `read` tool and its system-prompt guidance.
+* @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+* @param caps - the deployment's resolved read caps (plugin config after defaulting).
+*/
+function applyReadTool(ctx, caps) {
+	ctx.systemPrompt.section({
+		name: "tool:read",
+		order: 100,
+		text: "Use the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files."
+	});
+	ctx.tools.register(defineTool({
+		name: "read",
+		description: "Read a UTF-8 text file and return line-numbered content.",
+		parameters: {
+			file_path: {
+				type: "string",
+				required: true,
+				description: "Path to read, resolved by the filesystem backend."
+			},
+			offset: {
+				type: "number",
+				description: "1-based first line to return. Defaults to 1."
+			},
+			limit: {
+				type: "number",
+				description: `Maximum number of lines to return. Defaults to ${caps.limit}.`
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					path: {
+						type: "string",
+						required: true
+					},
+					offset: {
+						type: "integer",
+						required: true
+					},
+					lines: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								number: {
+									type: "integer",
+									required: true
+								},
+								text: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					totalLines: {
+						type: "integer",
+						required: true
+					}
+				}
+			},
+			render: (args, value) => {
+				const input = parseReadArgs(args, caps.limit);
+				const endLine = value.lines.at(-1)?.number ?? Math.max(0, value.offset - 1);
+				const truncatedByBytes = value.lines.length < input.limit && endLine < value.totalLines;
+				return [{
+					type: "text",
+					text: formatReadOutput(value.path, {
+						offset: value.offset,
+						lines: value.lines,
+						totalLines: value.totalLines,
+						...truncatedByBytes ? { truncatedByBytes: true } : {}
+					})
+				}];
+			},
+			presentationMeta: (_args, value) => {
+				const lang = langFromPath(value.path);
+				return {
+					path: value.path,
+					offset: value.offset,
+					lines: value.lines.map(({ number, text }) => ({
+						number,
+						text
+					})),
+					totalLines: value.totalLines,
+					...lang === void 0 ? {} : { lang }
+				};
+			}
+		},
+		isConcurrencySafe: () => true,
+		async execute(args, exec) {
+			const input = parseReadArgs(args, caps.limit);
+			const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath));
+			const info = await ctx.fs.stat(target, exec.signal);
+			if (!info) {
+				ctx.emit("fs/observed", target, { kind: "absent" }, exec);
+				throw new FsError(`cannot read "${target.displayPath}": not found`, "FS_NOT_FOUND");
+			}
+			if (info.type !== "file") throw new FsError(`cannot read "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
+			const window = await buildWindow(info.size === void 0 || info.size >= caps.streamMinSize ? await ctx.fs.streamText(target, exec.signal) : [await ctx.fs.readText(target, exec.signal)], {
+				offset: input.offset,
+				limit: input.limit,
+				maxLineLength: caps.maxLineLength,
+				maxBytes: caps.maxBytes
+			}, target.displayPath);
+			const outcome = {
+				path: target.displayPath,
+				offset: input.offset,
+				lines: window.lines,
+				totalLines: window.totalLines
+			};
+			ctx.emit("fs/observed", target, {
+				kind: "present",
+				version: info.version
+			}, exec);
+			return outcome;
+		},
+		presentResult(_args, result) {
+			if (result.isError) return void 0;
+			const meta = readMetaFromMeta(result.meta);
+			if (meta === void 0) return void 0;
+			const only = result.content.length === 1 ? result.content[0] : void 0;
+			const text = only?.type === "text" ? only.text : void 0;
+			if (text === void 0) return void 0;
+			const body = /^<path>[^\n]*<\/path>\n<type>file<\/type>\n<content>\n([\s\S]*)\n<\/content>$/u.exec(text)?.[1];
+			if (body === void 0) return void 0;
+			return {
+				card: "read",
+				path: meta.path,
+				offset: meta.offset,
+				lines: meta.lines,
+				totalLines: meta.totalLines,
+				...meta.lang === void 0 ? {} : { lang: meta.lang },
+				content: [{
+					type: "text",
+					text: body
+				}]
+			};
+		},
+		presentCall(args) {
+			const { offset, limit } = args;
+			const window = limit !== void 0 && limit > 0 ? ` (${offset ?? 1} - ${(offset ?? 1) + limit - 1})` : offset !== void 0 ? ` (from line ${offset})` : "";
+			return {
+				card: "generic",
+				title: `Read ${args.file_path}${window}`,
+				kind: "read",
+				locations: [{
+					path: args.file_path,
+					line: offset ?? 1
+				}]
+			};
+		}
+	}));
+}
+/**
+* Compute one {@link FileDiff} per hunk between `before` and `after`, each carrying the
+* applied change plus {@link DIFF_CONTEXT} context lines. Pure insertions use `oldText: null`,
+* patch-only no-newline markers are omitted, and scattered replacements remain separate hunks.
+*
+* @param path - the path stamped on every produced diff (the model-facing `file_path`; the
+*   bridge relativizes it).
+* @param before - the file text before the change (the backend's LF-normalized diff basis).
+* @param after - the file text after the change, on the same basis.
+* @returns one diff per applied hunk, in file order; empty when the texts are identical.
+*/
+function computeHunkDiffs(path, before, after) {
+	const patch = structuredPatch("", "", before, after, void 0, void 0, { context: 3 });
+	const diffs = [];
+	for (const hunk of patch.hunks) {
+		const oldLines = [];
+		const newLines = [];
+		for (const line of hunk.lines) {
+			if (line.startsWith("\\")) continue;
+			const text = line.slice(1);
+			if (line.startsWith("-")) oldLines.push(text);
+			else if (line.startsWith("+")) newLines.push(text);
+			else {
+				oldLines.push(text);
+				newLines.push(text);
+			}
+		}
+		diffs.push({
+			path,
+			oldText: oldLines.length > 0 ? oldLines.join("\n") : null,
+			newText: newLines.join("\n")
+		});
+	}
+	return diffs;
+}
+/** Whether `value` is a valid {@link FileDiff} (defensive narrowing from opaque `meta`). */
+function isFileDiff(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const { path, oldText, newText } = value;
+	return typeof path === "string" && (oldText === null || typeof oldText === "string") && typeof newText === "string";
+}
+/**
+* Narrow opaque live or replayed result metadata to non-empty file diffs. Malformed metadata
+* returns `undefined` so presentation can fall back instead of throwing during replay.
+* @param meta - result metadata.
+* @returns validated hunks, or `undefined` for absent or malformed data.
+*/
+function diffsFromMeta(meta) {
+	if (typeof meta !== "object" || meta === null || Array.isArray(meta)) return void 0;
+	const diffs = meta.diffs;
+	if (!Array.isArray(diffs) || diffs.length === 0 || !diffs.every(isFileDiff)) return void 0;
+	return diffs;
+}
+//#endregion
+//#region lib/types/error.js
+/**
+* Model-facing remediation for guarded-mutation failures. The provider's
+* `FS_STALE_VERSION` and `FS_NOT_OBSERVED` messages state the condition but
+* not the only correct recovery (re-read / read the file), so this package
+* appends the remedy at the model boundary; provider messages stay
+* machine-oriented and unchanged.
+* @module @deepseek-ai/dsh-tool-fs/src/error
+*/
+/** The remedy appended to each remediable failure code's message. */
+const REMEDIES = {
+	FS_STALE_VERSION: "re-read the file, then retry",
+	FS_NOT_OBSERVED: "read the file, then retry"
+};
+/**
+* Append the correct recovery instruction to a guarded-mutation failure's
+* message. `FS_STALE_VERSION` (the file changed since this session's last
+* observation, including a missing target) recovers only by re-reading;
+* `FS_NOT_OBSERVED` (no prior read by this session) by reading. The `FsError`
+* code is preserved so retry/permission/UI layers keep routing on it, and the
+* original error chains as `cause`. Anything else passes through untouched.
+* @param error - the caught value from a write/edit execution.
+* @returns a remediated `FsError` for the two guarded-mutation codes, else the original value.
+*/
+function remediateFsError(error) {
+	if (!(error instanceof FsError)) return error;
+	const remedy = REMEDIES[error.code];
+	if (!remedy) return error;
+	return new FsError(`${error.message} — ${remedy}`, error.code, { cause: error });
+}
+//#endregion
+//#region lib/types/write.js
+/**
+* Model-facing full-file write. It obtains an optional intent from the single policy slot, calls
+* `ctx.fs.writeText` without a stat, then records the resulting version; no policy means an
+* unconditional atomic create-or-overwrite.
+* @module @deepseek-ai/dsh-tool-fs/src/write
+*/
+/**
+* Validate value constraints the schema DSL can't express: only a non-blank
+* `file_path` — an empty `content` is legitimate (it writes an empty file).
+* @param args - the schema-validated raw tool arguments.
+* @returns the camelCased input; `content` passes through untouched.
+*/
+function parseWriteArgs(args) {
+	if (args.file_path.trim().length === 0) throw new Error("file_path must be a non-empty string");
+	return {
+		filePath: args.file_path,
+		content: args.content
+	};
+}
+/**
+* Format a write outcome as one model-facing text block body.
+* @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+* @param outcome - the write outcome; its `operation` selects the Created/Updated wording.
+* @returns the model-facing confirmation envelope (no file content is echoed back).
+*/
+function formatWriteOutput(displayPath, outcome) {
+	return `<path>${displayPath}</path>
+<type>file</type>
+<content>
+${outcome.operation === "create" ? "Created" : "Updated"} file
+</content>`;
+}
+/**
+* Register the `write` tool and its system-prompt guidance.
+* @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+* @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
+*/
+function applyWriteTool(ctx, sandbox) {
+	ctx.systemPrompt.section({
+		name: "tool:write",
+		order: 101,
+		text: "Use the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes."
+	});
+	ctx.tools.register(defineTool({
+		name: "write",
+		description: "Create or fully replace a UTF-8 text file.",
+		parameters: {
+			file_path: {
+				type: "string",
+				required: true,
+				description: "Path to write, resolved by the filesystem backend."
+			},
+			content: {
+				type: "string",
+				required: true,
+				description: "Full UTF-8 text content to write."
+			},
+			...sandbox.escalationModes.length > 0 ? sandbox.schemaFields() : {}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					path: {
+						type: "string",
+						required: true
+					},
+					operation: {
+						type: "string",
+						required: true,
+						enum: ["create", "update"]
+					},
+					before: {
+						required: true,
+						oneOf: [{ type: "string" }, { type: "null" }]
+					},
+					after: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: formatWriteOutput(value.path, value)
+			}],
+			presentationMeta: (args, value) => ({ diffs: value.before === null ? [] : computeHunkDiffs(args.file_path, value.before, value.after).map(({ path, oldText, newText }) => ({
+				path,
+				oldText,
+				newText
+			})) })
+		},
+		async execute(args, exec) {
+			const input = parseWriteArgs(args);
+			const sandboxPolicy = await sandbox.resolvePolicy("write", args, exec);
+			const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot));
+			const intent = await ctx.waterfall("fs/write-intent", target, exec, () => void 0);
+			let outcome;
+			try {
+				outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal, sandboxPolicy);
+			} catch (error) {
+				throw remediateFsError(sandbox.mapError(error, sandboxPolicy));
+			}
+			ctx.emit("fs/observed", target, {
+				kind: "present",
+				version: outcome.version
+			}, exec);
+			return {
+				path: target.displayPath,
+				operation: outcome.operation,
+				before: outcome.before,
+				after: outcome.after
+			};
+		},
+		presentCall(args) {
+			return {
+				card: "diff",
+				title: `Write ${args.file_path}`,
+				diffs: [{
+					path: args.file_path,
+					oldText: null,
+					newText: args.content
+				}],
+				locations: [{ path: args.file_path }]
+			};
+		},
+		presentResult(args, result) {
+			if (result.isError) return void 0;
+			const diffs = diffsFromMeta(result.meta) ?? [{
+				path: args.file_path,
+				oldText: null,
+				newText: args.content
+			}];
+			return {
+				card: "diff",
+				title: `Write ${args.file_path}`,
+				diffs
+			};
+		}
+	}));
+}
+//#endregion
+//#region lib/types/edit.js
+/**
+* Model-facing literal edit, unique-match by default. It obtains an optional guard from the
+* single intent slot, calls `ctx.fs.editText` without a separate stat, then records the observed
+* version; no policy means an unconditional atomic edit.
+* @module @deepseek-ai/dsh-tool-fs/src/edit
+*/
+/**
+* Validate value constraints the schema DSL can't express: a non-blank
+* `file_path`, a non-empty `old_string`, and `old_string !== new_string`
+* (an equal pair would be a guaranteed no-op edit).
+* @param args - the schema-validated raw tool arguments.
+* @returns the camelCased input with `replace_all` defaulted to false.
+*/
+function parseEditArgs(args) {
+	if (args.file_path.trim().length === 0) throw new Error("file_path must be a non-empty string");
+	if (args.old_string.length === 0) throw new Error("old_string must be a non-empty string");
+	if (args.old_string === args.new_string) throw new Error("old_string and new_string must differ");
+	return {
+		filePath: args.file_path,
+		oldString: args.old_string,
+		newString: args.new_string,
+		replaceAll: args.replace_all ?? false
+	};
+}
+/**
+* Format an edit success (single-match or replace-all) as a Claude-style model-facing message.
+* @param displayPath - the backend-resolved path shown to the model.
+* @param replaceAll - selects the all-occurrences wording over the single-replacement one.
+* @returns the confirmation sentence the model sees as the tool result.
+*/
+function formatEditOutput(displayPath, replaceAll) {
+	return replaceAll ? `The file ${displayPath} has been updated. All occurrences were successfully replaced.` : `The file ${displayPath} has been updated successfully.`;
+}
+/**
+* Register the `edit` tool and its system-prompt guidance.
+* @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+* @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
+*/
+function applyEditTool(ctx, sandbox) {
+	ctx.systemPrompt.section({
+		name: "tool:edit",
+		order: 102,
+		text: "Use the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session."
+	});
+	ctx.tools.register(defineTool({
+		name: "edit",
+		description: "Edit an existing UTF-8 text file by replacing literal text.",
+		parameters: {
+			file_path: {
+				type: "string",
+				required: true,
+				description: "Path to edit, resolved by the filesystem backend."
+			},
+			old_string: {
+				type: "string",
+				required: true,
+				description: "Literal text to replace. Must match exactly."
+			},
+			new_string: {
+				type: "string",
+				required: true,
+				description: "Literal replacement text. Use an empty string to delete the match."
+			},
+			replace_all: {
+				type: "boolean",
+				description: "Replace all matches. Defaults to false; when false, old_string must appear exactly once."
+			},
+			...sandbox.escalationModes.length > 0 ? sandbox.schemaFields() : {}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					path: {
+						type: "string",
+						required: true
+					},
+					before: {
+						type: "string",
+						required: true
+					},
+					after: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (args, value) => [{
+				type: "text",
+				text: formatEditOutput(value.path, args.replace_all ?? false)
+			}],
+			presentationMeta: (args, value) => ({ diffs: computeHunkDiffs(args.file_path, value.before, value.after).map(({ path, oldText, newText }) => ({
+				path,
+				oldText,
+				newText
+			})) })
+		},
+		async execute(args, exec) {
+			const input = parseEditArgs(args);
+			const sandboxPolicy = await sandbox.resolvePolicy("edit", args, exec);
+			const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot));
+			let outcome;
+			try {
+				const intent = await ctx.waterfall("fs/edit-intent", target, exec, () => void 0);
+				outcome = await ctx.fs.editText(target, {
+					oldString: input.oldString,
+					newString: input.newString,
+					replaceAll: input.replaceAll
+				}, intent, exec.signal, sandboxPolicy);
+			} catch (error) {
+				throw remediateFsError(sandbox.mapError(error, sandboxPolicy));
+			}
+			ctx.emit("fs/observed", target, {
+				kind: "present",
+				version: outcome.version
+			}, exec);
+			return {
+				path: target.displayPath,
+				before: outcome.before,
+				after: outcome.after
+			};
+		},
+		presentCall(args) {
+			return {
+				card: "diff",
+				title: `Edit ${args.file_path}`,
+				diffs: [{
+					path: args.file_path,
+					oldText: args.old_string || null,
+					newText: args.new_string
+				}],
+				locations: [{ path: args.file_path }]
+			};
+		},
+		presentResult(args, result) {
+			if (result.isError) return void 0;
+			const diffs = diffsFromMeta(result.meta);
+			if (diffs === void 0) return void 0;
+			return {
+				card: "diff",
+				title: `Edit ${args.file_path}`,
+				diffs
+			};
+		}
+	}));
+}
+//#endregion
+//#region lib/types/sandbox.js
+/**
+* The sandbox-escalation surface shared by the `write` and `edit` tools: the
+* per-call policy resolution, the advertised escalation fields, and the denial-marker
+* mapping — all delegating the vocabulary and the fail-closed approval
+* sequence to `@deepseek-ai/dsh-sandbox` (the same pieces `@deepseek-ai/dsh-tool-bash`
+* uses), so bash and fs escalate identically. Built ONCE per plugin from
+* `ctx.fs.sandboxMode` (the capability fact — is a confining backend mounted?)
+* and shared by both mutating tools.
+*
+* @module @deepseek-ai/dsh-tool-fs/sandbox
+*/
+/**
+* The filesystem escalation surface: advertisement gating, per-call policy
+* resolution, the one-approved wider retry, and denial-marker mapping. A pure
+* product of `ctx` at plugin apply time.
+*/
+var FsSandboxSurface = class {
+	ctx;
+	/** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
+	escalationModes;
+	/** Shared per-session policy resolver, required by a confining backend. */
+	policy;
+	constructor(ctx) {
+		this.ctx = ctx;
+		const defaultMode = ctx.fs.sandboxMode;
+		this.escalationModes = defaultMode === void 0 ? [] : ESCALATION_TARGETS;
+		this.policy = defaultMode === void 0 ? void 0 : ctx.get("sandboxPolicy");
+		if (defaultMode !== void 0 && this.policy === void 0) throw new Error("tool-fs: the mounted filesystem confines but ctx.sandboxPolicy is missing");
+	}
+	/**
+	* The escalation schema fields for a mutating tool's `parameters`. Call it
+	* only under a confining backend (guard on {@link escalationModes}); the
+	* enum pins the closed target vocabulary, the strict-wider check happens per
+	* call at execution.
+	* @returns the two escalation parameter specs.
+	*/
+	schemaFields() {
+		return {
+			sandbox_permissions: {
+				type: "string",
+				enum: [...this.escalationModes],
+				description: "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval."
+			},
+			justification: {
+				type: "string",
+				description: "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access."
+			}
+		};
+	}
+	/**
+	* The policy to stamp onto this mutation: an approved escalation grant (a
+	* strictly wider retry resolved through `ctx.approval` before anything
+	* executes), else the session's standing mode. The calling session's cwd is
+	* always carried as the workspace root. Validates the escalation argument
+	* pairing first.
+	* @param toolName - the mutating tool's name, for the approval audit trail.
+	* @param args - the call's escalation arguments.
+	* @param exec - the tool-execution context (agent, callId, signal).
+	* @returns the policy to pass to the mutation, or undefined for an
+	*   unsandboxed backend.
+	*/
+	async resolvePolicy(toolName, args, exec) {
+		validateEscalationArgs(args.sandbox_permissions, args.justification);
+		const standingPolicy = this.policy?.resolve({ ...exec.agent ? { session: exec.agent.session } : {} });
+		if (args.sandbox_permissions === void 0 || args.justification === void 0) return standingPolicy;
+		if (this.escalationModes.length === 0) throw new Error("sandbox_permissions is not available in this composition (no sandboxing filesystem to escalate)");
+		const policy = standingPolicy;
+		const approvedMode = await approveEscalation({
+			requestedMode: args.sandbox_permissions,
+			justification: args.justification,
+			effectiveMode: policy.mode,
+			subject: "operation"
+		}, {
+			approver: this.ctx.get("approval"),
+			agent: exec.agent,
+			callId: exec.callId,
+			toolName,
+			signal: exec.signal
+		});
+		return {
+			...policy,
+			mode: approvedMode
+		};
+	}
+	/**
+	* Map a thrown provider error for the model: a `FS_SANDBOX_DENIED` becomes a
+	* `FsError` whose text is the shared `[sandbox: …]` denial marker plus the
+	* same-turn escalation hint, so a policy denial reads identically to bash's
+	* WHILE keeping the structured `FS_SANDBOX_DENIED` code — `ToolRegistry`
+	* populates `result.error` only for `HarnessError` instances, so a plain
+	* `Error` would strip the code retry/observers key off. Any other error
+	* passes through unchanged. A `FS_SANDBOX_DENIED` only arises under a
+	* confining backend, which always advertises the escalation fields, so the
+	* hint always applies here.
+	* @param error - the error thrown by the mutation.
+	* @param policy - the policy stamped onto the call (names the mode in the marker).
+	* @returns the error to throw — the marker `FsError` for a sandbox denial, else the original.
+	*/
+	mapError(error, policy) {
+		if (!(error instanceof FsError) || error.code !== "FS_SANDBOX_DENIED") return error;
+		const mode = policy.mode;
+		return new FsError(`${sandboxDenialMarker(mode)}\n${escalationHintMarker("operation")}`, "FS_SANDBOX_DENIED", { cause: error });
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Model-facing read, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
+* read windows, formatting, and observation events, never a concrete provider. An optional
+* event policy supplies mutation guards; without one the tools use unconditional provider calls.
+* @module @deepseek-ai/dsh-tool-fs
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "tool-fs";
+/** Services required by the filesystem tool suite. */
+const inject = [
+	"tools",
+	"fs",
+	"systemPrompt"
+];
+const Config = z.object({
+	readLimit: z.number().default(READ_LIMIT),
+	readMaxLineLength: z.number().default(READ_MAX_LINE_LENGTH),
+	readMaxBytes: z.number().default(READ_MAX_BYTES),
+	readStreamMinSize: z.number().default(STREAM_MIN_SIZE)
+});
+/** Every read cap counts lines/chars/bytes — a positive integer, or windowing arithmetic misbehaves silently. */
+function assertPositiveInteger(name, value) {
+	if (!Number.isInteger(value) || value < 1) throw new Error(`tool-fs: ${name} must be a positive integer`);
+}
+/** Register the full `read`/`write`/`edit` filesystem tool suite. */
+function apply(ctx, config) {
+	const resolved = config;
+	assertPositiveInteger("readLimit", resolved.readLimit);
+	assertPositiveInteger("readMaxLineLength", resolved.readMaxLineLength);
+	assertPositiveInteger("readMaxBytes", resolved.readMaxBytes);
+	assertPositiveInteger("readStreamMinSize", resolved.readStreamMinSize);
+	applyReadTool(ctx, {
+		limit: resolved.readLimit,
+		maxLineLength: resolved.readMaxLineLength,
+		maxBytes: resolved.readMaxBytes,
+		streamMinSize: resolved.readStreamMinSize
+	});
+	const sandbox = new FsSandboxSurface(ctx);
+	applyWriteTool(ctx, sandbox);
+	applyEditTool(ctx, sandbox);
+}
+//#endregion
+export { Config, apply, inject, name };