@swoop111/dsh-tool-fs 0.0.0-stage → 0.2.0-rc.2

package/lib/index.js

@@ -0,0 +1,1838 @@
+import z from "@deepseek-ai/schemastery";
+import { DEFAULT_MAX_FILE_CHARS, DEFAULT_MAX_WINDOW_LINES, createDisclosureLedger, createReadWindowProjection, createSessionPathProjection, repairMissingPath, repairStrReplace } from "@deepseek-ai/dsh-fs-edit-repair";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { repairReadArgs } from "@deepseek-ai/dsh-arg-repair";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { readLangHintForPath as langFromPath } from "@deepseek-ai/dsh-util-code-language";
+import { structuredPatch } from "diff";
+import { basename, extname } from "node:path";
+import { AttachmentError, AttachmentId } from "@deepseek-ai/dsh-attachment";
+import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
+//#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
+	};
+}
+const OFFSET_OUT_OF_RANGE_RE = /^offset (-?\d+) is out of range for "(?:[^"\\]|\\"|\\\\)*" \((\d+) lines\)$/u;
+/**
+* Recognize this package's own offset-out-of-range `FsError` and return its scan
+* facts, so the read tool can tail-anchor the window instead of erroring. The
+* message and this parser live in the same module on purpose: the format is a
+* package-internal contract, pinned by tests on both sides.
+* @param error - the caught value from {@link buildWindow}.
+* @returns the requested offset and observed line count, or `undefined` for any other failure.
+*/
+function parseOffsetOutOfRange(error) {
+	if (!(error instanceof FsError) || error.code !== "FS_NOT_FOUND") return void 0;
+	const match = error.message.match(OFFSET_OUT_OF_RANGE_RE);
+	if (match === null) return void 0;
+	const requestedOffset = Number(match[1]);
+	const totalLines = Number(match[2]);
+	return Number.isSafeInteger(requestedOffset) && Number.isSafeInteger(totalLines) ? {
+		requestedOffset,
+		totalLines
+	} : void 0;
+}
+/**
+* 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, a continuation or end-of-file footer, and the repair disclosure when one fired.
+*/
+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}${outcome.repairNote === void 0 ? "" : `\n(repair: ${outcome.repairNote})`}
+</content>`;
+}
+/**
+* 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 directory.
+* 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
+*/
+/**
+* The session workspace cwd for this call, or `undefined` when none applies.
+* @param exec - the tool-execution context; only its optional `agent` is read.
+* @returns the calling agent's session cwd, or undefined for a non-agent caller (the backend then applies its own default).
+*/
+function sessionCwd(exec) {
+	return exec.agent?.session.header.cwd;
+}
+/**
+* Resolution options shared by all model-facing filesystem tools.
+* @param exec - the tool-execution context supplying session cwd and cancellation.
+* @param policyWorkspaceRoot - resolved per-call root, when a mutation carries sandbox policy.
+* @returns provider resolution options for the current tool call.
+*/
+function sessionResolveOptions(exec, policyWorkspaceRoot) {
+	const cwd = policyWorkspaceRoot ?? sessionCwd(exec);
+	return {
+		...cwd !== void 0 ? { cwd } : {},
+		signal: exec.signal
+	};
+}
+//#endregion
+//#region lib/types/read-target.js
+/**
+* Shared path resolution and regular-file validation for model-facing read tools.
+* @module @deepseek-ai/dsh-tool-fs/src/read-target
+*/
+/**
+* Resolve a model-supplied path, observe absence, and require a regular file.
+* @param ctx - the plugin context providing filesystem resolution and observation events.
+* @param exec - the current tool execution, including session cwd and cancellation.
+* @param requestedPath - the raw path supplied to the tool.
+* @returns the resolved target and its single stat result.
+*/
+async function resolveRegularReadTarget(ctx, exec, requestedPath) {
+	const target = await ctx.fs.resolve(requestedPath, sessionResolveOptions(exec));
+	const info = await ctx.fs.stat(target, exec.signal);
+	if (info === void 0) {
+		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");
+	return {
+		target,
+		info
+	};
+}
+/**
+* Attempt the engine's missing-path composition for a failed tool target: a
+* unique match among the session's prior successful path arguments, then a
+* unique directory-tree completion, each proven present before adoption. A
+* tool never re-anchors on ambiguity, so a wrong guess cannot replace a real
+* answer — the caller keeps its verbatim error when this returns `undefined`.
+* @param ctx - the plugin context providing filesystem resolution and listing.
+* @param exec - the current tool execution, including session cwd and cancellation.
+* @param requestedPath - the raw path the model supplied.
+* @param knownPaths - the session's prior successful path arguments, most recent first.
+* @returns the verified replacement path with its disclosure, or `undefined`.
+*/
+async function repairTargetPath(ctx, exec, requestedPath, knownPaths) {
+	const cwd = sessionCwd(exec);
+	return await repairMissingPath(requestedPath, {
+		knownPaths,
+		explorer: fsPathExplorer(ctx, exec.signal),
+		...cwd === void 0 ? {} : { root: cwd },
+		verify: async (candidate) => {
+			const target = await ctx.fs.resolve(candidate, sessionResolveOptions(exec));
+			return await ctx.fs.stat(target, exec.signal) !== void 0;
+		}
+	});
+}
+/** The filesystem itself as the engine's read-only probe: entry names, undefined when unreadable. */
+function fsPathExplorer(ctx, signal) {
+	return { listDir: async (directory) => {
+		const target = await ctx.fs.resolve(directory, { signal }).catch(() => void 0);
+		if (target === void 0) return void 0;
+		return await ctx.fs.listDir(target, signal).then((entries) => entries.map((entry) => entry.name)).catch(() => void 0);
+	} };
+}
+//#endregion
+//#region lib/types/structure.js
+/**
+* Structural analysis of file text for read-window completion: markdown
+* fences, bracket nesting, and indentation blocks. The analyzers are pure
+* functions over already-delivered text; they decide which construct a window
+* boundary falls inside, and how many neighbouring lines close an open one.
+*
+* Precision is traded for never touching delivered content: a wrong verdict
+* only costs a few appended real lines, or a silent non-completion. String
+* literals are scanned per line (an unterminated quote never carries into the
+* next line), line comments and C-style block comments are skipped, and
+* brackets inside an open fence are content, so prose and code samples do not
+* fabricate unbalanced constructs.
+* @module @deepseek-ai/dsh-tool-fs/structure
+*/
+/** The fence marker of one line, or `undefined` when the line is not a fence. */
+function fenceLine(line) {
+	const rest = line.slice(line.length - line.trimStart().length);
+	if (line.length - rest.length > 3) return void 0;
+	const char = rest.charAt(0);
+	if (char !== "`" && char !== "~") return void 0;
+	let length = 0;
+	while (rest.charAt(length) === char) length += 1;
+	if (length < 3) return void 0;
+	const info = rest.slice(length);
+	if (char === "`" && info.includes("`")) return void 0;
+	return {
+		marker: rest.slice(0, length),
+		info
+	};
+}
+/** Whether one line closes an open fence: same family, at least as long, no info string. */
+function closesFence(marker, line) {
+	const candidate = fenceLine(line);
+	return candidate !== void 0 && candidate.marker.slice(0, 1) === marker.slice(0, 1) && candidate.marker.length >= marker.length && candidate.info.trim().length === 0;
+}
+/** Code brackets of one line: string literals and comments are skipped. */
+function codeBrackets(line, state) {
+	const found = [];
+	let quote;
+	let i = 0;
+	while (i < line.length) {
+		const ch = line.charAt(i);
+		if (state.inBlockComment) {
+			if (ch === "*" && line.charAt(i + 1) === "/") {
+				state.inBlockComment = false;
+				i += 2;
+				continue;
+			}
+			i += 1;
+			continue;
+		}
+		if (quote !== void 0) {
+			if (ch === "\\") {
+				i += 2;
+				continue;
+			}
+			if (ch === quote) quote = void 0;
+			i += 1;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			quote = ch;
+			i += 1;
+			continue;
+		}
+		if (ch === "/" && line.charAt(i + 1) === "/") break;
+		if (ch === "/" && line.charAt(i + 1) === "*") {
+			state.inBlockComment = true;
+			i += 2;
+			continue;
+		}
+		if (ch === "(" || ch === "[" || ch === "{" || ch === ")" || ch === "]" || ch === "}") found.push(ch);
+		i += 1;
+	}
+	return found;
+}
+/** Whether one bracket character opens a level. */
+function isOpener(ch) {
+	return ch === "(" || ch === "[" || ch === "{";
+}
+/**
+* Scan a line sequence for the constructs it leaves open.
+* @param lines - the lines to scan, in file order.
+* @returns the open fence and the opening lines of every still-open bracket level.
+*/
+function scan(lines) {
+	const state = { inBlockComment: false };
+	const openBracketLines = [];
+	let fence;
+	for (const [index, line] of lines.entries()) {
+		if (fence !== void 0) {
+			if (closesFence(fence.marker, line)) fence = void 0;
+			continue;
+		}
+		const candidate = fenceLine(line);
+		if (candidate !== void 0) {
+			fence = {
+				marker: candidate.marker,
+				lineIndex: index
+			};
+			continue;
+		}
+		for (const ch of codeBrackets(line, state)) if (isOpener(ch)) openBracketLines.push(index);
+		else openBracketLines.pop();
+	}
+	return fence === void 0 ? { openBracketLines } : {
+		fence,
+		openBracketLines
+	};
+}
+/**
+* The indentation block a line sequence ends inside: its last non-blank line is
+* indented deeper than the nearest preceding shallower line, so a Python-style
+* block may still be open.
+* @param lines - the lines to analyze, in file order.
+* @returns the open indented block, or `undefined` when the tail is balanced.
+*/
+function detectOpenIndent(lines) {
+	const lastLine = lines.findLast((line) => line.trim().length > 0);
+	if (lastLine === void 0) return void 0;
+	const width = indentWidth(lastLine);
+	if (width === 0) return void 0;
+	const lastContent = lines.findLastIndex((line) => line.trim().length > 0);
+	for (const [offset, line] of lines.slice(0, lastContent).toReversed().entries()) {
+		if (line.trim().length === 0) continue;
+		const prior = indentWidth(line);
+		if (prior < width) return {
+			kind: "indent",
+			width,
+			lineIndex: lastContent - 1 - offset
+		};
+		if (prior === width) return void 0;
+	}
+	return {
+		kind: "indent",
+		width,
+		lineIndex: 0
+	};
+}
+/**
+* The construct a window ends inside.
+* @param lines - the delivered window lines, in file order.
+* @returns the construct to close, or `undefined` when the tail is balanced.
+*/
+function detectOpenTail(lines) {
+	const facts = scan(lines);
+	if (facts.fence !== void 0) return {
+		kind: "fence",
+		marker: facts.fence.marker,
+		lineIndex: facts.fence.lineIndex
+	};
+	const innermost = facts.openBracketLines.at(-1);
+	if (innermost !== void 0) return {
+		kind: "brace",
+		depth: facts.openBracketLines.length,
+		lineIndex: innermost
+	};
+	return detectOpenIndent(lines);
+}
+/**
+* The indentation block a window starts inside: the window's first non-blank
+* line is indented, and some earlier line is shallower, so the block header
+* lies above the window.
+* @param window - the delivered window lines, in file order.
+* @param preceding - the lines immediately before the window, in file order.
+* @returns the open indented block, or `undefined` when the window starts at a block boundary.
+*/
+function detectOpenIndentHead(window, preceding) {
+	const firstContent = window.find((line) => line.trim().length > 0);
+	if (firstContent === void 0) return void 0;
+	const width = indentWidth(firstContent);
+	if (width === 0) return void 0;
+	for (const [offset, line] of preceding.toReversed().entries()) {
+		if (line.trim().length === 0) continue;
+		if (indentWidth(line) < width) return {
+			kind: "indent",
+			startIndex: preceding.length - 1 - offset
+		};
+	}
+}
+/**
+* The construct a window starts inside, resolved from the lines that precede it.
+* A fence outranks a bracket block, which outranks an indented block. A
+* construct opened before the supplied preceding lines is not provable and
+* reports nothing, so the completion stays silent rather than guessing.
+* @param window - the delivered window lines, in file order.
+* @param preceding - the lines immediately before the window, in file order; the last entry is the line that precedes the window.
+* @returns the leading context, or `undefined` when the window starts at a construct boundary.
+*/
+function detectOpenHead(window, preceding) {
+	if (preceding.length === 0) return void 0;
+	const facts = scan(preceding);
+	if (facts.fence !== void 0) return {
+		kind: "fence",
+		startIndex: facts.fence.lineIndex
+	};
+	const outer = facts.openBracketLines[0];
+	if (outer !== void 0) return {
+		kind: "brace",
+		startIndex: outer
+	};
+	return detectOpenIndentHead(window, preceding);
+}
+/**
+* How many of the following lines close an open construct.
+* @param construct - the construct {@link detectOpenTail} found.
+* @param appended - the lines following the window, in file order.
+* @returns the count of lines to append, or `0` when the sequence closes nothing.
+*/
+function closureLength(construct, appended) {
+	if (construct.kind === "fence") {
+		for (const [index, line] of appended.entries()) if (closesFence(construct.marker, line)) return index + 1;
+		return 0;
+	}
+	if (construct.kind === "brace") {
+		const state = { inBlockComment: false };
+		let depth = construct.depth;
+		for (const [index, line] of appended.entries()) {
+			for (const ch of codeBrackets(line, state)) depth += isOpener(ch) ? 1 : -1;
+			if (depth <= 0) return index + 1;
+		}
+		return 0;
+	}
+	let cut = -1;
+	for (const [index, line] of appended.entries()) {
+		if (line.trim().length === 0) continue;
+		if (indentWidth(line) < construct.width) break;
+		cut = index;
+	}
+	return cut + 1;
+}
+/** Leading indentation width of one line, counting a tab as four columns. */
+function indentWidth(line) {
+	let width = 0;
+	for (const ch of line) if (ch === " ") width += 1;
+	else if (ch === "	") width += 4;
+	else break;
+	return width;
+}
+//#endregion
+//#region lib/types/completion.js
+/**
+* Window completion for reads: the neighbouring lines that give a delivered
+* window its structural boundaries. The head is the single line that opened
+* the construct the window starts inside; the tail is the run of following
+* lines that closes the construct the window ends inside. Neither ever
+* modifies, reorders, or drops a delivered line — a window either gains
+* context or stays exactly as the caller asked for it.
+*
+* The head is one line because everything between that opening line and the
+* window is the content the caller chose to skip; the tail is a run because
+* the construct cannot be called closed until its closer arrives.
+* @module @deepseek-ai/dsh-tool-fs/completion
+*/
+/**
+* Complete a window's structural boundaries.
+* @param lines - the delivered window lines, in file order.
+* @param supply - the line sources on each side of the window.
+* @param tuning - the hard caps for the added lines.
+* @returns the head and tail lines with the rules that produced them; `undefined` when neither side completes.
+*/
+async function completeWindow(lines, supply, tuning) {
+	if (lines.length === 0) return void 0;
+	let head = [];
+	let headRule;
+	const preceding = await supply.preceding(tuning.maxLines);
+	if (preceding !== void 0 && preceding.length > 0) {
+		const context = detectOpenHead(lines.map((line) => line.text), preceding.map((line) => line.text));
+		const opening = context === void 0 ? void 0 : preceding[context.startIndex];
+		if (context !== void 0 && opening !== void 0) {
+			head = [opening];
+			headRule = context.kind;
+		}
+	}
+	let tail = [];
+	let tailRule;
+	const construct = detectOpenTail([...head, ...lines].map((line) => line.text));
+	if (construct !== void 0) {
+		const following = await supply.following(tuning.maxLines);
+		if (following !== void 0) {
+			const closing = closureLength(construct, following.map((line) => line.text));
+			if (closing > 0) {
+				tail = following.slice(0, closing);
+				tailRule = construct.kind;
+			}
+		}
+	}
+	if (headRule === void 0 && tailRule === void 0) return void 0;
+	return {
+		head,
+		tail,
+		...headRule === void 0 ? {} : { headRule },
+		...tailRule === void 0 ? {} : { tailRule }
+	};
+}
+//#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.
+* With repair enabled, the measured addressing failures are normalized first through
+* {@link repairReadArgs}: a 0-based or negative start index and an over-cap or
+* non-positive limit all carry unambiguous intent, so the value is substituted
+* and the rule reported instead of erroring.
+* @param args - the schema-validated raw tool arguments; `offset`/`limit` must be positive integers when given unrepairable shapes.
+* @param maxLimit - the configured line cap: both the default `limit` and the largest one accepted.
+* @param repairEnabled - the read repair engine's switch; disabled keeps the strict validation errors.
+* @returns the validated input with `offset` defaulted to 1 and `limit` to `maxLimit`, plus the rules that fired.
+*/
+function parseReadArgs(args, maxLimit, repairEnabled = true) {
+	if (args.file_path.trim().length === 0) throw new Error("file_path must be a non-empty string");
+	const repair = repairEnabled ? repairReadArgs(args.offset, args.limit, maxLimit) : void 0;
+	const offset = repair?.offset ?? (args.offset === void 0 ? 1 : parsePositiveInteger(args.offset, "offset"));
+	const limit = repair?.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,
+		force: args.force === true,
+		...repair === void 0 ? {} : { repairs: repair.repairs }
+	};
+}
+/**
+* The model-facing failure for a blocked duplicate read: the file is unchanged,
+* what was delivered and how many steps ago, and the ways past the refusal.
+*/
+function duplicateMessage(verdict) {
+	const { record, steps } = verdict;
+	return `duplicate read blocked: lines ${record.offset}-${record.endLine} unchanged, delivered ${steps} step${steps === 1 ? "" : "s"} ago; that content is still above. Use offset=${record.endLine + 1}, or force=true.`;
+}
+/**
+* Register the `read` tool and its scope-aware 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).
+* @param repair - the read repair tuning; disabled keeps every failure's verbatim error.
+*/
+function applyReadTool(ctx, caps, repair) {
+	ctx.systemPrompt.section({
+		name: "tool:read",
+		order: ctx.systemPrompt.getSectionOrder("TOOL_READ"),
+		text: ({ scope }) => ctx.tools.get("read", scope) === void 0 ? "" : "Use the read tool — not shell commands like cat — to inspect text files. 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}.`
+			},
+			...repair.duplicate.enabled ? { force: {
+				type: "boolean",
+				description: "Read this window even when it was recently delivered and the file is unchanged."
+			} } : {}
+		},
+		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
+					},
+					note: { type: "string" }
+				}
+			},
+			render: (args, value) => {
+				const input = parseReadArgs(args, caps.limit, repair.enabled);
+				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 } : {},
+						...value.note === void 0 ? {} : { repairNote: value.note }
+					})
+				}];
+			},
+			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, repair.enabled);
+			const session = exec.agent?.session;
+			const notes = (input.repairs ?? []).filter((rule) => repair.claimDisclosure(session, `read:${rule.rule}`)).map((rule) => rule.note);
+			let requestedOffset = input.offset;
+			let target;
+			let info;
+			try {
+				({target, info} = await resolveRegularReadTarget(ctx, exec, input.filePath));
+			} catch (error) {
+				if (!repair.enabled || !(error instanceof FsError) || error.code !== "FS_NOT_FOUND") throw error;
+				const repaired = await repairTargetPath(ctx, exec, input.filePath, repair.priorPaths(exec.agent?.session));
+				if (repaired === void 0) throw error;
+				notes.push(repaired.note);
+				({target, info} = await resolveRegularReadTarget(ctx, exec, repaired.path));
+			}
+			if (repair.duplicate.enabled && !input.force) {
+				const verdict = repair.duplicate.judge(exec.agent?.session, input.filePath, info.version, {
+					offset: input.offset,
+					endLine: input.offset + input.limit - 1
+				});
+				if (verdict?.action === "block") throw new Error(duplicateMessage(verdict));
+			}
+			const readChunks = () => info.size === void 0 || info.size >= caps.streamMinSize ? ctx.fs.streamText(target, exec.signal) : ctx.fs.readText(target, exec.signal).then((text) => [text]);
+			const windowRequest = {
+				offset: input.offset,
+				limit: input.limit,
+				maxLineLength: caps.maxLineLength,
+				maxBytes: caps.maxBytes
+			};
+			let window;
+			try {
+				window = await buildWindow(await readChunks(), windowRequest, target.displayPath);
+			} catch (error) {
+				const out = repair.enabled ? parseOffsetOutOfRange(error) : void 0;
+				if (out === void 0) throw error;
+				const windowSize = Math.min(input.limit, out.totalLines);
+				requestedOffset = Math.max(1, out.totalLines - windowSize + 1);
+				window = await buildWindow(await readChunks(), {
+					...windowRequest,
+					offset: requestedOffset
+				}, target.displayPath);
+			}
+			const windowOffset = window.lines[0]?.number ?? requestedOffset;
+			if (repair.completion.enabled && window.lines.length > 0 && !window.truncatedByBytes) {
+				const firstAfterWindow = windowOffset + window.lines.length;
+				const fetchLines = async (offset, count) => {
+					return (await buildWindow(await readChunks(), {
+						...windowRequest,
+						offset,
+						limit: count,
+						maxBytes: Number.MAX_SAFE_INTEGER
+					}, target.displayPath)).lines;
+				};
+				const completion = await completeWindow(window.lines, {
+					preceding: async (count) => {
+						const lastBefore = windowOffset - 1;
+						if (lastBefore < 1) return void 0;
+						const offset = Math.max(1, lastBefore - count + 1);
+						return await fetchLines(offset, lastBefore - offset + 1);
+					},
+					following: async (count) => {
+						if (firstAfterWindow > window.totalLines) return void 0;
+						return await fetchLines(firstAfterWindow, count);
+					}
+				}, { maxLines: repair.completion.maxLines });
+				if (completion !== void 0) window = {
+					...window,
+					lines: [
+						...completion.head,
+						...window.lines,
+						...completion.tail
+					]
+				};
+			}
+			const note = notes.length === 0 ? void 0 : notes.join("; ");
+			repair.duplicate.record(exec.agent?.session, input.filePath, {
+				offset: windowOffset,
+				endLine: window.lines.at(-1)?.number ?? Math.max(0, windowOffset - 1),
+				totalLines: window.totalLines,
+				version: info.version
+			});
+			const outcome = {
+				path: target.displayPath,
+				offset: window.lines[0]?.number ?? requestedOffset,
+				lines: window.lines,
+				totalLines: window.totalLines,
+				...note === void 0 ? {} : { note }
+			};
+			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 diagnostics for guarded-mutation failures. Providers and
+* policies retain operation-specific causes, while this package owns the
+* stable message shown to the model.
+* @module @deepseek-ai/dsh-tool-fs/src/error
+*/
+/**
+* Render the stable model-facing diagnostic for a guarded-mutation failure.
+* `FS_STALE_VERSION` keeps the provider's reason and appends its re-read
+* remedy. `FS_NOT_OBSERVED` replaces operation-specific policy/provider text
+* with one path-aware reason and read remedy. The original error remains the
+* cause, and both diagnostics preserve its code for machine routing. Anything
+* else passes through untouched.
+* @param error - the caught value from a write/edit execution.
+* @param displayPath - the resolved target path shown to the model.
+* @returns a remediated `FsError` for the two guarded-mutation codes, else the original value.
+*/
+function remediateFsError(error, displayPath) {
+	if (!(error instanceof FsError)) return error;
+	if (error.code === "FS_NOT_OBSERVED") return new FsError(`cannot modify "${displayPath}": file has not been read — read the file, then retry`, error.code, { cause: error });
+	if (error.code === "FS_STALE_VERSION") return new FsError(`${error.message} — re-read the file, then retry`, error.code, { cause: error });
+	return 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.
+* @param hint - the drifted-path disclosure appended inside the content block, or undefined.
+* @returns the model-facing confirmation envelope (no file content is echoed back).
+*/
+function formatWriteOutput(displayPath, outcome, hint) {
+	return `<path>${displayPath}</path>
+<type>file</type>
+<content>
+${outcome.operation === "create" ? "Created" : "Updated"} file${hint === void 0 ? "" : `\n(hint: ${hint})`}
+</content>`;
+}
+/**
+* Register the `write` tool and its scope-aware 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 API (advertisement, mode stamping, denial mapping).
+* @param hints - the drifted-path hint tuning; disabled keeps creates silent.
+*/
+function applyWriteTool(ctx, sandbox, hints) {
+	ctx.systemPrompt.section({
+		name: "tool:write",
+		order: ctx.systemPrompt.getSectionOrder("TOOL_WRITE"),
+		text: ({ scope }) => ctx.tools.get("write", scope) === void 0 ? "" : "Read an existing file before overwriting it with write (the default fs-observation-policy requires it)" + (ctx.tools.get("edit", scope) === void 0 ? "" : " 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
+					},
+					note: { type: "string" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: formatWriteOutput(value.path, value, value.note)
+			}],
+			presentationMeta: (args, value) => ({
+				operation: value.operation,
+				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, 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), target.displayPath);
+			}
+			ctx.emit("fs/observed", target, {
+				kind: "present",
+				version: outcome.version
+			}, exec);
+			let note;
+			if (hints.pathHint && outcome.operation === "create") {
+				const similar = await repairTargetPath(ctx, exec, input.filePath, hints.priorPaths(exec.agent?.session));
+				if (similar !== void 0) note = `created a new file; similar existing "${similar.path}" — write to that path if you meant to update it`;
+			}
+			return {
+				path: target.displayPath,
+				operation: outcome.operation,
+				before: outcome.before,
+				after: outcome.after,
+				...note === void 0 ? {} : { note }
+			};
+		},
+		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. When the literal match fails or is
+* ambiguous, the `@deepseek-ai/dsh-fs-edit-repair` engine re-anchors the pair before the error
+* reaches the model.
+* @module @deepseek-ai/dsh-tool-fs/src/edit
+*/
+/**
+* Error codes that can mean "the target does not exist": the policy's unread
+* refusal, the provider's stale/missing guards on a guarded edit, and the
+* no-match failure FakeFs-style providers raise for absent content. Each is
+* only treated as a drifted path after a stat confirms the target's absence —
+* a present target means the code carries its own ordinary meaning (an unread
+* existing file, real staleness, a failed literal match).
+*/
+const ABSENT_TARGET_CODES = new Set([
+	"FS_NOT_FOUND",
+	"FS_STALE_VERSION",
+	"FS_EDIT_NOT_FOUND",
+	"FS_NOT_OBSERVED"
+]);
+/**
+* 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.`;
+}
+/**
+* Repair a failed or ambiguous literal edit through the fs-edit-repair engine.
+* A repaired pair is applied through the same guarded `editText` seam with the
+* original intent, so version guards and sandbox policy stay in force; the
+* outcome carries the repair note for the model. Without a safe patch the
+* remediated error is re-thrown, enriched with the engine's near-match hints.
+* @param ctx - the plugin context, used to re-read the target for repair.
+* @param sandbox - the shared sandbox-escalation API, used for denial mapping.
+* @param repair - the resolved repair tuning.
+* @param target - the resolved edit target.
+* @param input - the validated edit arguments.
+* @param intent - the intent resolved by the `fs/edit-intent` waterfall.
+* @param exec - the tool execution context.
+* @param sandboxPolicy - the per-call sandbox policy.
+* @param error - the failure thrown by the original `editText` call.
+* @returns the outcome of the repaired edit plus its model-facing note.
+*/
+async function repairEditFailure(ctx, sandbox, repair, target, input, intent, exec, sandboxPolicy, error) {
+	const mapped = sandbox.mapError(error, sandboxPolicy);
+	if (!repair.enabled || input.replaceAll || !(mapped instanceof FsError) || mapped.code !== "FS_EDIT_NOT_FOUND" && mapped.code !== "FS_AMBIGUOUS_EDIT") throw remediateFsError(mapped, target.displayPath);
+	let content;
+	try {
+		content = await ctx.fs.readText(target, exec.signal);
+	} catch {
+		throw remediateFsError(mapped, target.displayPath);
+	}
+	const attempt = repairStrReplace({
+		content,
+		oldString: input.oldString,
+		newString: input.newString
+	}, repair);
+	const patch = attempt.patch;
+	if (patch !== void 0) return {
+		outcome: await ctx.fs.editText(target, {
+			oldString: patch.oldString,
+			newString: patch.newString,
+			replaceAll: false
+		}, intent, exec.signal, sandboxPolicy),
+		note: patch.note
+	};
+	const hints = attempt.diagnosis.hints;
+	const base = remediateFsError(mapped, target.displayPath);
+	if (hints.length === 0 || !(base instanceof FsError)) throw base;
+	throw new FsError(`${base.message} ${hints.join(" ")}`, base.code, { cause: base });
+}
+/**
+* Register the `edit` tool and its scope-aware 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 API (advertisement, mode stamping, denial mapping).
+* @param repair - the resolved tuning for the failed-match repair engine and missing-path re-anchoring.
+*/
+function applyEditTool(ctx, sandbox, repair) {
+	ctx.systemPrompt.section({
+		name: "tool:edit",
+		order: ctx.systemPrompt.getSectionOrder("TOOL_EDIT"),
+		text: ({ scope }) => ctx.tools.get("edit", scope) === void 0 ? "" : "Read a file before editing it (the default fs-observation-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."
+			},
+			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
+					},
+					note: { type: "string" }
+				}
+			},
+			render: (args, value) => [{
+				type: "text",
+				text: `${formatEditOutput(value.path, args.replace_all ?? false)}${value.note === void 0 ? "" : ` (repair: ${value.note})`}`
+			}],
+			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);
+			let target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, sandboxPolicy?.workspaceRoot));
+			let outcome;
+			let note;
+			let intent;
+			const applyAt = async (editTarget) => {
+				const slot = await ctx.waterfall("fs/edit-intent", editTarget, exec, () => void 0);
+				intent = slot;
+				return await ctx.fs.editText(editTarget, {
+					oldString: input.oldString,
+					newString: input.newString,
+					replaceAll: input.replaceAll
+				}, slot, exec.signal, sandboxPolicy);
+			};
+			try {
+				outcome = await applyAt(target);
+			} catch (error) {
+				const mapped = sandbox.mapError(error, sandboxPolicy);
+				if (repair.enabled && mapped instanceof FsError && ABSENT_TARGET_CODES.has(mapped.code) && await ctx.fs.stat(target, exec.signal) === void 0) {
+					const repaired = await repairTargetPath(ctx, exec, input.filePath, repair.priorPaths(exec.agent?.session));
+					if (repaired === void 0) throw remediateFsError(mapped, target.displayPath);
+					target = await ctx.fs.resolve(repaired.path, sessionResolveOptions(exec, sandboxPolicy?.workspaceRoot));
+					note = repaired.note;
+					try {
+						outcome = await applyAt(target);
+					} catch (retryError) {
+						throw remediateFsError(sandbox.mapError(retryError, sandboxPolicy), target.displayPath);
+					}
+				} else {
+					const attempt = await repairEditFailure(ctx, sandbox, repair, target, input, intent, exec, sandboxPolicy, error);
+					outcome = attempt.outcome;
+					note = attempt.note;
+				}
+			}
+			ctx.emit("fs/observed", target, {
+				kind: "present",
+				version: outcome.version
+			}, exec);
+			return {
+				path: target.displayPath,
+				before: outcome.before,
+				after: outcome.after,
+				...note === void 0 ? {} : { note }
+			};
+		},
+		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/read-image.js
+/**
+* The model-facing `read_image` tool commits a PNG/JPEG/WebP/GIF file. A path
+* without a file extension is identified from its file signature, while the
+* attachment service's full decode stays authoritative. The mounted `ctx.fs`
+* backend owns path resolution and read access; names only declare media type.
+*
+* The route gate is deliberately stricter than the host upload preflight. An
+* image-reading tool is useful only when the exact calling route can inspect
+* its result, so unknown capability refuses instead of relying on an adapter
+* failure after filesystem and attachment work.
+* @module @deepseek-ai/dsh-tool-fs/src/read-image
+*/
+/** Extensions `read_image` accepts; magic-byte validation at the attachment service stays authoritative. */
+const IMAGE_EXTENSIONS = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".gif": "image/gif"
+};
+const PNG_SIGNATURE = [
+	137,
+	80,
+	78,
+	71,
+	13,
+	10,
+	26,
+	10
+];
+const JPEG_SIGNATURE = [
+	255,
+	216,
+	255
+];
+function matchesBytes(data, offset, expected) {
+	if (data.byteLength < offset + expected.length) return false;
+	return expected.every((byte, index) => data[offset + index] === byte);
+}
+function matchesAscii(data, offset, value) {
+	if (data.byteLength < offset + value.length) return false;
+	for (let index = 0; index < value.length; index += 1) if (data[offset + index] !== value.charCodeAt(index)) return false;
+	return true;
+}
+/**
+* Identify the media type declared by a supported image file signature.
+* @param data - file bytes read through the current filesystem backend.
+* @returns the detected supported media type, or undefined for other bytes.
+*/
+function sniffImageMediaType(data) {
+	if (matchesBytes(data, 0, PNG_SIGNATURE)) return "image/png";
+	if (matchesBytes(data, 0, JPEG_SIGNATURE)) return "image/jpeg";
+	if (matchesAscii(data, 0, "GIF87a") || matchesAscii(data, 0, "GIF89a")) return "image/gif";
+	if (matchesAscii(data, 0, "RIFF") && matchesAscii(data, 8, "WEBP")) return "image/webp";
+}
+const IMAGE_VALUE_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: true,
+	properties: {
+		attachmentId: {
+			type: "string",
+			required: true
+		},
+		mediaType: {
+			type: "string",
+			enum: [
+				"image/png",
+				"image/jpeg",
+				"image/webp",
+				"image/gif"
+			],
+			required: true
+		},
+		bytes: {
+			type: "integer",
+			required: true
+		},
+		width: {
+			type: "integer",
+			required: true
+		},
+		height: {
+			type: "integer",
+			required: true
+		},
+		name: { type: "string" },
+		originalDimensions: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				width: {
+					type: "integer",
+					required: true
+				},
+				height: {
+					type: "integer",
+					required: true
+				}
+			}
+		}
+	}
+};
+/**
+* Map a model-supplied path to its declared image media type by extension.
+* @param filePath - the raw `file_path` argument (not yet resolved).
+* @returns the declared media type, or undefined when the path does not claim an image.
+*/
+function imageMediaTypeForPath(filePath) {
+	return IMAGE_EXTENSIONS[extname(filePath).toLowerCase()];
+}
+/**
+* Enforce the strict image-capability gate for the calling route. Resolves the
+* session's latest routed provider/model (request header config, then agent
+* options) and requires the exact resolved route to declare `image` input explicitly.
+* @param ctx - the plugin context used to resolve the optional `llm` service.
+* @param exec - the tool-execution context supplying the calling agent.
+* @param requestedPath - the raw, not-yet-resolved path rendered in refusal messages.
+*/
+async function assertImageCapableRoute(ctx, exec, requestedPath) {
+	const routed = exec.agent?.session.requestHeader()?.config;
+	const provider = routed?.provider ?? exec.agent?.options.provider;
+	const model = routed?.model ?? exec.agent?.options.model;
+	const llm = ctx.get("llm");
+	if (provider === void 0 || model === void 0 || llm === void 0) throw new Error(`cannot read "${requestedPath}" as an image: the current model route could not be resolved`);
+	const active = await llm.resolveModelInfo(provider, model, exec.signal);
+	if (active.inputModalities === void 0 || !active.inputModalities.includes("image")) throw new Error(`cannot read "${requestedPath}" as an image: model "${model}" does not declare image input; switch to an image-capable model to read images`);
+}
+/** Refuse a media type outside the deployment's accepted set, naming the offending path. */
+function assertDeploymentAccepts(attachments, mediaType, displayPath) {
+	if (!attachments.imageLimits.mediaTypes.includes(mediaType)) throw new Error(`cannot read "${displayPath}": ${mediaType} images are not accepted by this deployment`);
+}
+/**
+* Re-brand a structured image outcome into the durable attachment reference an
+* `ImageBlock` carries.
+* @param image - the image metadata from the output schema.
+* @returns the branded attachment reference.
+*/
+function imageRefFromValue(image) {
+	return {
+		attachmentId: AttachmentId(image.attachmentId),
+		mediaType: image.mediaType,
+		bytes: image.bytes,
+		width: image.width,
+		height: image.height,
+		...image.name === void 0 ? {} : { name: image.name },
+		...image.originalDimensions === void 0 ? {} : { originalDimensions: { ...image.originalDimensions } }
+	};
+}
+/**
+* Format an image read as the model-facing envelope beside its image block.
+* A downscaled read names the on-disk dimensions and the multiplier that maps
+* coordinates measured on the attached image back onto the original file.
+* @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+* @param image - the image metadata to summarize.
+* @returns the model-facing envelope; the image itself rides the adjacent image block.
+*/
+function formatImageReadOutput(displayPath, image) {
+	let scaled = "";
+	if (image.originalDimensions !== void 0) {
+		const x = (image.originalDimensions.width / image.width).toFixed(2);
+		const y = (image.originalDimensions.height / image.height).toFixed(2);
+		const advice = x === y ? `multiply coordinates by ${x}` : `multiply x coordinates by ${x} and y coordinates by ${y}`;
+		scaled = ` (downscaled from ${image.originalDimensions.width}x${image.originalDimensions.height} px; ${advice} to locate features in the original file)`;
+	}
+	return `<path>${displayPath}</path>
+<type>image</type>
+<content>
+${image.mediaType} image, ${image.width}x${image.height} px, ${image.bytes} bytes${scaled}
+</content>`;
+}
+/**
+* Project one structured image read into its model-facing envelope and image.
+* @param value - the image-read outcome.
+* @returns the two content blocks used by native and nested dispatches.
+*/
+function imageReadContent(value) {
+	return [{
+		type: "text",
+		text: formatImageReadOutput(value.path, value.image)
+	}, {
+		type: "image",
+		attachment: imageRefFromValue(value.image)
+	}];
+}
+/**
+* Register the `read_image` tool into the given context. The composing plugin
+* owns the attachments gate: `src/index.ts` calls this inside
+* `ctx.inject(['attachments'], …)` so the tool exists only while a durable
+* store is mounted. Execution still re-checks `ctx.get('attachments')` for
+* direct callers and gates on the calling route's declared image input.
+* @param ctx - the registration scope; execution uses its `fs` service plus
+*   the optional `attachments`/`llm` services.
+*/
+function applyReadImageTool(ctx) {
+	ctx.tools.register(defineTool({
+		name: "read_image",
+		description: "Read a PNG/JPEG/WebP/GIF file and return the image itself. Large images are downscaled automatically; do not install image libraries or create thumbnails to inspect an image.",
+		parameters: { file_path: {
+			type: "string",
+			required: true,
+			description: "Path to the image file, resolved by the filesystem backend."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					path: {
+						type: "string",
+						required: true
+					},
+					image: IMAGE_VALUE_SCHEMA
+				}
+			},
+			render: (_args, value) => imageReadContent(value),
+			presentationMeta: (_args, value) => ({ path: value.path })
+		},
+		isConcurrencySafe: () => true,
+		async execute(args, exec) {
+			if (args.file_path.trim().length === 0) throw new Error("file_path must be a non-empty string");
+			const extension = extname(args.file_path).toLowerCase();
+			const declared = imageMediaTypeForPath(args.file_path);
+			if (declared === void 0 && extension !== "") throw new Error(`cannot read "${args.file_path}": the ${extension} extension does not declare a supported image format; read_image accepts PNG/JPEG/WebP/GIF files, including extension-less files in those formats`);
+			const attachments = ctx.get("attachments");
+			if (attachments === void 0) throw new Error(`cannot read "${args.file_path}" as an image: no attachment service is mounted`);
+			if (declared !== void 0) assertDeploymentAccepts(attachments, declared, args.file_path);
+			await assertImageCapableRoute(ctx, exec, args.file_path);
+			const { target, info } = await resolveRegularReadTarget(ctx, exec, args.file_path);
+			const byteCap = Math.min(attachments.imageLimits.maxImageBytes, attachments.imageLimits.maxMessageImageBytes);
+			const data = await ctx.fs.readBytes(target, exec.signal, byteCap);
+			const mediaType = declared ?? sniffImageMediaType(data);
+			if (mediaType === void 0) throw new Error(`cannot read "${target.displayPath}": the file content is not a supported image format; read_image accepts PNG/JPEG/WebP/GIF`);
+			if (declared === void 0) assertDeploymentAccepts(attachments, mediaType, target.displayPath);
+			let ref;
+			try {
+				ref = await attachments.saveImage({
+					data,
+					mediaType,
+					name: basename(target.displayPath)
+				});
+			} catch (error) {
+				if (!(error instanceof AttachmentError)) throw error;
+				if (error.code === "IMAGE_DIMENSION_TOO_LARGE") throw new Error(`cannot read "${target.displayPath}": at least one image side exceeds the ${attachments.imageLimits.maxImageDimension}px limit; downscale the image and read the smaller copy`, { cause: error });
+				if (error.code === "IMAGE_TOO_MANY_PIXELS") throw new Error(`cannot read "${target.displayPath}": the image exceeds the ${attachments.imageLimits.maxImagePixels}-pixel decoded-size limit; downscale the image and read the smaller copy`, { cause: error });
+				if (error.code === "IMAGE_TOO_LARGE") throw new Error(`cannot read "${target.displayPath}": the image cannot be stored within the deployment's byte limits; downscale the image and read the smaller copy`, { cause: error });
+				if (error.code === "ATTACHMENT_WRITE_FAILED" && /16-bit PNG/iu.test(error.message)) throw new Error(`cannot read "${target.displayPath}": the 16-bit PNG could not be converted to the normalized 8-bit sRGB form; convert it to an 8-bit PNG/JPEG/WebP and retry`, { cause: error });
+				if (error.code === "INVALID_IMAGE" && declared === void 0) throw new Error(`cannot read "${target.displayPath}": the bytes do not decode as a supported PNG/JPEG/WebP/GIF image; the file may be truncated or corrupt`, { cause: error });
+				if (error.code !== "IMAGE_TYPE_MISMATCH") throw error;
+				if (declared === void 0) throw new Error(`cannot read "${target.displayPath}": the file signature claims ${mediaType}, but the bytes decode as a different image format; the file may be corrupt`, { cause: error });
+				throw new Error(`cannot read "${target.displayPath}": the ${extension} extension declares ${mediaType}, but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats`, { cause: error });
+			}
+			ctx.emit("fs/observed", target, {
+				kind: "present",
+				version: info.version
+			}, exec);
+			return {
+				path: target.displayPath,
+				image: {
+					attachmentId: ref.attachmentId,
+					mediaType: ref.mediaType,
+					bytes: ref.bytes,
+					width: ref.width,
+					height: ref.height,
+					...ref.name === void 0 ? {} : { name: ref.name },
+					...ref.originalDimensions === void 0 ? {} : { originalDimensions: { ...ref.originalDimensions } }
+				}
+			};
+		},
+		presentCall(args) {
+			return {
+				card: "generic",
+				title: `Read image ${args.file_path}`,
+				kind: "read",
+				locations: [{ path: args.file_path }]
+			};
+		}
+	}));
+}
+//#endregion
+//#region lib/types/sandbox.js
+/**
+* The sandbox-escalation API 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 API: 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 FsSandboxController = 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: sandboxPermissionsDescription("operation")
+			},
+			justification: {
+				type: "string",
+				description: "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. Use the language of the user’s current request."
+			}
+		};
+	}
+	/**
+	* 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. Repeating the standing mode
+	* requires no approval. 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 — `ToolRuntime`
+	* 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, read_image, 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"
+];
+/** Defaults for the read repair sub-tunables. */
+const DEFAULT_DUPLICATE_STEPS = 4;
+/** Defaults for the structural completion sub-tunables. */
+const DEFAULT_COMPLETION_MAX_LINES = 40;
+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),
+	readRepair: z.object({
+		enabled: z.boolean().default(true),
+		duplicate: z.object({
+			enabled: z.boolean().default(true),
+			maxSteps: z.number().default(DEFAULT_DUPLICATE_STEPS)
+		}).default({
+			enabled: true,
+			maxSteps: DEFAULT_DUPLICATE_STEPS
+		}),
+		completion: z.object({
+			enabled: z.boolean().default(true),
+			maxLines: z.number().default(DEFAULT_COMPLETION_MAX_LINES)
+		}).default({
+			enabled: true,
+			maxLines: DEFAULT_COMPLETION_MAX_LINES
+		})
+	}).default({
+		enabled: true,
+		duplicate: {
+			enabled: true,
+			maxSteps: DEFAULT_DUPLICATE_STEPS
+		},
+		completion: {
+			enabled: true,
+			maxLines: DEFAULT_COMPLETION_MAX_LINES
+		}
+	}),
+	editRepair: z.object({
+		enabled: z.boolean().default(true),
+		maxFileChars: z.number().default(DEFAULT_MAX_FILE_CHARS),
+		maxWindowLines: z.number().default(DEFAULT_MAX_WINDOW_LINES)
+	}).default({
+		enabled: true,
+		maxFileChars: DEFAULT_MAX_FILE_CHARS,
+		maxWindowLines: DEFAULT_MAX_WINDOW_LINES
+	}),
+	writeRepair: z.object({ pathHint: z.boolean().default(true) }).default({ pathHint: true })
+});
+/** 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, plus `read_image` while `attachments` is mounted. */
+function apply(ctx, config) {
+	const resolved = config;
+	assertPositiveInteger("readLimit", resolved.readLimit);
+	assertPositiveInteger("readMaxLineLength", resolved.readMaxLineLength);
+	assertPositiveInteger("readMaxBytes", resolved.readMaxBytes);
+	assertPositiveInteger("readStreamMinSize", resolved.readStreamMinSize);
+	const editRepair = resolved.editRepair;
+	const repairMaxFileChars = editRepair.maxFileChars ?? DEFAULT_MAX_FILE_CHARS;
+	const repairMaxWindowLines = editRepair.maxWindowLines ?? DEFAULT_MAX_WINDOW_LINES;
+	assertPositiveInteger("editRepair.maxFileChars", repairMaxFileChars);
+	assertPositiveInteger("editRepair.maxWindowLines", repairMaxWindowLines);
+	const sessionPaths = createSessionPathProjection(["file_path", "path"]);
+	const readWindows = createReadWindowProjection();
+	const disclosures = createDisclosureLedger();
+	ctx.on("session/event", (session, event) => {
+		sessionPaths.observe(session, event);
+		readWindows.observe(session, event);
+		disclosures.observe(session, event);
+	});
+	const readRepair = resolved.readRepair;
+	const duplicateEnabled = readRepair.enabled === true && readRepair.duplicate?.enabled === true;
+	const duplicateSteps = readRepair.duplicate?.maxSteps ?? DEFAULT_DUPLICATE_STEPS;
+	const completionMaxLines = readRepair.completion?.maxLines ?? DEFAULT_COMPLETION_MAX_LINES;
+	assertPositiveInteger("readRepair.duplicate.maxSteps", duplicateSteps);
+	assertPositiveInteger("readRepair.completion.maxLines", completionMaxLines);
+	applyReadTool(ctx, {
+		limit: resolved.readLimit,
+		maxLineLength: resolved.readMaxLineLength,
+		maxBytes: resolved.readMaxBytes,
+		streamMinSize: resolved.readStreamMinSize
+	}, {
+		enabled: readRepair.enabled ?? true,
+		priorPaths: (session, limit) => sessionPaths.priorPaths(session, limit),
+		duplicate: {
+			enabled: duplicateEnabled,
+			maxSteps: duplicateSteps,
+			judge: (session, path, version, window) => readWindows.judge(session, path, version, window, duplicateSteps),
+			record: (session, path, observation) => {
+				readWindows.record(session, path, observation);
+			}
+		},
+		completion: {
+			enabled: readRepair.enabled === true && readRepair.completion?.enabled === true,
+			maxLines: completionMaxLines
+		},
+		claimDisclosure: (session, key) => disclosures.claim(session, key)
+	});
+	ctx.inject(["attachments"], (imageCtx) => {
+		applyReadImageTool(imageCtx);
+	});
+	const sandbox = new FsSandboxController(ctx);
+	applyWriteTool(ctx, sandbox, {
+		pathHint: resolved.writeRepair.pathHint ?? true,
+		priorPaths: (session, limit) => sessionPaths.priorPaths(session, limit)
+	});
+	applyEditTool(ctx, sandbox, {
+		enabled: editRepair.enabled ?? true,
+		maxFileChars: repairMaxFileChars,
+		maxWindowLines: repairMaxWindowLines,
+		priorPaths: (session, limit) => sessionPaths.priorPaths(session, limit)
+	});
+}
+//#endregion
+export { Config, apply, inject, name };