better-dsh 0.2.3 → 0.2.4-b

package/lib/compaction/index.js

@@ -0,0 +1,159 @@
+import { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+
+//#region src/compaction/config.ts
+/**
+* The `compaction-tuning` General-row config: the share of the routed context
+* window at which automatic condensation starts.
+*
+* Pure module — no `@deepseek-ai/*` value imports — so the host half and the
+* client half may both import it without dragging either runtime into the
+* browser bundle: the host takes the namespace and the schema defaults, the
+* client takes the namespace literal plus the stepper bounds.
+*
+* @module dashr/compaction/config
+*/
+/** The settings namespace the General row reads and writes. */
+const COMPACTION_SETTINGS_NS = "compaction-tuning";
+/** Upstream `compaction-basic`'s own default: condense at 80% of the window. */
+const DEFAULT_THRESHOLD_RATIO = .8;
+/**
+* Absolute recent-tail budget, in estimated tokens (~50 KB of English text).
+*
+* Composition-only, deliberately: the General row drives `thresholdRatio`
+* alone, so the recency window stays a deployment decision (its base layer is
+* the row config in `cordis.patch.yml`) rather than a second knob on the
+* settings page. The host half still applies it to the engine.
+*/
+const DEFAULT_RETAIN_TOKENS = 5e4;
+/** Ratio bounds the settings schema accepts (a config file may use either end). */
+const THRESHOLD_MIN_RATIO = .05;
+/** @see THRESHOLD_MIN_RATIO */
+const THRESHOLD_MAX_RATIO = 1;
+/** Spec defaults — `Config({})` must equal this. */
+const defaultCompactionTuningConfig = {
+	thresholdRatio: DEFAULT_THRESHOLD_RATIO,
+	retainTokens: DEFAULT_RETAIN_TOKENS
+};
+
+//#endregion
+//#region src/compaction/index.ts
+/** Cordis plugin name. */
+const name = "dashr-compaction-tuning";
+/**
+* No static injects: both `settings` and `compaction` are composed
+* conditionally inside {@link installCompactionTuning}, so the row loads
+* (dormant) in compositions without them.
+*/
+const inject = [];
+/**
+* The `compaction-tuning` settings schema.
+*
+* `thresholdRatio` is the field the General row drives; `retainTokens` is
+* composition-only (see {@link DEFAULT_RETAIN_TOKENS}) but still validated and
+* applied, so the recency window keeps one source of truth.
+*/
+const Config = z.object({
+	thresholdRatio: z.number().step(.01).min(THRESHOLD_MIN_RATIO).max(THRESHOLD_MAX_RATIO).default(DEFAULT_THRESHOLD_RATIO),
+	retainTokens: z.number().step(1).min(0).default(DEFAULT_RETAIN_TOKENS)
+});
+/**
+* Install the settings namespace and keep the live compaction engine in sync.
+* @param ctx - host context of the row that owns this capability.
+* @param config - composition base layer; schema defaults fill the rest.
+*/
+function installCompactionTuning(ctx, config = defaultCompactionTuningConfig) {
+	const logger = ctx.logger("compaction-tuning");
+	let source = () => Config(config);
+	/** Smallest routed context window seen so far (advisory guard, best effort). */
+	let minWindow;
+	let probing = false;
+	/**
+	* Learn the routed context windows so a write can be refused when it would
+	* leave `retainTokens >= floor(window x thresholdRatio)` — the condition
+	* under which the engine raises `TargetPressureConfigError` per route and
+	* automatic condensation quietly stops for that route.
+	*/
+	const probeWindows = () => {
+		if (probing || minWindow !== void 0) return;
+		const llm = ctx.get("llm");
+		if (llm === void 0) return;
+		probing = true;
+		(async () => {
+			try {
+				let smallest;
+				for (const provider of llm.listProviders()) for (const model of await llm.listModels(provider.id)) {
+					const window = (await llm.resolveModelInfo(provider.id, model.id)).context?.contextWindow;
+					if (typeof window !== "number" || window <= 0) continue;
+					smallest = smallest === void 0 ? window : Math.min(smallest, window);
+				}
+				if (smallest !== void 0) {
+					minWindow = smallest;
+					logger.info(`smallest routed context window: ${smallest} tokens`);
+				}
+			} catch (error) {
+				logger.warn(`context-window probe failed (retention guard disabled): ${error instanceof Error ? error.message : String(error)}`);
+			} finally {
+				probing = false;
+			}
+		})();
+	};
+	/**
+	* Overwrite only this module's two fields on the engine's current policy and
+	* hand the engine a fresh frozen object.
+	* @param reason - short diagnostic tag for the log line.
+	*/
+	const push = (reason) => {
+		const compaction = ctx.get("compaction");
+		if (compaction === void 0) return;
+		const base = compaction.config;
+		if (base === void 0) return;
+		const value = source();
+		const next = {
+			...base,
+			thresholdRatio: value.thresholdRatio,
+			retainTokens: value.retainTokens
+		};
+		delete next.retainRatio;
+		compaction.config = Object.freeze(next);
+		logger.info(`applied (${reason}): thresholdRatio=${value.thresholdRatio} retainTokens=${value.retainTokens}`);
+	};
+	ctx.inject(["compaction"], () => {
+		push("compaction-ready");
+		probeWindows();
+	});
+	ctx.inject(["settings"], (settingsCtx) => {
+		if (settingsCtx.settings.get(COMPACTION_SETTINGS_NS) !== void 0) {
+			logger.info("settings namespace already served; leaving it to its owner");
+			return;
+		}
+		settingsCtx.settings.installSection(ctx, COMPACTION_SETTINGS_NS, Config, Config(config), {
+			setSource: (current) => {
+				source = current;
+			},
+			onChange: () => {
+				push("settings-updated");
+			},
+			validate: (value) => {
+				if (minWindow === void 0) return;
+				const thresholdTokens = Math.floor(minWindow * value.thresholdRatio);
+				if (value.retainTokens >= thresholdTokens) throw new Error(`retainTokens (${value.retainTokens}) must stay below the threshold tokens for every routed model; the smallest window here is ${minWindow}, so ${value.thresholdRatio} leaves only ${thresholdTokens}`);
+			}
+		});
+		push("settings-installed");
+		probeWindows();
+	});
+}
+/** Mount the tuning as the row's whole apply (the row config is the settings base). */
+function apply(ctx, config) {
+	installCompactionTuning(ctx, config ?? defaultCompactionTuningConfig);
+}
+var compaction_default = {
+	name,
+	inject,
+	Config,
+	apply
+};
+
+//#endregion
+export { Config, apply, compaction_default as default, inject, installCompactionTuning, name };

package/lib/failover/index.d.ts

@@ -0,0 +1,35 @@
+import { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+
+//#region src/failover/config.d.ts
+
+/** The fallback chain: two ordered slots. `''` = not set (skip). */
+interface FailoverConfig {
+  fallback1: string;
+  fallback2: string;
+}
+//#endregion
+//#region src/failover/index.d.ts
+
+/** Cordis plugin name. */
+declare const name = "dashr-failover";
+/**
+ * No static injects: `settings` is composed conditionally inside
+ * {@link installFailover} (`ctx.inject(['settings'], …)`), so the row loads
+ * (dormant) in compositions without a settings service.
+ */
+declare const inject: string[];
+/** The `failover` settings schema: two optional fallback slots, both default "not set". */
+declare const Config: z<FailoverConfig>;
+/** Install the failover. A no-op composition degrades gracefully (empty chain = pass-through). */
+declare function installFailover(ctx: Context, config?: FailoverConfig): void;
+/** Mount the failover as the row's whole apply (the row config is the chain base). */
+declare function apply(ctx: Context, config: FailoverConfig | undefined): void;
+declare const _default: {
+  name: string;
+  inject: string[];
+  Config: z<FailoverConfig>;
+  apply: typeof apply;
+};
+//#endregion
+export { Config, apply, _default as default, inject, installFailover, name };

package/lib/failover/index.js

@@ -0,0 +1,141 @@
+import { Context } from "@deepseek-ai/cordis";
+import { randomUUID } from "node:crypto";
+import z from "@deepseek-ai/schemastery";
+import { RetryId } from "@deepseek-ai/dsh-llm-retry";
+
+//#region src/failover/config.ts
+/**
+* The `failover` general-fallback config (host-plane, per-turn latch).
+*
+* Pure module — no `@deepseek-ai/*` value imports, so both the host module and
+* the client half may import it (the client type-only) without dragging a host
+* runtime dependency into the browser bundle.
+*
+* A route is a `provider/model` string (e.g. `deepseek/deepseek-v4-flash`).
+* The empty string `''` means "not set" — the slot is skipped.
+*
+* @module dashr/failover/config
+*/
+/** The settings namespace the General row reads and writes. */
+const FAILOVER_SETTINGS_NS = "failover";
+/** Failure codes that activate a fallback switch. */
+const FAILOVER_TRIGGER_CODES = {
+	AUTH: true,
+	MISSING_CREDENTIAL: true,
+	QUOTA: true,
+	RATE_LIMIT: true
+};
+/** Spec defaults — `Config({})` must equal this (both slots unset = native behavior). */
+const defaultFailoverConfig = {
+	fallback1: "",
+	fallback2: ""
+};
+/** The non-empty fallback routes in order (at most 2). */
+function fallbackRoutes(config) {
+	return [config.fallback1, config.fallback2].filter((route) => route.length > 0);
+}
+/** Split a `provider/model` route; `undefined` when malformed. */
+function splitRoute(route) {
+	const slash = route.indexOf("/");
+	if (slash <= 0 || slash === route.length - 1) return void 0;
+	return {
+		provider: route.slice(0, slash),
+		model: route.slice(slash + 1)
+	};
+}
+
+//#endregion
+//#region src/failover/index.ts
+/** Cordis plugin name. */
+const name = "dashr-failover";
+/**
+* No static injects: `settings` is composed conditionally inside
+* {@link installFailover} (`ctx.inject(['settings'], …)`), so the row loads
+* (dormant) in compositions without a settings service.
+*/
+const inject = [];
+/** The `failover` settings schema: two optional fallback slots, both default "not set". */
+const Config = z.object({
+	fallback1: z.string().default(""),
+	fallback2: z.string().default("")
+});
+/** Replace provider/model on a request config, dropping the inherited reasoning effort. */
+function overrideConfig(seed, to) {
+	const { reasoningEffort: _inherited,...rest } = seed;
+	return {
+		...rest,
+		provider: to.provider,
+		model: to.model
+	};
+}
+/** Install the failover. A no-op composition degrades gracefully (empty chain = pass-through). */
+function installFailover(ctx, config = defaultFailoverConfig) {
+	const logger = ctx.logger("llm-failover");
+	let source = () => Config(config);
+	ctx.inject(["settings"], (sctx) => {
+		sctx.settings.installSection(ctx, FAILOVER_SETTINGS_NS, Config, Config(config), {
+			setSource: (current) => {
+				source = current;
+			},
+			onChange: () => {}
+		});
+	});
+	const latches = /* @__PURE__ */ new Map();
+	ctx.on("agent/disposed", ({ agent }) => {
+		latches.delete(agent.id);
+	});
+	ctx.on("agent/request-error", async ({ agent, turn, step, provider, failure }, next) => {
+		if (FAILOVER_TRIGGER_CODES[failure.code] !== true) return next();
+		const routes = fallbackRoutes(source());
+		if (routes.length === 0) return next();
+		const latch = latches.get(agent.id);
+		const fallbackIndex = latch !== void 0 && latch.turn === turn ? latch.fallbackIndex : 0;
+		if (fallbackIndex >= routes.length) return next();
+		const nextIndex = fallbackIndex + 1;
+		const route = routes[nextIndex - 1];
+		if (splitRoute(route) === void 0) return next();
+		latches.set(agent.id, {
+			turn,
+			fallbackIndex: nextIndex
+		});
+		logger.info("llm-failover: agent \"%s\" provider=\"%s\" code=%s -> switch to \"%s\" (per turn)", agent.id, provider, failure.code, route);
+		agent.session.append("llm/retry", {
+			retryId: RetryId(randomUUID()),
+			turn,
+			step,
+			provider,
+			mode: "normal",
+			policyKey: "llm-failover",
+			retry: nextIndex,
+			maxRetries: routes.length,
+			delayMs: 0,
+			failure: {
+				...failure,
+				code: "failover",
+				message: `[${failure.code}] ${failure.message} → switched to "${route}"`
+			}
+		});
+		return { kind: "retry" };
+	});
+	ctx.on("agent/request", async ({ agent, turn }, next) => {
+		const seed = await next();
+		const latch = latches.get(agent.id);
+		if (latch === void 0 || latch.turn !== turn || latch.fallbackIndex <= 0) return seed;
+		const route = splitRoute(fallbackRoutes(source())[latch.fallbackIndex - 1] ?? "");
+		if (route === void 0) return seed;
+		return overrideConfig(seed, route);
+	});
+}
+/** Mount the failover as the row's whole apply (the row config is the chain base). */
+function apply(ctx, config) {
+	installFailover(ctx, config ?? defaultFailoverConfig);
+}
+var failover_default = {
+	name,
+	inject,
+	Config,
+	apply
+};
+
+//#endregion
+export { Config, apply, failover_default as default, inject, installFailover, name };

package/lib/fs-aware/sandbox-plugin.d.ts

@@ -0,0 +1,71 @@
+import { Context } from "@deepseek-ai/cordis";
+import { Config } from "@deepseek-ai/dsh-fs-local";
+
+//#region src/fs-aware/sandbox-plugin.d.ts
+
+/** Module config: the stock LocalConfig fields plus the scheme gate. */
+interface FsAwareConfig extends Config {
+  /** Master gate for scheme interception at the FS layer (default on). */
+  urlSchemes?: boolean;
+}
+/** Structural view of the inherited backend (loose, like the spike's Base). */
+interface BaseView {
+  resolve(path: string, opts?: {
+    cwd?: string;
+    signal?: AbortSignal;
+  }): Promise<{
+    targetKey: string;
+    displayPath: string;
+  }>;
+  stat(target: {
+    targetKey: string;
+  }, signal?: AbortSignal): Promise<unknown>;
+  readText(target: {
+    targetKey: string;
+  }, signal?: AbortSignal): Promise<string>;
+  writeText(target: {
+    targetKey: string;
+  }, ...rest: unknown[]): Promise<unknown>;
+  editText(target: {
+    targetKey: string;
+  }, ...rest: unknown[]): Promise<unknown>;
+}
+declare const Base: abstract new (ctx: Context, config: FsAwareConfig) => BaseView;
+declare class FsAwareSandboxFileSystem extends Base {
+  static inject: string[];
+  private readonly resolver;
+  private readonly schemeResolution;
+  constructor(ctx: Context, config: FsAwareConfig);
+  /**
+   * FS-layer resolver — the SHARED builder from `wrap.ts` (design D2). One
+   * registration source for both FS consumers: this backend and the instance
+   * wrap. (A private duplicate here once drifted — a doubled `dsh` register
+   * and a literal `'http'` that would silently drop `https` if this backend
+   * were ever the outermost layer.) The `ctx`/`agent` handlers it registers
+   * are unreachable here: session-layer schemes are guarded before resolve.
+   */
+  private buildResolver;
+  /** FS-layer resolver env: no live agent — session-layer schemes are excluded upstream. */
+  private envFor;
+  resolve(path: string, opts?: {
+    cwd?: string;
+    signal?: AbortSignal;
+  }): Promise<{
+    targetKey: string;
+    displayPath: string;
+  }>;
+  stat(target: {
+    targetKey: string;
+  }, signal?: AbortSignal): Promise<unknown>;
+  readText(target: {
+    targetKey: string;
+  }, signal?: AbortSignal): Promise<string>;
+  writeText(target: {
+    targetKey: string;
+  }, ...rest: unknown[]): Promise<unknown>;
+  editText(target: {
+    targetKey: string;
+  }, ...rest: unknown[]): Promise<unknown>;
+}
+//#endregion
+export { FsAwareConfig, FsAwareSandboxFileSystem as default };

package/lib/fs-aware/sandbox-plugin.js

@@ -0,0 +1,249 @@
+import { f as UrlSchemesError, t as buildFsLayerResolver } from "../wrap-Dr8XtIak.js";
+import { Context } from "@deepseek-ai/cordis";
+import { dirname, sep } from "node:path";
+import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { writableRoots } from "@deepseek-ai/dsh-sandbox";
+import { stat } from "node:fs/promises";
+
+//#region ../../../better-dsh/node_modules/@deepseek-ai/dsh-fs-sandbox/lib/index.js
+/**
+* Path-containment mechanics for the filesystem sandbox. Canonical spellings
+* take the fast lexical path; filesystem identity supplies the conservative
+* fallback for alias-equivalent roots such as Windows 8.3 names and casing.
+* @module @deepseek-ai/dsh-fs-sandbox/containment
+*/
+const MISSING_CODES = new Set(["ENOENT", "ENOTDIR"]);
+function isMissing(error) {
+	const code = error.code;
+	return MISSING_CODES.has(code);
+}
+function comparablePath(path, caseSensitive) {
+	return caseSensitive ? path : path.toLowerCase();
+}
+function isLexicallyUnder(path, root, caseSensitive) {
+	const comparableTarget = comparablePath(path, caseSensitive);
+	const comparableRoot = comparablePath(root, caseSensitive);
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+async function statIfPresent(path) {
+	try {
+		return await stat(path, { bigint: true });
+	} catch (error) {
+		/* v8 ignore else -- a non-missing stat failure requires a host permission or I/O fault after resolve reached this ancestor. */
+		if (isMissing(error)) return void 0;
+		/* v8 ignore next -- requires a host permission or I/O fault after resolve already reached this ancestor. */
+		throw error;
+	}
+}
+function sameIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+* Determine whether a canonical target is a writable root or lies beneath it.
+* The lexical fast path handles normal canonical spellings. When spellings
+* differ, walk the target's existing ancestors and compare filesystem identity
+* with the root; this recognizes Windows long-name/8.3 aliases and casing
+* without weakening containment to a textual approximation.
+* @param path - canonical target key, which may end in a missing suffix.
+* @param root - canonical writable root.
+* @param caseSensitive - whether lexical comparison preserves case; defaults
+*   to the host filesystem convention used by supported platforms.
+* @returns whether the target is the root or a descendant of it.
+*/
+async function isPathUnder(path, root, caseSensitive = process.platform !== "win32") {
+	if (isLexicallyUnder(path, root, caseSensitive)) return true;
+	const rootInfo = await statIfPresent(root);
+	if (!rootInfo) return false;
+	let ancestor = path;
+	while (true) {
+		const ancestorInfo = await statIfPresent(ancestor);
+		if (ancestorInfo && sameIdentity(ancestorInfo, rootInfo)) return true;
+		const parent = dirname(ancestor);
+		if (parent === ancestor) return false;
+		ancestor = parent;
+	}
+}
+/**
+* `SandboxedFileSystem`: the sandbox-enforcing implementation of the
+* `@deepseek-ai/dsh-fs` Service Definition. It extends `LocalFileSystem` so all
+* text-storage mechanics — resolve, stat, read/stream, list, the atomic
+* write and the read-match-write edit critical section — are the local
+* implementation's, verbatim; this package adds only the per-call POLICY fence
+* on the two mutations. Reads pass through untouched: every mode permits
+* reading.
+*
+* The fence is a policy check in TRUSTED code over a MODEL-CONTROLLED path,
+* NOT a kernel boundary — the operations are the seam's own (open, rename),
+* and only the target path is untrusted, so canonicalize-then-contain is the
+* complete answer to this surface. This is containment, not a security
+* boundary; kernel-grade isolation of untrusted CODE stays `ctx.shell`'s job
+* (`@deepseek-ai/dsh-bash-sandbox`). The residual
+* TOCTOU (an ancestor symlink swapped between the containment re-check and the
+* syscall) is narrowed by re-canonicalizing immediately before delegating and
+* is accepted for this threat model.
+*
+* Per-call policy: `read-only` denies every mutation; `workspace-write` allows
+* a mutation only when the target canonicalizes under the policy's workspace
+* root or a platform temp area from the shared `writableRoots` policy;
+* `danger-full-access` delegates unfenced. A denial throws the structured
+* `FS_SANDBOX_DENIED`.
+*
+* @module @deepseek-ai/dsh-fs-sandbox
+*/
+/**
+* Sandbox-enforcing filesystem backend. Registers as `ctx.fs` (loading it
+* INSTEAD OF `dsh-fs-local`, together with a `ctx.sandboxPolicy`, is the whole
+* swap — the model-facing tools are untouched). Its configured default mode is
+* the capability fact exposed by {@link sandboxMode}; `dsh-tool-fs` resolves
+* each session's mode and cwd into a policy for every mutation, while an
+* approved escalation may stamp a strictly wider mode for one call.
+*/
+var SandboxedFileSystem = class extends LocalFileSystem {
+	static inject = ["sandboxPolicy"];
+	defaultMode;
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.defaultMode = ctx.sandboxPolicy.defaultMode;
+	}
+	/** The deployment default mode — the capability fact the tool layer reads to advertise escalation. */
+	get sandboxMode() {
+		return this.defaultMode;
+	}
+	/**
+	* Fence the write by the per-call policy, then delegate to the inherited
+	* atomic write. See {@link checkedTarget}.
+	* @param target - the resolved target to write.
+	* @param content - the full new file content.
+	* @param expected - the write intent guarding the write; omit for unconditional.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the write outcome from the inherited backend.
+	*/
+	async writeText(target, content, expected, signal, sandboxPolicy) {
+		return super.writeText(await this.checkedTarget(target, sandboxPolicy), content, expected, signal);
+	}
+	/**
+	* Fence the edit by the per-call policy, then delegate to the inherited
+	* atomic edit. See {@link checkedTarget}.
+	* @param target - the resolved target to edit.
+	* @param edit - the literal search/replace request.
+	* @param expected - the version guard; omit for an unconditional edit.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the edit outcome from the inherited backend.
+	*/
+	async editText(target, edit, expected, signal, sandboxPolicy) {
+		return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal);
+	}
+	/**
+	* Enforce the per-call policy against `target` and return the EXACT target the
+	* mutation must use, so the checked identity is the mutated one (no
+	* check-here-write-there TOCTOU). `read-only` denies; `workspace-write`
+	* re-canonicalizes NOW (`resolve` realpaths the deepest existing ancestor,
+	* reflecting a concurrently swapped symlink), requires containment under a
+	* writable root, and returns THAT fresh target; `danger-full-access` returns
+	* the caller's target unfenced. Throws the structured `FS_SANDBOX_DENIED` on
+	* refusal — the tool layer maps it to the model-facing `[sandbox: …]` marker
+	* and the escalation hint.
+	*/
+	async checkedTarget(target, sandboxPolicy) {
+		const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+		const { mode } = policy;
+		if (mode === "danger-full-access") return target;
+		if (mode === "read-only") throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
+		const fresh = await this.resolve(target.displayPath);
+		let contained = false;
+		for (const root of writableRoots(policy)) if (await isPathUnder(fresh.targetKey, root)) {
+			contained = true;
+			break;
+		}
+		if (!contained) throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+		return fresh;
+	}
+};
+
+//#endregion
+//#region src/fs-aware/sandbox-plugin.ts
+/** Scheme prefix test — mirrors the resolver's own grammar. */
+function isSchemePath(path) {
+	return /^[a-z][a-z0-9]*:\/\//.test(path);
+}
+/** Session-layer schemes are excluded from FS-layer resolution (design D2). */
+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)`);
+}
+const Base = SandboxedFileSystem;
+var FsAwareSandboxFileSystem = class extends Base {
+	static inject = [
+		"sandboxPolicy",
+		"settings",
+		"agents"
+	];
+	resolver;
+	schemeResolution;
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.schemeResolution = config?.urlSchemes !== false;
+		this.resolver = this.buildResolver(ctx);
+	}
+	/**
+	* FS-layer resolver — the SHARED builder from `wrap.ts` (design D2). One
+	* registration source for both FS consumers: this backend and the instance
+	* wrap. (A private duplicate here once drifted — a doubled `dsh` register
+	* and a literal `'http'` that would silently drop `https` if this backend
+	* were ever the outermost layer.) The `ctx`/`agent` handlers it registers
+	* are unreachable here: session-layer schemes are guarded before resolve.
+	*/
+	buildResolver(ctx) {
+		return buildFsLayerResolver({ settings: ctx.settings }, this);
+	}
+	/** FS-layer resolver env: no live agent — session-layer schemes are excluded upstream. */
+	envFor(url) {
+		return {
+			fs: this,
+			rawUrl: url
+		};
+	}
+	async resolve(path, opts) {
+		if (!this.schemeResolution || !isSchemePath(path)) return super.resolve(path, opts);
+		if (isSessionLayerScheme(path)) throw sessionLayerError(path);
+		await this.resolver.resolve(this.envFor(path), path);
+		return {
+			targetKey: path,
+			displayPath: path
+		};
+	}
+	async stat(target, signal) {
+		if (!this.schemeResolution || !isSchemePath(target.targetKey)) return super.stat(target, signal);
+		if (isSessionLayerScheme(target.targetKey)) throw sessionLayerError(target.targetKey);
+		return {
+			type: "file",
+			size: (await this.resolver.resolve(this.envFor(target.targetKey), target.targetKey)).length
+		};
+	}
+	async readText(target, signal) {
+		if (!this.schemeResolution || !isSchemePath(target.targetKey)) return super.readText(target, signal);
+		if (isSessionLayerScheme(target.targetKey)) throw sessionLayerError(target.targetKey);
+		return this.resolver.resolve(this.envFor(target.targetKey), target.targetKey);
+	}
+	async writeText(target, ...rest) {
+		if (this.schemeResolution && isSchemePath(target.targetKey)) throw new UrlSchemesError("FS_VIRTUAL_READONLY", `cannot write "${target.targetKey}": scheme resources are read-only at the filesystem layer`);
+		return super.writeText(target, ...rest);
+	}
+	async editText(target, ...rest) {
+		if (this.schemeResolution && isSchemePath(target.targetKey)) throw new UrlSchemesError("FS_VIRTUAL_READONLY", `cannot edit "${target.targetKey}": scheme resources are read-only at the filesystem layer`);
+		return super.editText(target, ...rest);
+	}
+};
+
+//#endregion
+export { FsAwareSandboxFileSystem as default };