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

package/lib/index.js

@@ -8,16 +8,16 @@ 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 {
@@ -60,14 +60,14 @@ function finish(acc, request, displayPath) {
 	};
 }
 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);
@@ -79,15 +79,15 @@ function parseOffsetOutOfRange(error) {
 		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;
@@ -114,12 +114,12 @@ async function buildWindow(chunks, request, displayPath) {
 	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;
@@ -132,30 +132,30 @@ function formatReadOutput(displayPath, outcome) {
 ${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;
@@ -177,30 +177,30 @@ function readMetaFromMeta(meta) {
 		...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 {
@@ -208,19 +208,19 @@ function sessionResolveOptions(exec, policyWorkspaceRoot) {
 		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);
@@ -234,18 +234,18 @@ async function resolveRegularReadTarget(ctx, exec, requestedPath) {
 		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, {
@@ -258,7 +258,7 @@ async function repairTargetPath(ctx, exec, requestedPath, knownPaths) {
 		}
 	});
 }
-/** 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);
@@ -266,23 +266,23 @@ function fsPathExplorer(ctx, signal) {
 		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;
@@ -298,12 +298,12 @@ function fenceLine(line) {
 		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;
@@ -344,15 +344,15 @@ function codeBrackets(line, state) {
 	}
 	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 = [];
@@ -378,13 +378,13 @@ function scan(lines) {
 		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;
@@ -407,11 +407,11 @@ function detectOpenIndent(lines) {
 		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 {
@@ -427,14 +427,14 @@ function detectOpenTail(lines) {
 	};
 	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;
@@ -448,15 +448,15 @@ function detectOpenIndentHead(window, preceding) {
 		};
 	}
 }
-/**
-* 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);
@@ -471,12 +471,12 @@ function detectOpenHead(window, preceding) {
 	};
 	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;
@@ -499,7 +499,7 @@ function closureLength(construct, appended) {
 	}
 	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;
@@ -507,28 +507,28 @@ function indentWidth(line) {
 	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 = [];
@@ -563,35 +563,35 @@ async function completeWindow(lines, supply, tuning) {
 		...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;
@@ -606,20 +606,20 @@ function parseReadArgs(args, maxLimit, repairEnabled = 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",
@@ -848,17 +848,17 @@ function applyReadTool(ctx, caps, repair) {
 		}
 	}));
 }
-/**
-* 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 = [];
@@ -883,63 +883,63 @@ function computeHunkDiffs(path, before, after) {
 	}
 	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 {
@@ -947,13 +947,13 @@ function parseWriteArgs(args) {
 		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>
@@ -961,12 +961,12 @@ function formatWriteOutput(displayPath, outcome, hint) {
 ${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",
@@ -1082,37 +1082,37 @@ function applyWriteTool(ctx, sandbox, hints) {
 		}
 	}));
 }
-//#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");
@@ -1124,32 +1124,32 @@ function parseEditArgs(args) {
 		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);
@@ -1178,12 +1178,12 @@ async function repairEditFailure(ctx, sandbox, repair, target, input, intent, ex
 	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",
@@ -1316,21 +1316,21 @@ function applyEditTool(ctx, sandbox, repair) {
 		}
 	}));
 }
-//#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",
@@ -1362,11 +1362,11 @@ function matchesAscii(data, offset, value) {
 	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";
@@ -1421,22 +1421,22 @@ const IMAGE_VALUE_SCHEMA = {
 		}
 	}
 };
-/**
-* 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;
@@ -1446,16 +1446,16 @@ async function assertImageCapableRoute(ctx, exec, requestedPath) {
 	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),
@@ -1467,14 +1467,14 @@ function imageRefFromValue(image) {
 		...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) {
@@ -1489,11 +1489,11 @@ function formatImageReadOutput(displayPath, image) {
 ${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",
@@ -1503,15 +1503,15 @@ function imageReadContent(value) {
 		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",
@@ -1597,29 +1597,29 @@ function applyReadImageTool(ctx) {
 		}
 	}));
 }
-//#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;
@@ -1628,13 +1628,13 @@ var FsSandboxController = class {
 		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: {
@@ -1648,19 +1648,19 @@ var FsSandboxController = class {
 			}
 		};
 	}
-	/**
-	* 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 } : {} });
@@ -1684,45 +1684,45 @@ var FsSandboxController = class {
 			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),
@@ -1767,11 +1767,11 @@ const Config = z.object({
 	}),
 	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);
@@ -1834,5 +1834,5 @@ function apply(ctx, config) {
 		priorPaths: (session, limit) => sessionPaths.priorPaths(session, limit)
 	});
 }
-//#endregion
+ 
 export { Config, apply, inject, name };