@khorsheed/dsh-file-preview 0.1.0

package/lib/index.js

@@ -0,0 +1,1338 @@
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import z from "@deepseek-ai/schemastery";
+import { homedir, release } from "node:os";
+import { runNativeCommand } from "@deepseek-ai/dsh-native-command";
+//#region lib/types/bash-writes.js
+/**
+* Bash-write capture: the "B channel + A collection" seam (upstream-seam
+* registry S2). The official bash tool writes files (heredocs, redirects,
+* `tee`, `sed -i`) with no log structure a products view can fold — the
+* file-preview fold only knows `read`/`write`/`edit` tool calls. This module
+* watches each session's event stream, extracts high-precision write targets
+* from bash command strings, verifies each with `fs.stat` after the call
+* settles (prefer a miss over a false positive), and keeps a per-session
+* registry the `filePreview.list` fold merges into its entries. It never
+* touches the session log — the official `Session.append` cannot mark an
+* event `ignorable: true`, and the persistence read path refuses unknown
+* event types that lack the marker (a plugin-appended event would poison the
+* log on reload), which is exactly why this seam is a side registry instead.
+* The registry is rebuilt on `session/created` by replaying the session's own
+* history, so a restarted host regains its captures.
+* @module @khorsheed/dsh-file-preview
+*/
+/** Cap on write candidates extracted from one command (bounds stat load). */
+const MAX_CANDIDATES_PER_COMMAND = 8;
+/** A write-target token stripped of its surrounding quotes. */
+function stripQuotes(token) {
+	let t = token;
+	while (t.length >= 2 && (t.startsWith("'") && t.endsWith("'") || t.startsWith("\"") && t.endsWith("\""))) t = t.slice(1, -1);
+	return t;
+}
+/** Whether a character ends a shell token (outside quotes). */
+function isTokenBoundary(ch) {
+	return ch === " " || ch === "	" || ch === "\n" || ch === "\r" || ch === ";" || ch === "|" || ch === "&" || ch === "<" || ch === ">";
+}
+/**
+* Read the next shell token starting at `from` (after any whitespace), with
+* quote awareness so `'a b'` stays one token. Stops at a boundary character
+* outside quotes.
+* @param command - the command text.
+* @param from - scan start index.
+* @returns the raw token and the index just past it, or null at end / boundary.
+*/
+function nextToken(command, from) {
+	const n = command.length;
+	let i = from;
+	while (i < n && (command[i] === " " || command[i] === "	")) i++;
+	if (i >= n || isTokenBoundary(command[i] ?? "")) return null;
+	let token = "";
+	let quote;
+	while (i < n) {
+		const ch = command[i] ?? "";
+		if (quote !== void 0) {
+			if (ch === quote) quote = void 0;
+			token += ch;
+			i++;
+			continue;
+		}
+		if (ch === "'" || ch === "\"") {
+			quote = ch;
+			token += ch;
+			i++;
+			continue;
+		}
+		if (isTokenBoundary(ch)) break;
+		token += ch;
+		i++;
+	}
+	return token.length === 0 ? null : {
+		token,
+		end: i
+	};
+}
+/**
+* Extract write-target tokens from one bash command string. High-precision
+* forms only (the "minimal set"): a single `>` redirect (`cat > path`, any
+* `cmd > path`), `tee path` (append forms skipped), and `sed -i ... path`
+* (the first non-option token after the inline script). `>>`, fd redirects
+* (`2>`), `>&`, `<>`, and any write form inside a heredoc body are ignored;
+* `cp`/`mv`/`python open()` are deliberately deferred. Quoted targets keep
+* their quotes here — expansion strips them.
+* @param command - the bash tool's command string.
+* @returns raw target tokens, capped per command.
+*/
+function extractWriteTargets(command) {
+	const targets = [];
+	const n = command.length;
+	let i = 0;
+	let quote;
+	let heredoc;
+	while (i < n) {
+		const ch = command[i] ?? "";
+		if (heredoc !== void 0) {
+			const nl = command.indexOf("\n", i);
+			if (command.slice(i, nl === -1 ? n : nl).trim() === heredoc) heredoc = void 0;
+			i = nl === -1 ? n : nl + 1;
+			continue;
+		}
+		if (quote !== void 0) {
+			if (ch === quote) quote = void 0;
+			i++;
+			continue;
+		}
+		if (ch === "'" || ch === "\"") {
+			quote = ch;
+			i++;
+			continue;
+		}
+		if (ch === "<" && command[i + 1] === "<") {
+			let j = i + 2;
+			if (command[j] === "-") j++;
+			const q = command[j];
+			let delim = "";
+			if (q === "'" || q === "\"") {
+				const end = command.indexOf(q, j + 1);
+				delim = end === -1 ? "" : command.slice(j + 1, end);
+				j = end === -1 ? n : end + 1;
+			} else {
+				const start = j;
+				while (j < n && !/\s/.test(command[j] ?? "")) j++;
+				delim = command.slice(start, j);
+			}
+			if (delim.length > 0) heredoc = delim;
+			i = j;
+			continue;
+		}
+		if (ch === "t" && command.startsWith("tee", i) && (i === 0 || isTokenBoundary(command[i - 1] ?? ""))) {
+			const after = command.slice(i + 3);
+			if (/^\s*(?:-a\b|--append\b)/.test(after)) {
+				i += 3;
+				continue;
+			}
+			const consumed = /^\s*(?:-i\b|--ignore-interrupts\s+)*/.exec(after)?.[0].length ?? 0;
+			const tok = nextToken(command, i + 3 + consumed);
+			if (tok !== null) {
+				targets.push(tok.token);
+				i = tok.end;
+				continue;
+			}
+			i += 3;
+			continue;
+		}
+		if (ch === "s" && command.startsWith("sed", i) && (i === 0 || isTokenBoundary(command[i - 1] ?? ""))) {
+			const im = /^\s*-i([A-Za-z0-9.]*)/.exec(command.slice(i + 3));
+			if (im === null) {
+				i++;
+				continue;
+			}
+			let j = i + 3 + im[0].length;
+			const opt = nextToken(command, j);
+			if (opt !== null && (opt.token === "-e" || opt.token === "--expression")) {
+				const script = nextToken(command, opt.end);
+				j = script === null ? opt.end : script.end;
+			} else if (opt !== null) j = opt.end;
+			const file = nextToken(command, j);
+			if (file !== null && !file.token.startsWith("-")) {
+				targets.push(file.token);
+				i = file.end;
+				continue;
+			}
+			i = j;
+			continue;
+		}
+		if (ch === ">") {
+			const prev = command[i - 1] ?? "";
+			const next = command[i + 1] ?? "";
+			if (next === ">" || next === "&" || prev === ">" || prev === "<" || prev === "&" || /[0-9]/.test(prev)) {
+				i++;
+				continue;
+			}
+			const tok = nextToken(command, i + 1);
+			if (tok !== null) {
+				targets.push(tok.token);
+				i = tok.end;
+				continue;
+			}
+			i++;
+			continue;
+		}
+		i++;
+	}
+	return targets.slice(0, MAX_CANDIDATES_PER_COMMAND);
+}
+/**
+* Expand one raw target token into an absolute host path. Strips quotes,
+* expands a leading `~` and `$VAR`/`${VAR}` from the given environment, and
+* resolves a relative target against the session cwd. Rejects anything that
+* cannot be a literal path: glob metacharacters, command substitution, an
+* unset variable (rather than guessing a truncated path), or a relative
+* target with no cwd to anchor it.
+* @param token - a raw target from {@link extractWriteTargets}.
+* @param env - the host environment (the collector runs in the host process,
+*   so `$DSH_HOME`-style variables resolve here, not in the fold).
+* @param home - the host home directory for `~`.
+* @param cwd - the owning session's cwd for relative targets, or undefined.
+* @returns the absolute path, or null when the token is not statable literally.
+*/
+function expandShellPath(token, env, home, cwd) {
+	let t = stripQuotes(token);
+	if (t.length === 0) return null;
+	if (/[*?[\]{}]/.test(t.replace(/\$\{[A-Za-z_][A-Za-z0-9_]*\}/g, ""))) return null;
+	if (t.includes("$(") || t.includes("`")) return null;
+	if (t.startsWith("~")) t = home + t.slice(1);
+	const varPattern = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+	let match;
+	while ((match = varPattern.exec(t)) !== null) {
+		const name = match[1] ?? match[2];
+		if (name === void 0 || env[name] === void 0) return null;
+	}
+	t = t.replace(varPattern, (_, braced, bare) => env[braced ?? bare ?? ""] ?? "");
+	if (t.length === 0) return null;
+	if (t.startsWith("/")) return t;
+	if (cwd === void 0 || cwd.length === 0) return null;
+	return resolve(cwd, t);
+}
+/** Parse a tool-call arguments JSON payload into a plain object ({} on failure). */
+function parseArguments(argumentsJson) {
+	try {
+		const value = JSON.parse(argumentsJson);
+		return value !== null && typeof value === "object" ? value : {};
+	} catch {
+		return {};
+	}
+}
+/**
+* Per-session registry of bash-written files. Subscribes to the session event
+* firehose: `tool/call` (bash) records the command's write candidates keyed by
+* callId; the matching `tool/result` stat-verifies them (files must exist and
+* be files — prefer a miss over a false positive) and stores the survivors.
+* `session/created` replays the session's own history so a restarted host
+* regains captures without any durable state of its own.
+*/
+var BashWriteCollector = class {
+	#fs;
+	#env;
+	#home;
+	#maxFiles;
+	/** sessionId → callId → pending bash write candidates. */
+	#pending = /* @__PURE__ */ new Map();
+	/** sessionId → path → verified capture. */
+	#captured = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.#fs = options.fs;
+		this.#env = options.env ?? process.env;
+		this.#home = options.home ?? homedir();
+		this.#maxFiles = options.maxFiles ?? 500;
+	}
+	/**
+	* Subscribe to the session feed; the returned disposer removes both
+	* listeners (fiber disposal also cleans them up — this is belt and braces).
+	* @param ctx - the owning composition context.
+	* @returns a disposer removing the listeners.
+	*/
+	attach(ctx) {
+		const offs = [ctx.on("session/event", (session, event) => {
+			this.#onEvent(session, event);
+		}), ctx.on("session/created", (session) => {
+			this.#replay(session);
+		})];
+		return () => {
+			for (const off of offs) if (typeof off === "function") off();
+		};
+	}
+	/** Verified captures for one session (the fold-merge source), or undefined. */
+	captured(sessionId) {
+		return this.#captured.get(sessionId);
+	}
+	/** Rebuild one session's registry from its own history (host restart). */
+	#replay(session) {
+		this.#pending.set(session.id, /* @__PURE__ */ new Map());
+		this.#captured.set(session.id, /* @__PURE__ */ new Map());
+		for (const event of session.events) this.#onEvent(session, event);
+	}
+	#onEvent(session, event) {
+		if (event.type === "tool/call") {
+			if (event.data.name !== "bash") return;
+			const command = parseArguments(event.data.arguments).command;
+			if (typeof command !== "string" || command.length === 0) return;
+			const candidates = extractWriteTargets(command).map((token) => expandShellPath(token, this.#env, this.#home, session.header.cwd)).filter((path) => path !== null);
+			if (candidates.length === 0) return;
+			const calls = this.#pending.get(session.id) ?? /* @__PURE__ */ new Map();
+			calls.set(String(event.data.callId), {
+				turn: event.data.turn,
+				step: event.data.step,
+				seq: event.seq,
+				candidates
+			});
+			this.#pending.set(session.id, calls);
+			return;
+		}
+		if (event.type === "tool/result") {
+			const calls = this.#pending.get(session.id);
+			if (calls === void 0) return;
+			const callId = String(event.data.message?.source?.callId ?? "");
+			const pending = calls.get(callId);
+			if (pending === void 0) return;
+			calls.delete(callId);
+			return this.#verify(session, pending);
+		}
+	}
+	/** stat-verify the pending candidates and store the survivors. */
+	async #verify(session, pending) {
+		const captured = this.#captured.get(session.id) ?? /* @__PURE__ */ new Map();
+		for (const candidate of pending.candidates) {
+			if (captured.size >= this.#maxFiles || captured.has(candidate)) continue;
+			let ok = false;
+			try {
+				const target = await this.#fs.resolve(candidate);
+				ok = (await this.#fs.stat(target))?.type === "file";
+			} catch {
+				ok = false;
+			}
+			if (ok) captured.set(candidate, {
+				turn: pending.turn,
+				step: pending.step,
+				seq: pending.seq
+			});
+		}
+		if (captured.size > 0) this.#captured.set(session.id, captured);
+	}
+};
+//#endregion
+//#region lib/types/fold.js
+/** Pure log fold over the files a session read, wrote, or edited. @module @khorsheed/dsh-file-preview/fold */
+/** Tool names whose calls record a touched file path. */
+const FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
+	"read",
+	"write",
+	"edit"
+]);
+/** The argument key carrying the touched path (shared by all three file tools). */
+const FILE_PATH_ARGUMENT = "file_path";
+/**
+* Extract the touched path and operation from parsed file-tool arguments.
+* @param name - the tool name.
+* @param args - the parsed arguments payload (an object when well-formed).
+* @returns the touch target, or undefined when the call is not a file touch.
+*/
+function targetFromArguments(name, args) {
+	if (!FILE_TOOL_NAMES.has(name)) return void 0;
+	if (args !== null && typeof args === "object") {
+		const candidate = args[FILE_PATH_ARGUMENT];
+		if (typeof candidate === "string" && candidate.length > 0) return {
+			op: name,
+			path: candidate
+		};
+	}
+}
+/** Extract the touched path and operation from one tool call's raw arguments JSON. */
+function pathFromToolCall(name, argumentsJson) {
+	try {
+		return targetFromArguments(name, JSON.parse(argumentsJson));
+	} catch {
+		return;
+	}
+}
+/** Read the write/edit diff list out of a tool result's tool-private meta. */
+function diffsFromResultMeta(meta) {
+	if (meta === null || typeof meta !== "object") return void 0;
+	const diffs = meta.diffs;
+	if (!Array.isArray(diffs) || diffs.length === 0) return void 0;
+	const result = [];
+	for (const item of diffs) {
+		if (item === null || typeof item !== "object") return void 0;
+		const { path, oldText, newText } = item;
+		if (typeof path !== "string" || path.length === 0) return void 0;
+		if (typeof newText !== "string") return void 0;
+		if (oldText !== null && typeof oldText !== "string") return void 0;
+		result.push({
+			path,
+			oldText,
+			newText
+		});
+	}
+	return result;
+}
+/**
+* Fold a session's events into the files it read, wrote, or edited, in
+* first-seen order and deduplicated by display path; a later occurrence
+* refreshes the entry's op and location without moving it, and each write/edit
+* tool result appends its change's diff to the entry's `diffs` in event order.
+* Nested Code Mode file dispatches (`tool/code-dispatch` events) count too —
+* they carry no turn/step of their own, so the entry borrows the enclosing
+* root call's location.
+* @param events - the session's events in ascending seq order.
+* @param maxFiles - cap on returned entries; excess files are dropped in
+*   first-seen order after the cap is reached.
+* @returns the capped list plus the last scanned seq and the truncation flag.
+*/
+function foldFilePreview(events, maxFiles) {
+	const entries = /* @__PURE__ */ new Map();
+	/** Root tool/call locations, so nested code dispatches borrow their turn/step. */
+	const callSites = /* @__PURE__ */ new Map();
+	let asOfSeq = -1;
+	/** Upsert one touched path, refreshing a repeat in place and keeping its diffs. */
+	const record = (target, seq, turn, step) => {
+		const next = {
+			path: target.path,
+			op: target.op,
+			seq,
+			turn,
+			step,
+			diffs: []
+		};
+		const existing = entries.get(target.path);
+		if (existing === void 0 && entries.size >= maxFiles) return;
+		entries.set(target.path, existing === void 0 ? next : {
+			...existing,
+			...next,
+			diffs: existing.diffs
+		});
+	};
+	for (const event of events) {
+		asOfSeq = event.seq;
+		if (event.type === "tool/call") {
+			callSites.set(String(event.data.callId), {
+				turn: event.data.turn,
+				step: event.data.step
+			});
+			const target = pathFromToolCall(event.data.name, event.data.arguments);
+			if (target === void 0) continue;
+			record(target, event.seq, event.data.turn, event.data.step);
+			continue;
+		}
+		if (event.type === "tool/code-dispatch") {
+			if (event.data.isError) continue;
+			const target = targetFromArguments(event.data.name, event.data.arguments);
+			if (target === void 0) continue;
+			const site = callSites.get(String(event.data.rootCallId)) ?? {
+				turn: 0,
+				step: 0
+			};
+			record(target, event.seq, site.turn, site.step);
+			continue;
+		}
+		if (event.type === "tool/result") {
+			const diffs = diffsFromResultMeta(event.data.meta);
+			if (diffs === void 0) continue;
+			for (const diff of diffs) {
+				if (!entries.has(diff.path)) record({
+					op: "edit",
+					path: diff.path
+				}, event.seq, event.data.turn, event.data.step);
+				const entry = entries.get(diff.path);
+				if (entry === void 0) continue;
+				const change = {
+					seq: event.seq,
+					turn: event.data.turn,
+					step: event.data.step,
+					oldText: diff.oldText,
+					newText: diff.newText
+				};
+				entries.set(diff.path, {
+					...entry,
+					diffs: [...entry.diffs, change]
+				});
+			}
+		}
+	}
+	return {
+		entries: [...entries.values()].map((entry) => {
+			const last = entry.diffs[entry.diffs.length - 1];
+			return last === void 0 ? entry : {
+				...entry,
+				lastDiff: {
+					oldText: last.oldText,
+					newText: last.newText
+				}
+			};
+		}),
+		asOfSeq,
+		truncated: entries.size >= maxFiles
+	};
+}
+/** Lines in one diff text: a trailing newline terminates the last line rather than adding one. */
+function lineCount(text) {
+	if (text === "") return 0;
+	const lines = text.split("\n").length;
+	return text.endsWith("\n") ? lines - 1 : lines;
+}
+/** Sum two optional counts; unknown wins (any uncounted mutation reports no total). */
+function sumKnown(a, b) {
+	return a === void 0 || b === void 0 ? void 0 : a + b;
+}
+/** Extract the full written content from a `write` tool call's arguments JSON. */
+function contentFromWriteCall(argumentsJson) {
+	try {
+		const args = JSON.parse(argumentsJson);
+		if (args !== null && typeof args === "object") {
+			const content = args.content;
+			if (typeof content === "string") return content;
+		}
+	} catch {}
+}
+/** Read the tool-result block's call identity and failure flag off a result message. */
+function resultCallFacts(message) {
+	const block = message.content[0];
+	if (block?.type !== "tool-result" || typeof block.toolCallId !== "string") return void 0;
+	return {
+		callId: block.toolCallId,
+		isError: block.isError === true
+	};
+}
+/**
+* Fold a session's events into per-turn file-mutation maps — the turn card's
+* single source of truth. Unlike {@link foldFilePreview}, this does NOT dedupe
+* a path to its last occurrence: a file touched in two turns appears in BOTH
+* turn maps, so each turn's card lists exactly what that turn mutated.
+* write/edit calls register with their own turn; nested Code Mode dispatches
+* borrow the enclosing root call's turn (dispatch events carry none); a
+* `tool/result` whose presentation meta carries diffs registers its paths (the
+* render-intent vocabulary) with the result's turn, and per-turn line deltas
+* are summed from the diffs. A `write` whose result carries no diffs is a
+* create (the write tool records no diffs when the file had no prior content):
+* its full written content — read from the call arguments, which the log keeps
+* — is the added-line count, once per file per turn.
+*
+* Count discipline: a write/edit tool/call only registers the path's location
+* and never touches counts (its counted result follows); the first count
+* contribution for a turn+path is adopted verbatim, later ones accumulate per
+* field with unknown-wins — an uncounted mutation (a Code Mode dispatch, or a
+* diff whose side reports no prior content) poisons that field to undefined
+* rather than reporting a misleading partial.
+* @param events - the session's events in ascending seq order.
+* @returns turn → path → facts, in event order per turn.
+*/
+function foldFilePreviewByTurn(events) {
+	const byTurn = /* @__PURE__ */ new Map();
+	/** Root tool/call locations, so nested code dispatches borrow their turn/step. */
+	const callSites = /* @__PURE__ */ new Map();
+	/** Write-tool calls keyed by callId (create fallback; see {@link WriteCallFacts}). */
+	const writeCalls = /* @__PURE__ */ new Map();
+	/** Every path the session log has written/edited or diff-reported so far
+	*  (create discrimination: a first-touch write is a create). */
+	const sessionSeen = /* @__PURE__ */ new Set();
+	/** Turn+path keys that have received a line-count contribution. */
+	const counted = /* @__PURE__ */ new Set();
+	const countKey = (turn, path) => `${turn}:${path}`;
+	const turnMap = (turn) => {
+		let map = byTurn.get(turn);
+		if (map === void 0) {
+			map = /* @__PURE__ */ new Map();
+			byTurn.set(turn, map);
+		}
+		return map;
+	};
+	/** Upsert a path's location without touching its line counts: a write/edit
+	*  tool/call precedes its counted result, so it must neither wipe counts a
+	*  sibling mutation contributed nor adopt anything itself. */
+	const recordLocation = (path, turn, seq, step) => {
+		const map = turnMap(turn);
+		const existing = map.get(path);
+		map.set(path, existing === void 0 ? {
+			path,
+			seq,
+			step
+		} : {
+			...existing,
+			seq,
+			step
+		});
+	};
+	/** Apply one mutation's line-count contribution. The first contribution for
+	*  a turn+path is adopted verbatim (a count-less placeholder from a
+	*  preceding tool/call must not poison it); later contributions accumulate
+	*  per field with unknown-wins. `unknown` marks an uncountable mutation (a
+	*  Code Mode dispatch): it poisons both fields. */
+	const recordContribution = (path, turn, seq, step, added, removed, unknown) => {
+		const map = turnMap(turn);
+		const key = countKey(turn, path);
+		if (unknown) {
+			counted.add(key);
+			map.set(path, {
+				path,
+				seq,
+				step
+			});
+			return;
+		}
+		const existing = map.get(path);
+		if (!counted.has(key)) {
+			counted.add(key);
+			map.set(path, {
+				path,
+				seq,
+				step,
+				...added === void 0 ? {} : { added },
+				...removed === void 0 ? {} : { removed }
+			});
+			return;
+		}
+		const mergedAdded = added === void 0 ? void 0 : sumKnown(existing?.added, added);
+		const mergedRemoved = removed === void 0 ? void 0 : sumKnown(existing?.removed, removed);
+		map.set(path, {
+			path,
+			seq,
+			step,
+			...mergedAdded === void 0 ? {} : { added: mergedAdded },
+			...mergedRemoved === void 0 ? {} : { removed: mergedRemoved }
+		});
+	};
+	for (const event of events) {
+		if (event.type === "tool/call") {
+			callSites.set(String(event.data.callId), {
+				turn: event.data.turn,
+				step: event.data.step
+			});
+			const target = pathFromToolCall(event.data.name, event.data.arguments);
+			if (target === void 0) continue;
+			if (target.op === "write") {
+				const content = contentFromWriteCall(event.data.arguments);
+				if (content !== void 0) {
+					const firstTouch = !sessionSeen.has(target.path);
+					sessionSeen.add(target.path);
+					writeCalls.set(String(event.data.callId), {
+						path: target.path,
+						content,
+						firstTouch
+					});
+				}
+			}
+			recordLocation(target.path, event.data.turn, event.seq, event.data.step);
+			continue;
+		}
+		if (event.type === "tool/code-dispatch") {
+			if (event.data.isError) continue;
+			const target = targetFromArguments(event.data.name, event.data.arguments);
+			if (target === void 0) continue;
+			const site = callSites.get(String(event.data.rootCallId)) ?? {
+				turn: 0,
+				step: 0
+			};
+			sessionSeen.add(target.path);
+			recordContribution(target.path, site.turn, event.seq, site.step, void 0, void 0, true);
+			continue;
+		}
+		if (event.type === "tool/result") {
+			const diffs = diffsFromResultMeta(event.data.meta);
+			if (diffs !== void 0) {
+				for (const diff of diffs) {
+					sessionSeen.add(diff.path);
+					recordContribution(diff.path, event.data.turn, event.seq, event.data.step, lineCount(diff.newText), diff.oldText === null ? void 0 : lineCount(diff.oldText), false);
+				}
+				continue;
+			}
+			const call = resultCallFacts(event.data.message);
+			const write = call === void 0 ? void 0 : writeCalls.get(call.callId);
+			if (write === void 0 || !write.firstTouch || call?.isError === true) continue;
+			recordContribution(write.path, event.data.turn, event.seq, event.data.step, lineCount(write.content), 0, false);
+		}
+	}
+	return byTurn;
+}
+//#endregion
+//#region lib/types/reveal.js
+/**
+* Cross-platform native "show in folder, selecting the file" dispatch used by
+* the file-preview Remote's `reveal` method.
+*
+* The official host opener only opens a path with the default application —
+* it has no select-in-folder intent — so this plugin carries its own
+* shell-free dispatch: macOS `open -R` (Finder reveals and selects), Windows
+* `explorer /select,<path>` (Explorer reveals and selects), WSL translates the
+* path to the Windows spelling first, and desktop Linux tries the
+* select-capable file managers (`nautilus` / `dolphin` / `nemo` `--select`) in
+* order, falling back to the caller's parent-folder open when none is
+* installed. Every command runs through the official
+* `@deepseek-ai/dsh-native-command` runner — no shell, abort propagation.
+* @module @khorsheed/dsh-file-preview
+*/
+/** Whether one environment marker is set to a non-empty value. */
+function present(value) {
+	return value !== void 0 && value !== "";
+}
+/** Distinguish WSL from desktop Linux using its process and kernel markers. */
+function isWsl(internals) {
+	const env = internals.env ?? process.env;
+	if (present(env.WSL_DISTRO_NAME) || present(env.WSL_INTEROP)) return true;
+	return (internals.osRelease ?? release()).toLowerCase().includes("microsoft");
+}
+/** Desktop file managers with a documented `--select <path>` flag, tried in order. */
+const SELECT_FILE_MANAGERS = [
+	"nautilus",
+	"dolphin",
+	"nemo"
+];
+/**
+* Reveal one path in the host file manager, opening its folder and selecting
+* the path. Throws when the platform cannot select (no select-capable file
+* manager, unsupported platform) — the caller then opens the parent folder.
+* @param path - absolute path in the host's execution world (caller owns
+*   resolution, typically `FileSystem.processPath`).
+* @param signal - caller/connection lifetime; abort terminates the native command.
+* @param internals - platform and environment seam for deterministic tests.
+*/
+async function revealNativePath(path, signal, internals = {}) {
+	const platform = internals.platform ?? process.platform;
+	const run = internals.run ?? runNativeCommand;
+	if (platform === "linux" && isWsl(internals)) {
+		const translated = await run("wslpath", ["-w", path], signal);
+		signal.throwIfAborted();
+		const windowsPath = translated.stdout.replace(/[\r\n]+$/, "");
+		if (windowsPath === "") throw new Error("wslpath returned no Windows path");
+		await run("explorer.exe", [`/select,${windowsPath}`], signal);
+		return;
+	}
+	if (platform === "darwin") {
+		await run("open", ["-R", path], signal);
+		return;
+	}
+	if (platform === "win32") {
+		await run("explorer.exe", [`/select,${path}`], signal);
+		return;
+	}
+	if (platform === "linux") {
+		let lastError;
+		for (const manager of SELECT_FILE_MANAGERS) try {
+			await run(manager, ["--select", path], signal);
+			return;
+		} catch (error) {
+			lastError = error;
+		}
+		throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error("no select-capable file manager found");
+	}
+	throw new Error(`native path reveal is unsupported on ${platform}`);
+}
+//#endregion
+//#region lib/types/index.js
+/** Read-only file-preview Remote service over live sessions and the filesystem.
+* @module @khorsheed/dsh-file-preview
+*/
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) {
+			if (kind === "field") initializers.unshift(_);
+			else descriptor[key] = _;
+		}
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+/**
+* Register the 3d-artifact skill — the generation-side contract for
+* sandbox-runnable interactive 3D / digital-twin single-file HTML (self-
+* contained, zero runtime network, GLB-inline zero-fetch models). Pull-based
+* discovery: an agent whose task involves generating such an HTML page finds
+* the contract through the skill catalog — no per-session push notice.
+* Optional: compositions without the skill capability skip the registration.
+* A missing/malformed shipped SKILL.md degrades to a warning — a discovery
+* aid must never take a boot down; the pack-smoke test owns the file's
+* presence in the tarball.
+* @param ctx - plugin context.
+*/
+function registerArtifactSkill(ctx) {
+	const skills = ctx.get("skills");
+	if (skills === void 0) {
+		ctx.logger.warn("file-preview: skills capability absent — the 3d-artifact skill is not registered");
+		return;
+	}
+	try {
+		const skillFile = join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "3d-artifact", "SKILL.md");
+		const raw = readFileSync(skillFile, "utf8");
+		const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(raw);
+		const name = /^name: (.+)$/m.exec(match?.[1] ?? "")?.[1]?.trim();
+		const description = /^description: (.+)$/m.exec(match?.[1] ?? "")?.[1]?.trim();
+		const content = match?.[2];
+		if (match === null || name === void 0 || description === void 0 || content === void 0) {
+			ctx.logger.warn("file-preview: shipped SKILL.md is malformed — the 3d-artifact skill is not registered");
+			return;
+		}
+		ctx.effect(() => skills.register({
+			name,
+			description,
+			content
+		}));
+	} catch (error) {
+		ctx.logger.warn(`file-preview: shipped SKILL.md unreadable (${String(error)}) — the 3d-artifact skill is not registered`);
+	}
+}
+/** Extensions treated as binary without reading (their text decode is meaningless). */
+const BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+	".pdf",
+	".zip",
+	".gz",
+	".tar",
+	".7z",
+	".zstd",
+	".br",
+	".woff",
+	".woff2",
+	".ttf",
+	".otf",
+	".eot",
+	".wasm",
+	".node",
+	".dylib",
+	".so",
+	".dll",
+	".exe",
+	".kext",
+	".class",
+	".jar",
+	".pyc",
+	".sqlite",
+	".db",
+	".DS_Store",
+	".a",
+	".o"
+]);
+/** Image extensions served to the browser through the image route. */
+const IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".avif",
+	".bmp",
+	".ico",
+	".svg"
+]);
+/** MIME type per image extension for the image route's Content-Type header. */
+const IMAGE_MIME = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".bmp": "image/bmp",
+	".ico": "image/x-icon",
+	".svg": "image/svg+xml"
+};
+/** NUL bytes in decoded text mark a file as binary despite a successful decode. */
+function hasNulByte(content) {
+	return content.slice(0, 4096).includes("\0");
+}
+/** Detect a binary file from its display path extension. */
+function isBinaryPath(path) {
+	const dot = path.lastIndexOf(".");
+	return dot >= 0 && BINARY_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** Detect an image from its display path extension. */
+function isImagePath(path) {
+	const dot = path.lastIndexOf(".");
+	return dot >= 0 && IMAGE_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** HTML extensions served through the sandboxed render channel. */
+const HTML_EXTENSIONS = /* @__PURE__ */ new Set([".html", ".htm"]);
+/** Detect an HTML document from its display path extension. */
+function isHtmlPath(path) {
+	const dot = path.lastIndexOf(".");
+	return dot >= 0 && HTML_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** Best-effort scripted-HTML detection: any `<script>` tag, inline event
+*  handler (`on*="…"`), or `javascript:` URL marks the document as scripted.
+*  Only a hint for default-mode selection and warning — never a trust
+*  decision; the sandbox and the Tier1 CSP are the real boundary. The scan
+*  runs on the read content as delivered (a truncated read may miss markers
+*  in the tail; acceptable for a hint). */
+function isScriptedHtml(content) {
+	return /<\s*script[\s>]/i.test(content) || /\son[a-z]+\s*=/i.test(content) || /javascript:/i.test(content);
+}
+/** Stable error text for a failed read, without leaking backend internals. */
+function readErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* The `filePreview` Remote service: session-scoped read-only file inspection
+* for web surfaces. `list` is a pure fold over the session log (no filesystem
+* access); `read` resolves the path against the session cwd and serves current
+* text content through `ctx.fs` (or a browser URL for images), capped by
+* config. Image bytes ride a dedicated host route so the browser loads them
+* natively without bloating the RPC channel.
+*/
+let FilePreviewService = (() => {
+	let _classSuper = TypertRemoteService;
+	let _instanceExtraInitializers = [];
+	let _list_decorators;
+	let _turnFiles_decorators;
+	let _read_decorators;
+	let _reveal_decorators;
+	return class FilePreviewService extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_list_decorators = [Remote("list")];
+			_turnFiles_decorators = [Remote("turnFiles")];
+			_read_decorators = [Remote("read")];
+			_reveal_decorators = [Remote("reveal")];
+			__esDecorate(this, null, _list_decorators, {
+				kind: "method",
+				name: "list",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "list" in obj,
+					get: (obj) => obj.list
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _turnFiles_decorators, {
+				kind: "method",
+				name: "turnFiles",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "turnFiles" in obj,
+					get: (obj) => obj.turnFiles
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _read_decorators, {
+				kind: "method",
+				name: "read",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "read" in obj,
+					get: (obj) => obj.read
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _reveal_decorators, {
+				kind: "method",
+				name: "reveal",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "reveal" in obj,
+					get: (obj) => obj.reveal
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		static inject = ["fs"];
+		static Config = z.object({
+			maxReadBytes: z.natural().min(1).default(524288),
+			htmlMaxReadBytes: z.natural().min(1).default(4194304),
+			maxFiles: z.natural().min(1).default(500),
+			captureBashWrites: z.boolean().default(true)
+		});
+		/** URL prefix the image route answers under. */
+		static IMAGE_ROUTE = "/file-preview-image";
+		resolved = __runInitializers(this, _instanceExtraInitializers);
+		/** Whether a web server is present to host the image route; image reads
+		* answer `binary` without it (the headless face has no browser to serve). */
+		imageRoute;
+		/** The agents service when present (image route only; null headless). */
+		agents;
+		/** Native reveal runner; a constructor seam for deterministic tests. */
+		revealNative;
+		/** Bash-write collector (S2 seam), or undefined when disabled in config. */
+		collector;
+		/** Per-session by-turn fold cache, invalidated by the log watermark. */
+		turnCache = /* @__PURE__ */ new Map();
+		/**
+		* @param ctx - owning Cordis Context carrying `fs`; `webServer` and `agents`
+		*   are optional (the image route needs them, headless faces lack both).
+		* @param config - optional deployment tuning; defaults cap reads and lists,
+		*   and enable the bash-write collector.
+		* @param deps - test seam for the native reveal dispatch.
+		*/
+		constructor(ctx, config = {}, deps = {}) {
+			super(ctx, "filePreview");
+			this.resolved = {
+				maxReadBytes: config.maxReadBytes ?? 524288,
+				htmlMaxReadBytes: config.htmlMaxReadBytes ?? 4194304,
+				maxFiles: config.maxFiles ?? 500,
+				captureBashWrites: config.captureBashWrites ?? true
+			};
+			this.revealNative = deps.revealNative ?? revealNativePath;
+			if (config.captureBashWrites !== false) {
+				this.collector = new BashWriteCollector({
+					fs: this.fs,
+					maxFiles: this.resolved.maxFiles
+				});
+				ctx.effect(() => this.collector.attach(ctx), "file-preview: bash-write capture");
+			} else this.collector = void 0;
+			const webServer = ctx.get("webServer");
+			this.agents = ctx.get("agents");
+			this.imageRoute = webServer !== void 0 && this.agents !== void 0;
+			if (this.imageRoute && webServer !== void 0) ctx.effect(() => webServer.register({
+				kind: "prefix",
+				path: FilePreviewService.IMAGE_ROUTE,
+				/* v8 ignore next 2 -- the handler body is the request path; the
+				unit tests drive serveImage directly, the real server reaches it
+				through this registration */
+				handler: (req, res) => {
+					this.serveImage(req, res);
+				}
+			}), "file-preview: image route");
+			registerArtifactSkill(ctx);
+		}
+		get fs() {
+			return this.ctx.fs;
+		}
+		/**
+		* Serve one image file's bytes for a browser `<img>` request. The URL is
+		* `IMAGE_ROUTE/<sessionId>/<encodeURIComponent(path)>`; the session must be
+		* live (the same scope `read` serves) and the path resolves against its cwd.
+		* @param req - the incoming image request.
+		* @param res - the response to fill with bytes or an error status.
+		*/
+		async serveImage(req, res) {
+			const rest = (req.url === void 0 ? "" : req.url.split("?")[0] ?? "").slice(FilePreviewService.IMAGE_ROUTE.length + 1);
+			const slash = rest.indexOf("/");
+			if (slash <= 0) {
+				res.writeHead(400).end("file preview: expected /<sessionId>/<path>");
+				return;
+			}
+			const sessionId = rest.slice(0, slash);
+			const encoded = rest.slice(slash + 1);
+			let display;
+			try {
+				display = decodeURIComponent(encoded);
+			} catch {
+				res.writeHead(400).end("file preview: malformed path");
+				return;
+			}
+			const agent = this.agents?.get(sessionId);
+			if (agent === void 0) {
+				res.writeHead(404).end("file preview: session not found");
+				return;
+			}
+			if (!isImagePath(display)) {
+				res.writeHead(400).end("file preview: not an image path");
+				return;
+			}
+			const cwd = agent.session.header.cwd;
+			let target;
+			try {
+				target = await this.fs.resolve(display, cwd === void 0 ? {} : { cwd });
+			} catch (error) {
+				res.writeHead(404).end(readErrorMessage(error));
+				return;
+			}
+			let info;
+			try {
+				info = await this.fs.stat(target);
+			} catch (error) {
+				res.writeHead(404).end(readErrorMessage(error));
+				return;
+			}
+			if (info === void 0 || info.type !== "file") {
+				res.writeHead(404).end("file preview: not a file");
+				return;
+			}
+			if (info.size !== void 0 && info.size > this.resolved.maxReadBytes) {
+				res.writeHead(413).end("file preview: image exceeds the read cap");
+				return;
+			}
+			let bytes;
+			try {
+				bytes = await this.fs.readBytes(target, void 0, this.resolved.maxReadBytes);
+			} catch (error) {
+				res.writeHead(404).end(readErrorMessage(error));
+				return;
+			}
+			const dot = display.lastIndexOf(".");
+			/* v8 ignore next -- every IMAGE_EXTENSIONS entry has a MIME mapping; the fallback guards a future extension */
+			const mime = IMAGE_MIME[display.slice(dot).toLowerCase()] ?? "application/octet-stream";
+			res.writeHead(200, {
+				"Content-Type": mime,
+				"Cache-Control": "no-store"
+			});
+			res.end(Buffer.from(bytes));
+		}
+		/**
+		* List the files one session wrote or edited: the log fold plus any
+		* bash-written files the collector verified (the S2 seam), merged so a
+		* captured path the fold already knows keeps its log-derived entry.
+		* @param agent - owning live agent; its session log is the data source.
+		* @returns first-seen files capped by `maxFiles`, with the log watermark.
+		*/
+		list(agent) {
+			const folded = foldFilePreview(agent.session.events, this.resolved.maxFiles);
+			const captured = this.collector?.captured(agent.session.id);
+			if (captured === void 0 || captured.size === 0) return folded;
+			const seen = new Set(folded.entries.map((entry) => entry.path));
+			const extra = [];
+			for (const [path, write] of captured) {
+				if (seen.has(path) || folded.entries.length + extra.length >= this.resolved.maxFiles) continue;
+				extra.push({
+					path,
+					op: "write",
+					seq: write.seq,
+					turn: write.turn,
+					step: write.step,
+					diffs: []
+				});
+			}
+			if (extra.length === 0) return folded;
+			return {
+				entries: [...folded.entries, ...extra],
+				asOfSeq: folded.asOfSeq,
+				truncated: folded.truncated || folded.entries.length + extra.length >= this.resolved.maxFiles
+			};
+		}
+		/**
+		* Every turn's file mutations for the turn-tail card — the single source of
+		* truth the card renders (the client's old write/edit-only fold retired).
+		* Built by folding the session log per turn (write/edit calls, Code Mode
+		* dispatches borrowing the root call's turn, and render-intent paths from
+		* result diff meta) and merging the collector's bash-written captures by
+		* their own turn. The fold is cached per session and invalidated by the log
+		* watermark, so repeated card fetches do not refold. A path touched in two
+		* turns appears in BOTH turn groups — per-turn attribution is exact.
+		* @param agent - owning live agent; its session log is the data source.
+		* @returns per-turn file groups plus the scanned watermark.
+		*/
+		turnFiles(agent) {
+			const session = agent.session;
+			const events = session.events;
+			const asOfSeq = events.length === 0 ? -1 : events[events.length - 1].seq;
+			const cached = this.turnCache.get(session.id);
+			let byTurn;
+			if (cached === void 0 || cached.asOfSeq !== asOfSeq) {
+				byTurn = foldFilePreviewByTurn(events);
+				this.turnCache.set(session.id, {
+					asOfSeq,
+					byTurn
+				});
+			} else byTurn = cached.byTurn;
+			const captured = this.collector?.captured(session.id);
+			const turns = [];
+			const turnNumbers = new Set(byTurn.keys());
+			if (captured !== void 0) for (const write of captured.values()) turnNumbers.add(write.turn);
+			for (const turn of [...turnNumbers].sort((a, b) => a - b)) {
+				const files = [];
+				const map = byTurn.get(turn);
+				if (map !== void 0) files.push(...map.values());
+				if (captured !== void 0) for (const [path, write] of captured) {
+					if (write.turn !== turn || files.some((file) => file.path === path)) continue;
+					files.push({
+						path,
+						seq: write.seq,
+						step: write.step
+					});
+				}
+				if (files.length === 0) continue;
+				turns.push({
+					turn,
+					files: files.sort((a, b) => a.seq - b.seq)
+				});
+			}
+			return {
+				turns,
+				asOfSeq
+			};
+		}
+		/**
+		* Read the current content of one recorded file, resolved against the
+		* session cwd and capped by `maxReadBytes`.
+		* @param agent - owning live agent; its session cwd anchors relative paths.
+		* @param path - the display path recorded by the write/edit tool call.
+		* @param signal - cooperative cancellation from the calling UI request.
+		* @returns the classified read; `text` carries content, `image` carries a
+		*   browser URL, other kinds carry the size or a human-readable reason.
+		*/
+		async read(agent, path, signal) {
+			if (typeof path !== "string" || path.length === 0) return {
+				path,
+				kind: "error",
+				message: "file preview requires a non-empty path"
+			};
+			const cwd = agent.session.header.cwd;
+			let target;
+			try {
+				target = await this.fs.resolve(path, cwd === void 0 ? { signal } : {
+					cwd,
+					signal
+				});
+			} catch (error) {
+				return {
+					path,
+					kind: "error",
+					message: readErrorMessage(error)
+				};
+			}
+			let info;
+			try {
+				info = await this.fs.stat(target, signal);
+			} catch (error) {
+				return {
+					path,
+					kind: "error",
+					message: readErrorMessage(error)
+				};
+			}
+			if (info === void 0 || info.type !== "file") return {
+				path,
+				kind: "missing"
+			};
+			const html = isHtmlPath(path);
+			const cap = html ? this.resolved.htmlMaxReadBytes : this.resolved.maxReadBytes;
+			if (info.size !== void 0 && info.size > cap) return {
+				path,
+				kind: "too-large",
+				size: info.size
+			};
+			if (isImagePath(path)) {
+				if (this.imageRoute) {
+					const encoded = encodeURIComponent(path);
+					return {
+						path,
+						kind: "image",
+						url: `${FilePreviewService.IMAGE_ROUTE}/${agent.session.id}/${encoded}`,
+						...info.size === void 0 ? {} : { size: info.size }
+					};
+				}
+				return {
+					path,
+					kind: "binary",
+					...info.size === void 0 ? {} : { size: info.size }
+				};
+			}
+			if (isBinaryPath(path)) return {
+				path,
+				kind: "binary",
+				...info.size === void 0 ? {} : { size: info.size }
+			};
+			try {
+				const content = await this.fs.readText(target, signal);
+				if (hasNulByte(content)) return {
+					path,
+					kind: "binary",
+					...info.size === void 0 ? {} : { size: info.size }
+				};
+				const truncated = content.length > cap;
+				return {
+					path,
+					kind: "text",
+					content: truncated ? content.slice(0, cap) : content,
+					truncated,
+					...html && isScriptedHtml(content) ? { htmlScripted: true } : {},
+					...info.size === void 0 ? {} : { size: info.size }
+				};
+			} catch (error) {
+				return {
+					path,
+					kind: "error",
+					message: readErrorMessage(error)
+				};
+			}
+		}
+		/**
+		* Reveal one recorded file in the host file manager — open its folder and
+		* select the file (macOS Finder, Windows Explorer, or a select-capable
+		* desktop file manager). The display path resolves against the session cwd;
+		* the native reveal runs on the host. A path that does not resolve to an
+		* existing target, or a platform that cannot select, answers `revealed:
+		* false` and the caller opens the parent folder instead (the pre-reveal
+		* "show in folder" behavior), so the gesture always lands somewhere visible.
+		* @param agent - owning live agent; its session cwd anchors relative paths.
+		* @param path - the display path recorded by the read/write/edit tool call.
+		* @param signal - cooperative cancellation from the calling UI request.
+		* @returns whether the file manager selected the file, or why not.
+		*/
+		async reveal(agent, path, signal) {
+			if (typeof path !== "string" || path.length === 0) return {
+				revealed: false,
+				reason: "missing"
+			};
+			const cwd = agent.session.header.cwd;
+			let target;
+			try {
+				target = await this.fs.resolve(path, cwd === void 0 ? { signal } : {
+					cwd,
+					signal
+				});
+			} catch (error) {
+				return {
+					revealed: false,
+					reason: "missing"
+				};
+			}
+			let info;
+			try {
+				info = await this.fs.stat(target, signal);
+			} catch {
+				info = void 0;
+			}
+			if (info === void 0) return {
+				revealed: false,
+				reason: "missing"
+			};
+			try {
+				await this.revealNative(this.fs.processPath(target), signal);
+				return { revealed: true };
+			} catch {
+				return {
+					revealed: false,
+					reason: "select-failed"
+				};
+			}
+		}
+	};
+})();
+//#endregion
+export { FilePreviewService, FilePreviewService as default };