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

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";
+ 
+
+
+
+
+
+
+ 
+const READ_MAX_LINE_LENGTH = 2e3;
+ 
+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;
+
+
+
+
+
+
+
+
+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;
+}
+
+
+
+
+
+
+
+
+
+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);
+}
+
+
+
+
+
+
+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>`;
+}
+
+
+
+
+
+
+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";
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+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 }
+	};
+}
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+function sessionCwd(exec) {
+	return exec.agent?.session.header.cwd;
+}
+
+
+
+
+
+
+function sessionResolveOptions(exec, policyWorkspaceRoot) {
+	const cwd = policyWorkspaceRoot ?? sessionCwd(exec);
+	return {
+		...cwd !== void 0 ? { cwd } : {},
+		signal: exec.signal
+	};
+}
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+
+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
+	};
+}
+
+
+
+
+
+
+
+
+
+
+
+
+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;
+		}
+	});
+}
+ 
+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);
+	} };
+}
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 
+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
+	};
+}
+ 
+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;
+}
+ 
+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;
+}
+ 
+function isOpener(ch) {
+	return ch === "(" || ch === "[" || ch === "{";
+}
+
+
+
+
+
+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
+	};
+}
+
+
+
+
+
+
+
+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
+	};
+}
+
+
+
+
+
+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);
+}
+
+
+
+
+
+
+
+
+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
+		};
+	}
+}
+
+
+
+
+
+
+
+
+
+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);
+}
+
+
+
+
+
+
+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;
+}
+ 
+function indentWidth(line) {
+	let width = 0;
+	for (const ch of line) if (ch === " ") width += 1;
+	else if (ch === "	") width += 4;
+	else break;
+	return width;
+}
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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 }
+	};
+}
+ 
+ 
+
+
+
+
+
+ 
+const READ_LIMIT = 2e3;
+
+
+
+
+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;
+}
+
+
+
+
+
+
+
+
+
+
+
+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 }
+	};
+}
+
+
+
+
+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.`;
+}
+
+
+
+
+
+
+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
+				}]
+			};
+		}
+	}));
+}
+
+
+
+
+
+
+
+
+
+
+
+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;
+}
+ 
+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";
+}
+
+
+
+
+
+
+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;
+}
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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;
+}
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+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
+	};
+}
+
+
+
+
+
+
+
+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>`;
+}
+
+
+
+
+
+
+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
+			};
+		}
+	}));
+}
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+const ABSENT_TARGET_CODES = new Set([
+	"FS_NOT_FOUND",
+	"FS_STALE_VERSION",
+	"FS_EDIT_NOT_FOUND",
+	"FS_NOT_OBSERVED"
+]);
+
+
+
+
+
+
+
+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
+	};
+}
+
+
+
+
+
+
+function formatEditOutput(displayPath, replaceAll) {
+	return replaceAll ? `The file ${displayPath} has been updated. All occurrences were successfully replaced.` : `The file ${displayPath} has been updated successfully.`;
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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 });
+}
+
+
+
+
+
+
+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
+			};
+		}
+	}));
+}
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+ 
+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;
+}
+
+
+
+
+
+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
+				}
+			}
+		}
+	}
+};
+
+
+
+
+
+function imageMediaTypeForPath(filePath) {
+	return IMAGE_EXTENSIONS[extname(filePath).toLowerCase()];
+}
+
+
+
+
+
+
+
+
+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`);
+}
+ 
+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`);
+}
+
+
+
+
+
+
+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 } }
+	};
+}
+
+
+
+
+
+
+
+
+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>`;
+}
+
+
+
+
+
+function imageReadContent(value) {
+	return [{
+		type: "text",
+		text: formatImageReadOutput(value.path, value.image)
+	}, {
+		type: "image",
+		attachment: imageRefFromValue(value.image)
+	}];
+}
+
+
+
+
+
+
+
+
+
+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 }]
+			};
+		}
+	}));
+}
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+var FsSandboxController = class {
+	ctx;
+	 
+	escalationModes;
+	 
+	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");
+	}
+	
+
+
+
+
+
+
+	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."
+			}
+		};
+	}
+	
+
+
+
+
+
+
+
+
+
+
+
+
+	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
+		};
+	}
+	
+
+
+
+
+
+
+
+
+
+
+
+
+
+	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 });
+	}
+};
+ 
+ 
+
+
+
+
+
+
+ 
+const name = "tool-fs";
+ 
+const inject = [
+	"tools",
+	"fs",
+	"systemPrompt"
+];
+ 
+const DEFAULT_DUPLICATE_STEPS = 4;
+ 
+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 })
+});
+ 
+function assertPositiveInteger(name, value) {
+	if (!Number.isInteger(value) || value < 1) throw new Error(`tool-fs: ${name} must be a positive integer`);
+}
+ 
+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)
+	});
+}
+ 
+export { Config, apply, inject, name };