better-dsh 0.2.3 → 0.2.4

package/lib/wrap-JFjcWwZf.js

@@ -0,0 +1,747 @@
+import { promises, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/url-schemes/catalog.ts
+/**
+* The scheme set, in declaration order.
+*
+* `paths` mirrors each handler's own path parsing, not an idealised grammar:
+* `dvc://` addresses a device by its FIRST segment only (a trailing `/sub` is
+* parsed and then dropped), and `ctx://` addresses collection elements with a
+* `[n]` bracket that lives in the *path*, not in the selector.
+*/
+const SCHEME_CATALOGUE = [
+	{
+		names: ["skill"],
+		display: "skill://",
+		paths: "skill://<name>[/<file>]",
+		purpose: "a registered skill's files",
+		example: "skill://<name>/SKILL.md",
+		write: "read-only"
+	},
+	{
+		names: ["agent"],
+		display: "agent://",
+		paths: "agent://[<id>[/transcript]]",
+		purpose: "agent roster / a LIVE agent transcript",
+		example: "agent://<id>/transcript:1-40",
+		write: "read-only"
+	},
+	{
+		names: ["dsh"],
+		display: "dsh://",
+		paths: "dsh://docs[/<doc>] · dsh://config",
+		purpose: "harness docs / live resolved config",
+		example: "dsh://config:path/agent-loop.maxParallelToolCalls",
+		write: "read-only"
+	},
+	{
+		names: ["ctx"],
+		display: "ctx://",
+		paths: "ctx://session/<face>",
+		purpose: "THIS session's own log; face ∈ transcript, compactions, thinking, system, user_prompts[n], tool_calls[n], agent_responses[n]",
+		example: "ctx://session/tool_calls[0]",
+		write: "read-only",
+		selector: "`:raw` | `:N-M[,N2-M2]` | `:raw:N-M` (composite ≡ `:N-M`); `[n]` is path syntax (0-based ordinal or event seq)"
+	},
+	{
+		names: ["dvc"],
+		display: "dvc://",
+		paths: "dvc://[<device>]",
+		purpose: "device registry; `write dvc://<device>` with JSON args RUNS it",
+		example: "dvc://ast_grep",
+		write: "json-args"
+	},
+	{
+		names: ["http", "https"],
+		display: "http(s)://",
+		paths: "http(s)://<host>/<path>",
+		purpose: "plain fetch",
+		example: "https://example.com",
+		write: "read-only",
+		selector: "exempt — the whole remainder is the path (`:8443` port, `?x=1` query)"
+	}
+];
+/** Every registered scheme token, sorted — the list error messages report. */
+const SCHEME_NAMES = SCHEME_CATALOGUE.flatMap((doc) => doc.names).sort();
+/** The schemes as display tokens (`skill://`, `http(s)://`, …) — prose + error messages. */
+const SCHEME_DISPLAYS = SCHEME_CATALOGUE.map((doc) => doc.display);
+/** Number of schemes with no write channel (every entry except `dvc://`). */
+const READ_ONLY_SCHEME_COUNT = SCHEME_CATALOGUE.filter((doc) => doc.write === "read-only").length;
+
+//#endregion
+//#region src/url-schemes/selector.ts
+/** Structured error thrown by the URL-schema layer. */
+var UrlSchemesError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "UrlSchemesError";
+		this.code = code;
+	}
+};
+/** Matches `scheme://rest` with a lowercase alphanumeric scheme. */
+const SCHEME_RE = /^([a-z][a-z0-9]*):\/\/(.*)$/;
+/** One line range token: `N`, `N-M`, or open `N-`. */
+const RANGE_RE = /^(\d+)(?:-(\d*))?$/;
+/**
+* Schemes whose URL syntax reserves `:` and `?` (ports, query strings): the
+* whole remainder is the path and NO selector is parsed. The http(s) handler
+* is documented as selector-free for exactly this reason — `:8443` is a port
+* and `?q=` a server query, never a line range or content filter.
+*/
+const SELECTOR_EXEMPT = {
+	http: true,
+	https: true
+};
+/**
+* Parse a `scheme://` URL into `{ scheme, path, selector }`.
+*
+* Throws a structured {@link UrlSchemesError} (code `URL_NO_SCHEME`) when the
+* URL has no `scheme://` prefix. Any lowercase scheme is accepted here; the
+* resolver rejects schemes with no registered handler. Selector-exempt
+* schemes ({@link SELECTOR_EXEMPT}) return the whole remainder as the path.
+*/
+function parseUrl(raw) {
+	const m = SCHEME_RE.exec(raw);
+	if (m === null) throw new UrlSchemesError("URL_NO_SCHEME", `URL "${raw}" has no scheme — expected "scheme://" (${SCHEME_DISPLAYS.join(", ")})`);
+	const scheme = m[1];
+	const rest = m[2];
+	if (SELECTOR_EXEMPT[scheme] === true) return {
+		scheme,
+		path: rest,
+		selector: null
+	};
+	const colon = rest.indexOf(":");
+	const question = rest.indexOf("?");
+	const hasColon = colon !== -1;
+	const hasQuestion = question !== -1;
+	if (!hasColon && !hasQuestion) return {
+		scheme,
+		path: rest,
+		selector: null
+	};
+	const isQuery = hasQuestion && (!hasColon || question < colon);
+	const marker = isQuery ? question : colon;
+	const path = rest.slice(0, marker);
+	const selPart = rest.slice(marker + 1);
+	return {
+		scheme,
+		path,
+		selector: isQuery ? {
+			kind: "query",
+			q: selPart.startsWith("q=") ? selPart.slice(2) : selPart
+		} : parseColonSelector(selPart)
+	};
+}
+/** `:raw`, composite `:raw:N-M`, `:path/<subpath>`, or a `:N-M` line range list. */
+function parseColonSelector(selPart) {
+	if (selPart === "raw") return { kind: "raw" };
+	if (selPart.startsWith("raw:")) return {
+		kind: "lines",
+		ranges: parseRanges(selPart.slice(4))
+	};
+	if (selPart.startsWith("path/")) return {
+		kind: "path",
+		value: selPart.slice(5)
+	};
+	return {
+		kind: "lines",
+		ranges: parseRanges(selPart)
+	};
+}
+/** `N`, `N-M`, `N-`, comma-separated → `[[start, end], ...]` (1-based). */
+function parseRanges(spec) {
+	return spec.split(",").map((part) => {
+		const token = part.trim();
+		const m = RANGE_RE.exec(token);
+		if (m === null) throw new UrlSchemesError("URL_BAD_SELECTOR", `invalid line selector ":${spec}" — expected N, N-M, or N-M,N2-M2`);
+		const start = Number(m[1]);
+		if (start < 1) throw new UrlSchemesError("URL_BAD_SELECTOR", `line numbers are 1-based — got ${start} in ":${spec}"`);
+		const end = m[2] === void 0 ? start : m[2] === "" ? Infinity : Number(m[2]);
+		if (end !== Infinity && end < start) throw new UrlSchemesError("URL_BAD_SELECTOR", `line range ${start}-${end} is empty — end must be >= start`);
+		return [start, end];
+	});
+}
+/**
+* Apply a selector to already-resolved text.
+*
+* `null` and `{ kind: 'raw' }` return the text unchanged. `lines` performs a
+* 1-based inclusive slice (open tail via `Infinity`). `path` navigates a JSON
+* sub-resource by dot-path. `query` navigates JSON by dot-path when the text
+* parses as JSON, and otherwise keeps the lines containing the query string.
+*/
+function applySelector(text, sel) {
+	if (sel === null) return text;
+	switch (sel.kind) {
+		case "raw": return text;
+		case "lines": return applyLines(text, sel.ranges);
+		case "path": return applyPath(text, sel.value);
+		case "query": return applyQuery(text, sel.q);
+	}
+}
+/** 1-based inclusive line slicing; `Infinity` end = open tail. */
+function applyLines(text, ranges) {
+	if (ranges.length === 0) return "";
+	const lines = text.split("\n");
+	const out = [];
+	for (const [startRaw, endRaw] of ranges) {
+		const start = Math.max(1, startRaw);
+		const end = endRaw === Infinity ? lines.length : Math.min(lines.length, endRaw);
+		if (start <= end) out.push(...lines.slice(start - 1, end));
+	}
+	return out.join("\n");
+}
+/** Navigate a JSON sub-resource by dot-path; non-JSON text passes through. */
+function applyPath(text, value) {
+	if (value === "") return text;
+	const parsed = tryParseJson(text);
+	if (parsed === void 0) return text;
+	const node = navigate(parsed, value);
+	return node === void 0 ? text : stringifyNode(node);
+}
+/** JSON dot-path query when the text is JSON, else a substring line filter. */
+function applyQuery(text, q) {
+	if (q === "") return text;
+	const parsed = tryParseJson(text);
+	if (parsed !== void 0) {
+		const node = navigate(parsed, q);
+		return node === void 0 ? text.split("\n").filter((line) => line.includes(q)).join("\n") : stringifyNode(node);
+	}
+	return text.split("\n").filter((line) => line.includes(q)).join("\n");
+}
+function tryParseJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+/** Walk a dot-path through a parsed JSON value (numeric segments index arrays). */
+function navigate(node, path) {
+	let current = node;
+	for (const segment of path.split(".")) {
+		if (segment === "") return void 0;
+		if (Array.isArray(current)) {
+			const idx = Number(segment);
+			if (!Number.isInteger(idx) || idx < 0) return void 0;
+			current = current[idx];
+		} else if (current !== null && typeof current === "object") current = current[segment];
+		else return;
+	}
+	return current;
+}
+/** Render a navigated leaf as text. */
+function stringifyNode(node) {
+	if (typeof node === "string") return node;
+	try {
+		return JSON.stringify(node) ?? "";
+	} catch {
+		return String(node);
+	}
+}
+
+//#endregion
+//#region src/url-schemes/handlers/dvc.ts
+/** Module-level device registry: insertion-ordered, shared by every handler instance. */
+const devices = /* @__PURE__ */ new Map();
+/** Register (or replace) the device mounted under `name`. */
+function registerDvcDevice(name, device) {
+	devices.set(name, device);
+}
+/** Read-only view of the registered devices, in registration order. */
+function listDvcDevices() {
+	return devices;
+}
+/**
+* The first path segment is the device name (`dvc://name`, `dvc://name/sub`).
+* A leading `dvc://` is tolerated so callers may pass either the parsed path
+* (the write tool's contract) or the full URL.
+*/
+/** Subpath after the device name (`status`, `diagnostics?file=…`), or undefined. */
+function subpathOf(path) {
+	const trimmed = (path.startsWith("dvc://") ? path.slice(6) : path).replace(/^\/+/, "");
+	const slash = trimmed.indexOf("/");
+	if (slash === -1) return void 0;
+	const sub = trimmed.slice(slash + 1);
+	return sub === "" ? void 0 : sub;
+}
+function deviceNameFromPath(path) {
+	const trimmed = (path.startsWith("dvc://") ? path.slice(6) : path).replace(/^\/+/, "");
+	const slash = trimmed.indexOf("/");
+	return slash === -1 ? trimmed : trimmed.slice(0, slash);
+}
+/** Uniform `unknown`-error rendering for structured error messages. */
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Build the `dvc://` scheme handler over the module-level device registry.
+* Bare `dvc://` yields the roster (`no devices mounted` while empty); a
+* registered `<device>` yields its summary plus a usage hint; an unregistered
+* name keeps the `unknown device` placeholder text.
+*/
+function createDvcHandler(_deps = {}) {
+	return {
+		selectorAware: true,
+		async resolve(_env, path, selector) {
+			const name = deviceNameFromPath(path);
+			if (name === "") {
+				if (devices.size === 0) return "no devices mounted";
+				return applySelector([...devices].map(([n, device$1]) => `${n}\t${device$1.summary}`).join("\n"), selector ?? null);
+			}
+			const device = devices.get(name);
+			if (device === void 0) return `unknown device: ${name}`;
+			const subpath = subpathOf(path);
+			if (subpath !== void 0 && device.read !== void 0) {
+				const query = selector?.kind === "query" ? `?${selector.q}` : "";
+				let text;
+				try {
+					text = await device.read(`${subpath}${query}`, _env.agent?.id);
+				} catch (error) {
+					return `Error: ${error instanceof Error ? error.message : String(error)}`;
+				}
+				return selector !== void 0 && selector !== null && selector.kind !== "query" ? applySelector(text, selector) : text;
+			}
+			if (subpath !== void 0) return `unknown read path dvc://${name}/${subpath} (device serves doc only)`;
+			return applySelector(`${device.summary}\nusage: write dvc://${name} with a JSON args object to execute this device`, selector ?? null);
+		}
+	};
+}
+/**
+* Write dispatch for `dvc://` URLs — called by the write tool's URL branch.
+* `path` addresses the device (parsed path or full `dvc://` URL); `content`
+* must be the JSON args payload.
+*
+* Routing and args failures (`DVC_NO_DEVICE`, `DVC_UNKNOWN_DEVICE`,
+* `DVC_BAD_ARGS`) throw synchronously — the placeholder wave's observable
+* contract — while a device-reported failure rejects the returned promise as
+* `DVC_DEVICE_ERROR` carrying the device name.
+*/
+function dispatchDvcWrite(path, content, session) {
+	if (devices.size === 0) throw new UrlSchemesError("DVC_NO_DEVICE", "dvc:// write dispatch: no devices mounted to route the write to");
+	const name = deviceNameFromPath(path);
+	const device = devices.get(name);
+	if (device === void 0) throw new UrlSchemesError("DVC_UNKNOWN_DEVICE", `dvc:// write dispatch: no device named "${name}" (registered: ${[...devices.keys()].sort().join(", ")})`);
+	let args;
+	try {
+		args = JSON.parse(content);
+	} catch (error) {
+		throw new UrlSchemesError("DVC_BAD_ARGS", `dvc:// write dispatch: device "${name}" requires a JSON args payload (${messageOf(error)})`);
+	}
+	if (session !== void 0 && args !== null && typeof args === "object" && !Array.isArray(args)) args = { ...args };
+	return Promise.resolve().then(() => device.execute(args, { session })).catch((error) => {
+		throw new UrlSchemesError("DVC_DEVICE_ERROR", `dvc:// device "${name}" execute failed: ${messageOf(error)}`);
+	});
+}
+
+//#endregion
+//#region src/url-schemes/docs-dir.ts
+function resolveDocsDir() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		for (const name of ["dsh-docs", "docs"]) {
+			const candidate = join(dir, name);
+			try {
+				if (statSync(candidate).isDirectory()) return candidate;
+			} catch {}
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+}
+
+//#endregion
+//#region src/url-schemes/resolver.ts
+/** Scheme→handler registry that resolves `scheme://` URLs end-to-end. */
+var UrlResolver = class {
+	handlers = /* @__PURE__ */ new Map();
+	/** Register (or replace) the handler for `scheme`. */
+	register(scheme, handler) {
+		this.handlers.set(scheme, handler);
+	}
+	/**
+	* Resolve a `scheme://` URL to its selected text: parse the URL, dispatch
+	* to the registered handler for the scheme, then apply the selector.
+	*
+	* Throws a structured {@link UrlSchemesError} for a scheme-less URL
+	* (`URL_NO_SCHEME`, from {@link parseUrl}) or an unregistered scheme
+	* (`URL_UNREGISTERED_SCHEME`).
+	*/
+	async resolve(env, url) {
+		const parsed = parseUrl(url);
+		const handler = this.handlers.get(parsed.scheme);
+		if (handler === void 0) {
+			const registered = [...this.handlers.keys()].sort().join(", ");
+			throw new UrlSchemesError("URL_UNREGISTERED_SCHEME", `no handler registered for scheme "${parsed.scheme}" (registered: ${registered || "none"})`);
+		}
+		if (handler.selectorAware === true) return handler.resolve(env, parsed.path, parsed.selector);
+		return applySelector(await handler.resolve(env, parsed.path), parsed.selector);
+	}
+	/**
+	* Resolve a `scheme://` URL to its on-disk path when its handler is
+	* path-backed: parse the URL, dispatch to the handler's optional
+	* `resolvePath`, and return the real disk location. Returns `undefined`
+	* for an unregistered scheme, a handler without `resolvePath`, or a path
+	* the handler cannot map — callers then fall back to text resolution
+	* (whose unregistered-scheme error is the structured generic one).
+	* Selectors are NOT applied: they operate on resolved text, not paths.
+	*/
+	async resolvePath(env, url) {
+		const parsed = parseUrl(url);
+		const handler = this.handlers.get(parsed.scheme);
+		if (handler?.resolvePath === void 0) return void 0;
+		return await handler.resolvePath(env, parsed.path);
+	}
+};
+
+//#endregion
+//#region src/url-schemes/handlers/dsh.ts
+/** File extensions considered readable harness documentation. */
+const DOC_EXTENSIONS = {
+	".md": true,
+	".markdown": true,
+	".txt": true
+};
+/**
+* Key-name patterns for the defensive secret denylist, matched against a
+* normalized key (lowercased, separators removed). Complements schema-declared
+* `role('secret')` redaction for fields a schema did not mark secret.
+*/
+const SECRET_KEY_PATTERNS = [
+	/secret/,
+	/password/,
+	/passwd/,
+	/credential/,
+	/token/,
+	/apikey/,
+	/authorization/,
+	/privatekey/,
+	/accesskey/
+];
+/** True when a settings field name names credentials/env/API-key material. */
+function isSecretKey(key) {
+	const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+	if (normalized === "env" || normalized === "environment") return true;
+	return SECRET_KEY_PATTERNS.some((re) => re.test(normalized));
+}
+/** Deep-copy a settings value, dropping every key the denylist names. */
+function stripSecrets(value) {
+	if (Array.isArray(value)) return value.map(stripSecrets);
+	if (value !== null && typeof value === "object") {
+		const out = {};
+		for (const [key, item] of Object.entries(value)) {
+			if (isSecretKey(key)) continue;
+			out[key] = stripSecrets(item);
+		}
+		return out;
+	}
+	return value;
+}
+/** True when `name` has a doc extension (case-insensitive). */
+function isDocFile(name) {
+	const dot = name.lastIndexOf(".");
+	if (dot === -1) return false;
+	return DOC_EXTENSIONS[name.slice(dot).toLowerCase()] === true;
+}
+/** Recursive, sorted list of readable doc paths relative to `dir`. */
+async function listDocs(dir) {
+	const out = [];
+	const entries = await promises.readdir(dir, { withFileTypes: true });
+	entries.sort((a, b) => a.name.localeCompare(b.name));
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) continue;
+		const abs = join(dir, entry.name);
+		if (entry.isDirectory()) for (const child of await listDocs(abs)) out.push(join(entry.name, child));
+		else if (isDocFile(entry.name)) out.push(entry.name);
+	}
+	return out;
+}
+/** Read one `<doc>` path inside `dir`, guarding against path traversal. */
+async function readDoc(dir, docPath) {
+	const abs = resolve(dir, docPath);
+	const rel = relative(dir, abs);
+	if (rel === "" || rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) throw new UrlSchemesError("URL_DOC_NOT_FOUND", `dsh://docs/${docPath}: path escapes the docs directory`);
+	let stat;
+	try {
+		stat = await promises.stat(abs);
+	} catch {
+		throw new UrlSchemesError("URL_DOC_NOT_FOUND", `dsh://docs/${docPath}: document not found`);
+	}
+	if (stat.isDirectory()) return JSON.stringify(await listDocs(abs), null, 2);
+	if (stat.isFile()) return await promises.readFile(abs, "utf8");
+	throw new UrlSchemesError("URL_DOC_NOT_FOUND", `dsh://docs/${docPath}: not a regular file`);
+}
+/** Create the `dsh://` scheme handler, capturing `deps` by closure. */
+function createDshHandler(deps) {
+	const { settings, docsDir } = deps;
+	let docsDirPromise;
+	function findDocsDir() {
+		if (docsDirPromise === void 0) docsDirPromise = (async () => {
+			const candidates = [];
+			if (docsDir !== void 0) candidates.push(docsDir);
+			const pkgRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
+			candidates.push(join(pkgRoot, "dsh-docs"), join(pkgRoot, "docs"), join(pkgRoot, "..", "docs"));
+			for (const dir of candidates) try {
+				if ((await promises.stat(dir)).isDirectory()) return dir;
+			} catch {}
+		})();
+		return docsDirPromise;
+	}
+	/**
+	* Path-backed view: `docs` and `docs/<sub>` map into the real docs tree, so
+	* the URL-aware `grep`/`glob` can hand the native tools a disk path instead
+	* of materializing the listing text. `config` is content-backed (resolved
+	* settings JSON) — never path-backed.
+	*/
+	async function resolvePathDisk(path) {
+		if (path !== "docs" && !path.startsWith("docs/")) return void 0;
+		const dir = await findDocsDir();
+		if (dir === void 0) return void 0;
+		const abs = path === "docs" ? dir : join(dir, path.slice(5));
+		try {
+			await promises.stat(abs);
+			return abs;
+		} catch {
+			return;
+		}
+	}
+	return {
+		async resolvePath(_env, path) {
+			return resolvePathDisk(path);
+		},
+		async resolve(_env, path) {
+			const [root, ...rest] = path.split("/");
+			const restPath = rest.join("/");
+			if (root === "docs") {
+				const dir = await findDocsDir();
+				if (dir === void 0) throw new UrlSchemesError("URL_DOCS_UNAVAILABLE", "dsh://docs: no docs directory found (provide `docsDir` to createDshHandler)");
+				if (restPath === "") return JSON.stringify(await listDocs(dir), null, 2);
+				return await readDoc(dir, restPath);
+			}
+			if (root === "config") {
+				if (settings === void 0) throw new UrlSchemesError("URL_SETTINGS_UNAVAILABLE", "dsh://config: no ctx.settings service is mounted");
+				const descriptors = settings.describe({ redactSecrets: true });
+				if (restPath === "") {
+					const out = {};
+					for (const descriptor of descriptors) out[String(descriptor.ns)] = stripSecrets(descriptor.value);
+					return JSON.stringify(out, null, 2);
+				}
+				const found = descriptors.find((descriptor) => String(descriptor.ns) === restPath);
+				if (found === void 0) throw new UrlSchemesError("URL_UNKNOWN_SETTINGS_NAMESPACE", `dsh://config/${restPath}: unknown settings namespace`);
+				return JSON.stringify(stripSecrets(found.value), null, 2);
+			}
+			throw new UrlSchemesError("URL_UNKNOWN_RESOURCE", `dsh://: unknown resource "${root || "(empty)"}" — expected "docs" or "config"`);
+		}
+	};
+}
+
+//#endregion
+//#region src/url-schemes/handlers/http.ts
+/** The schemes one handler instance serves; register it under each of these. */
+const HTTP_SCHEMES = ["http", "https"];
+/** Hard cap on a fetched body: 2 MiB. */
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+/** Abort the GET after this many milliseconds. */
+const TIMEOUT_MS = 2e4;
+/** First line of every resolved http(s) URL: flags plain-fetch semantics. */
+const DISCLAIMER = "[url-fetch] plain-text result of a direct HTTP GET (curl-equivalent). No JS execution or interaction — use browser tools, if any, for that.";
+/** `application/` MIME types treated as text (any `text/*` also is). */
+const APPLICATION_TEXT_TYPES = {
+	"application/json": true,
+	"application/xml": true,
+	"application/yaml": true,
+	"application/toml": true,
+	"application/xhtml+xml": true,
+	"application/javascript": true,
+	"application/plain": true
+};
+/** Strict whitelist: `text/*` or a known textual `application/*` MIME. A
+* missing header fails the check — binary decoding is never guessed. */
+function isTextContentType(headerValue) {
+	if (headerValue === null) return false;
+	const mime = headerValue.split(";", 1)[0].trim().toLowerCase();
+	return mime.startsWith("text/") || mime in APPLICATION_TEXT_TYPES;
+}
+/** Best-effort `err.cause` message — undici nests DNS/socket failures there. */
+function causeMessageOf(err) {
+	const cause = err?.cause;
+	if (cause instanceof Error) return cause.message;
+	if (typeof cause === "string" && cause !== "") return cause;
+	return null;
+}
+/** Stream the body as UTF-8 text, throwing past the 2 MiB byte cap. */
+async function readBodyCapped(body, href) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let received = 0;
+	let text = "";
+	try {
+		for (;;) {
+			const { done, value } = await reader.read().catch((err) => {
+				if (err instanceof Error && err.name === "AbortError") throw new UrlSchemesError("URL_HTTP_TIMEOUT", `HTTP GET ${href} aborted after the ${TIMEOUT_MS / 1e3} s deadline`);
+				throw err;
+			});
+			if (done) break;
+			received += value.byteLength;
+			if (received > MAX_BODY_BYTES) throw new UrlSchemesError("URL_HTTP_TOO_LARGE", `body of ${href} exceeded the ${MAX_BODY_BYTES}-byte (2 MiB) text limit after ${received} bytes`);
+			text += decoder.decode(value, { stream: true });
+		}
+		return text + decoder.decode();
+	} finally {
+		await reader.cancel().catch(() => {});
+	}
+}
+/** One capped, whitelisted GET of `url`; returns the decoded body text. */
+async function getUrl(url) {
+	const controller = new AbortController();
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, TIMEOUT_MS);
+	try {
+		let response;
+		try {
+			response = await fetch(url, {
+				method: "GET",
+				redirect: "follow",
+				signal: controller.signal
+			});
+		} catch (err) {
+			if (timedOut || err instanceof Error && err.name === "AbortError") throw new UrlSchemesError("URL_HTTP_TIMEOUT", `HTTP GET ${url.href} aborted after the ${TIMEOUT_MS / 1e3} s deadline`);
+			const cause = causeMessageOf(err);
+			const message = err instanceof Error ? err.message : String(err);
+			throw new UrlSchemesError("URL_HTTP_FETCH_FAILED", `HTTP GET ${url.href} failed: ${message}${cause === null ? "" : ` (${cause})`}`);
+		}
+		if (!response.ok) {
+			const statusText = response.statusText === "" ? "" : ` ${response.statusText}`;
+			throw new UrlSchemesError("URL_HTTP_STATUS", `HTTP GET ${url.href} returned ${response.status}${statusText}`);
+		}
+		const declared = response.headers.get("content-length");
+		if (declared !== null) {
+			const bytes = Number(declared);
+			if (Number.isFinite(bytes) && bytes > MAX_BODY_BYTES) throw new UrlSchemesError("URL_HTTP_TOO_LARGE", `body of ${url.href} is ${bytes} bytes, over the ${MAX_BODY_BYTES}-byte (2 MiB) text limit`);
+		}
+		const contentType = response.headers.get("content-type");
+		if (!isTextContentType(contentType)) throw new UrlSchemesError("URL_HTTP_UNSUPPORTED_MEDIA", `content-type of ${url.href} is "${contentType ?? "(none)"}", outside the text whitelist (text/* or application/{json,xml,yaml,toml,xhtml+xml,javascript,plain}) — binary decoding is deliberately not guessed`);
+		if (response.body === null) {
+			const text = await response.text();
+			const bytes = Buffer.byteLength(text, "utf8");
+			if (bytes > MAX_BODY_BYTES) throw new UrlSchemesError("URL_HTTP_TOO_LARGE", `body of ${url.href} is ${bytes} bytes, over the ${MAX_BODY_BYTES}-byte (2 MiB) text limit`);
+			return text;
+		}
+		return await readBodyCapped(response.body, url.href);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Build the `http://`/`https://` handler. Register the returned instance
+* under BOTH schemes ({@link HTTP_SCHEMES}); it is stateless and safe to
+* share.
+*/
+function createHttpHandler() {
+	return { async resolve(env, path) {
+		const raw = env.rawUrl ?? `https://${path}`;
+		let url;
+		try {
+			url = new URL(raw);
+		} catch (err) {
+			throw new UrlSchemesError("URL_INVALID", `invalid http(s) URL "${raw}": ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (url.protocol !== "http:" && url.protocol !== "https:") throw new UrlSchemesError("URL_INVALID", `not an http(s) URL: "${raw}"`);
+		return `${DISCLAIMER}\n\n${await getUrl(url)}`;
+	} };
+}
+
+//#endregion
+//#region src/fs-aware/wrap.ts
+const WRAPPED = Symbol("dsh-url-schemes.fs-wrap");
+function isSchemePath(path) {
+	return typeof path === "string" && /^[a-z][a-z0-9]*:\/\//.test(path);
+}
+function isSessionLayerScheme(path) {
+	return path.startsWith("ctx://") || path.startsWith("agent://") || path.startsWith("skill://");
+}
+function sessionLayerError(url) {
+	if (url.startsWith("skill://")) return new UrlSchemesError("CTX_SESSION_LAYER", `${url}: session-layer scheme — skill discovery (which roots load, scan depth, layered scope merge) is the host skill provider's business logic and resolves only against a calling agent, which the filesystem layer does not have. Load skills with the native \`skill\` tool; grep/glob with path=skill://… keep working through the tool layer`);
+	return new UrlSchemesError("CTX_SESSION_LAYER", `${url}: session-layer scheme — read it through the read tool (the session-layer resolver environment carries the live agent this filesystem layer does not have)`);
+}
+/** Build the FS-layer resolver: file-type schemes only (design D2). */
+function buildFsLayerResolver(services, fsSelf) {
+	const resolver = new UrlResolver();
+	resolver.register("dsh", createDshHandler({
+		settings: services.settings,
+		docsDir: resolveDocsDir()
+	}));
+	resolver.register("dvc", createDvcHandler());
+	for (const scheme of HTTP_SCHEMES) resolver.register(scheme, createHttpHandler());
+	resolver.register("ctx", { async resolve(_env, path) {
+		throw sessionLayerError(`ctx://${path}`);
+	} });
+	resolver.register("agent", { async resolve(_env, path) {
+		throw sessionLayerError(`agent://${path}`);
+	} });
+	return resolver;
+}
+/**
+* Wrap the mounted `ctx.fs` instance in place. Idempotent via a symbol flag.
+* Returns the resolver used for scheme dereferencing (for diagnostics).
+*/
+function wrapFsWithSchemes(fs, services) {
+	const holder = fs;
+	if (holder[WRAPPED] !== void 0) return holder[WRAPPED];
+	const resolver = buildFsLayerResolver(services, fs);
+	const envFor = (url) => ({
+		fs,
+		rawUrl: url
+	});
+	const bind = (fn) => typeof fn === "function" ? fn.bind(fs) : void 0;
+	const origResolve = bind(fs.resolve);
+	const origStat = bind(fs.stat);
+	const origReadText = bind(fs.readText);
+	const origWriteText = bind(fs.writeText);
+	const origEditText = bind(fs.editText);
+	const requireOrig = (orig, method) => {
+		if (orig === void 0) throw new UrlSchemesError("FS_BASE_UNSUPPORTED", `the mounted filesystem service exposes no "${method}" — scheme wrap is active but the base backend cannot serve real paths`);
+		return orig;
+	};
+	fs.resolve = async (path, opts) => {
+		if (!isSchemePath(path)) return requireOrig(origResolve, "resolve")(path, opts);
+		if (isSessionLayerScheme(path)) throw sessionLayerError(path);
+		await resolver.resolve(envFor(path), path);
+		return {
+			targetKey: path,
+			displayPath: path
+		};
+	};
+	fs.stat = async (target, signal) => {
+		if (!isSchemePath(target.targetKey)) return requireOrig(origStat, "stat")(target, signal);
+		if (isSessionLayerScheme(target.targetKey)) throw sessionLayerError(target.targetKey);
+		return {
+			type: "file",
+			size: (await resolver.resolve(envFor(target.targetKey), target.targetKey)).length
+		};
+	};
+	fs.readText = async (target, signal) => {
+		if (!isSchemePath(target.targetKey)) return requireOrig(origReadText, "readText")(target, signal);
+		if (isSessionLayerScheme(target.targetKey)) throw sessionLayerError(target.targetKey);
+		return resolver.resolve(envFor(target.targetKey), target.targetKey);
+	};
+	fs.writeText = async (target, ...rest) => {
+		if (isSchemePath(target.targetKey)) throw new UrlSchemesError("FS_VIRTUAL_READONLY", `cannot write "${target.targetKey}": scheme resources are read-only at the filesystem layer`);
+		return requireOrig(origWriteText, "writeText")(target, ...rest);
+	};
+	fs.editText = async (target, ...rest) => {
+		if (isSchemePath(target.targetKey)) throw new UrlSchemesError("FS_VIRTUAL_READONLY", `cannot edit "${target.targetKey}": scheme resources are read-only at the filesystem layer`);
+		return requireOrig(origEditText, "editText")(target, ...rest);
+	};
+	holder[WRAPPED] = resolver;
+	return resolver;
+}
+
+//#endregion
+export { createDshHandler as a, createDvcHandler as c, registerDvcDevice as d, UrlSchemesError as f, createHttpHandler as i, dispatchDvcWrite as l, SCHEME_NAMES as m, wrapFsWithSchemes as n, UrlResolver as o, parseUrl as p, HTTP_SCHEMES as r, resolveDocsDir as s, buildFsLayerResolver as t, listDvcDevices as u };