dsh-plugin-wsl-env 0.1.0

package/lib/picker.js

@@ -0,0 +1,350 @@
+/**
+ * WSL-aware directory picker: the `ctx.directoryPicker` backend that makes the
+ * Web GUI's "Select Workspace Directory" dialog open inside a distro.
+ *
+ * ## Why this serves `kind: 'browse'` instead of declaring a `wsl` kind
+ *
+ * The seam's capability is a merge-extensible discriminated union, so adding a
+ * `wsl` kind looks like the natural move. It does not work, and the reason is
+ * worth stating plainly: the capability is **not** what crosses the wire.
+ * `dsh-api-workspace-controller` exposes exactly three Remote verbs and pins
+ * each to a literal kind —
+ *
+ *     pick(signal)             -> requireCapability('native', 'pick')
+ *     list(path, signal)       -> requireCapability('browse', 'list')
+ *     createDirectory(...)     -> requireCapability('browse', 'createDirectory')
+ *
+ * — and refuses anything else with `directory-picker/unavailable`. A backend
+ * reporting `{ kind: 'wsl', ... }` would therefore break the very verbs it
+ * needs, because `requireCapability('browse', ...)` would no longer match. The
+ * wire vocabulary lives in a shipped, versioned package inside `app.asar`, so
+ * adding a third kind means patching an asar package that the next app update
+ * overwrites.
+ *
+ * Serving `browse` is not a workaround, it is the fit: `browse`'s primitives are
+ * "list one absolute directory level" and "create one child directory", which is
+ * exactly what browsing a distro needs. The only thing the shipped browse
+ * backend lacks is *discoverability* of WSL — it opens at the Windows home
+ * directory. This backend closes that gap:
+ *
+ *   - the root level lists the installed distros (`wsl.exe -l -q`), so WSL is
+ *     the entry point rather than something you must know a UNC path for;
+ *   - the breadcrumb "WSL" row jumps back to that distro list;
+ *   - the dialog's Home affordance targets the preferred distro's Linux `$HOME`;
+ *   - every other level is an ordinary directory listing, which the host
+ *     performs over the distro's UNC share.
+ *
+ * Because the client surface is unchanged, this row composes with the **shipped**
+ * `@deepseek-ai/dsh-client-ui-directory-picker-browse` dialog: no client code,
+ * no wire change, no asar patch.
+ *
+ * @module dsh-plugin-wsl/picker
+ */
+
+import { mkdir, opendir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { DirectoryPicker, DirectoryPickerError } from "@deepseek-ai/dsh-host-directory-picker";
+import { UNC_PROVIDER_ROOT, distroRoot, isProviderRoot } from "./paths.js";
+import { breadcrumbs, boundedInsert, fullyQualified } from "./listing.js";
+import { listDistros, linuxHome } from "./wsl.js";
+
+/** How long a resolved distro list stays fresh before it is queried again. */
+const DEFAULT_DISTRO_CACHE_MS = 5_000;
+
+/**
+ * Await `operation`, but reject with the signal's reason the moment it aborts.
+ * Node's filesystem reads are not retractable, so the operation itself keeps
+ * running against a handle the caller then closes; its late settlement is
+ * swallowed so an abandoned read cannot surface as an unhandled rejection.
+ *
+ * @param operation - the in-flight filesystem step.
+ * @param signal - caller lifetime; absent means plain awaiting.
+ * @returns the operation's value.
+ */
+export function raceAbort(operation, signal) {
+  if (signal === void 0) return operation;
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      operation.catch(() => {});
+      reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)));
+    };
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (reason) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(reason instanceof Error ? reason : new Error(String(reason)));
+      },
+    );
+  });
+}
+
+/** Message text of an unknown thrown value. */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * One listing row for a dirent, following symlinks to directories; null for
+ * non-directories and broken or cyclic links, which cannot be entered.
+ */
+async function directoryRow(parent, name, isDirectory, isSymbolicLink, signal) {
+  const path = join(parent, name);
+  let enterable = isDirectory;
+  if (!enterable && isSymbolicLink) {
+    try {
+      enterable = (await raceAbort(stat(path), signal)).isDirectory();
+    } catch {
+      if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));
+      return null;
+    }
+  }
+  if (!enterable) return null;
+  return { name, path, hidden: name.startsWith(".") };
+}
+
+/**
+ * The `ctx.directoryPicker` WSL implementation.
+ *
+ * The capability object is built once per service lifetime because consumers may
+ * capture it across calls.
+ */
+export class WslDirectoryPicker extends DirectoryPicker {
+  static Config = z.object({
+    /** Path to `wsl.exe`; overridable for a non-standard install. */
+    wslPath: z.string().default("wsl.exe"),
+    /**
+     * Distro listed first and used for the Home affordance. Empty means WSL's
+     * own default distro.
+     */
+    preferredDistro: z.string().default(""),
+    /**
+     * Also offer the Windows home directory at the root level, so a normal
+     * host folder stays reachable without typing a path. The dialog's editable
+     * path zone accepts any Windows path either way.
+     */
+    includeHostHome: z.boolean().default(true),
+    /** Bound on the directory rows one `list` call may return; the level is flagged truncated. */
+    maxEntries: z.natural().min(1).default(1_000),
+    /** How long a resolved distro list stays fresh. */
+    distroCacheMs: z.natural().default(DEFAULT_DISTRO_CACHE_MS),
+  });
+
+  constructor(ctx, config) {
+    super(ctx);
+    this.config = config;
+    /** Last distro listing, so navigating to the root does not spawn `wsl.exe` every time. */
+    this.distroCache = undefined;
+    /** Per-distro Linux home, resolved once (a distro's default user does not change under a running session). */
+    this.homeCache = new Map();
+  }
+
+  /**
+   * The browse interaction capability.
+   *
+   * Deliberately `browse` and not a `wsl` kind: see the module comment. The
+   * distro listing is exposed as {@link WslDirectoryPicker.distros} for
+   * programmatic callers instead of through the capability union, because a
+   * capability kind the wire controller does not recognise would disable the
+   * verbs above rather than add a new one.
+   *
+   * @returns the stable `browse` capability object.
+   */
+  capability() {
+    return this.browseCapability;
+  }
+
+  browseCapability = {
+    kind: "browse",
+    list: (path, signal) => this.list(path, signal),
+    createDirectory: (path, name) => this.createDirectory(path, name),
+  };
+
+  /**
+   * Installed distros, cached briefly.
+   * @param signal - optional cancellation.
+   * @returns distro names, default distro first.
+   */
+  async distros(signal) {
+    const ttl = this.config.distroCacheMs;
+    const now = Date.now();
+    if (this.distroCache !== undefined && now - this.distroCache.at < ttl) return this.distroCache.value;
+    const value = await listDistros({ wslPath: this.config.wslPath, signal });
+    this.distroCache = { at: now, value };
+    return value;
+  }
+
+  /**
+   * The distro this picker leads with: the configured one when installed, else
+   * WSL's default, else the first installed.
+   * @param signal - optional cancellation.
+   * @returns a distro name, or empty when none is installed.
+   */
+  async preferredDistro(signal) {
+    const distros = await this.distros(signal);
+    const configured = this.config.preferredDistro;
+    if (configured.length > 0 && distros.includes(configured)) return configured;
+    return distros[0] ?? "";
+  }
+
+  /**
+   * A distro's Linux home directory as a UNC path, best effort: a distro that
+   * cannot be queried (stopped, and unable to start) falls back to its root so
+   * the dialog still opens somewhere real.
+   *
+   * @param distro - distro name.
+   * @param signal - optional cancellation.
+   * @returns the UNC home path.
+   */
+  async homeOf(distro, signal) {
+    const cached = this.homeCache.get(distro);
+    if (cached !== undefined) return cached;
+    let home;
+    try {
+      home = await linuxHome(distro, { wslPath: this.config.wslPath, signal });
+    } catch {
+      home = distroRoot(distro);
+    }
+    this.homeCache.set(distro, home);
+    return home;
+  }
+
+  /**
+   * The root level: one row per installed distro, plus the Windows home when
+   * configured. `path` is the preferred distro's root rather than the share
+   * root, so adopting the level with nothing selected still yields a real
+   * directory; the breadcrumb's "WSL" row carries the share root and returns
+   * here.
+   *
+   * @param signal - optional cancellation.
+   * @returns the root listing.
+   */
+  async rootLevel(signal) {
+    const distros = await this.distros(signal);
+    const preferred = await this.preferredDistro(signal);
+    const entries = [];
+    if (this.config.includeHostHome) {
+      const hostHome = homedir();
+      entries.push({ name: hostHome, path: hostHome, hidden: false });
+    }
+    for (const distro of distros) entries.push({ name: distro, path: distroRoot(distro), hidden: false });
+    const home = preferred.length > 0 ? await this.homeOf(preferred, signal) : homedir();
+    return {
+      path: preferred.length > 0 ? distroRoot(preferred) : homedir(),
+      home,
+      crumbs: [{ name: "WSL", path: UNC_PROVIDER_ROOT, hidden: false }],
+      entries,
+      truncated: false,
+    };
+  }
+
+  /**
+   * Breadcrumb rows for a level, headed by the WSL row.
+   * @param target - the directory being listed.
+   * @returns breadcrumb rows.
+   */
+  crumbsFor(target) {
+    return breadcrumbs(target, UNC_PROVIDER_ROOT);
+  }
+
+  /**
+   * List one directory level.
+   * @param path - absolute directory; absent or the share root lists the distros.
+   * @param signal - caller lifetime.
+   * @returns the level's listing with its ancestry.
+   * @throws DirectoryPickerError with code `directory-unreadable`.
+   */
+  async list(path, signal) {
+    if (path === void 0 || isProviderRoot(path)) return this.rootLevel(signal);
+    if (!fullyQualified(path)) {
+      throw new DirectoryPickerError("directory-unreadable", path, `cannot list "${path}": not a fully qualified path`);
+    }
+    const target = resolve(path);
+    const maxEntries = this.config.maxEntries;
+    const keep = maxEntries + 1;
+    const window = [];
+    let evicted = false;
+    let level;
+    try {
+      const opening = opendir(target);
+      level = await raceAbort(opening, signal).catch((error) => {
+        opening.then((dir) => dir.close().catch(() => {}), () => {});
+        throw error;
+      });
+      for (;;) {
+        const dirent = await raceAbort(level.read(), signal);
+        if (dirent === null) break;
+        if (!dirent.isDirectory() && !dirent.isSymbolicLink()) continue;
+        if (boundedInsert(window, { name: dirent.name, isDirectory: dirent.isDirectory(), isSymbolicLink: dirent.isSymbolicLink() }, keep)) {
+          evicted = true;
+        }
+      }
+    } catch (error) {
+      signal?.throwIfAborted();
+      throw new DirectoryPickerError("directory-unreadable", target, `cannot list ${target}: ${messageOf(error)}`);
+    } finally {
+      if (level !== undefined) await level.close().catch(() => {});
+    }
+
+    const entries = [];
+    let truncated = evicted;
+    for (const candidate of window) {
+      signal?.throwIfAborted();
+      const row = await directoryRow(target, candidate.name, candidate.isDirectory, candidate.isSymbolicLink, signal);
+      if (row === null) continue;
+      if (entries.length === maxEntries) {
+        truncated = true;
+        break;
+      }
+      entries.push(row);
+    }
+
+    const preferred = await this.preferredDistro(signal);
+    return {
+      path: target,
+      home: preferred.length > 0 ? await this.homeOf(preferred, signal) : homedir(),
+      crumbs: this.crumbsFor(target),
+      entries,
+      truncated,
+    };
+  }
+
+  /**
+   * Create one child directory inside the listed level.
+   * @param path - absolute existing parent directory.
+   * @param name - single non-blank path segment.
+   * @returns the created directory's absolute path.
+   * @throws DirectoryPickerError with code `directory-exists` or `directory-create-failed`.
+   */
+  async createDirectory(path, name) {
+    if (!fullyQualified(path)) {
+      throw new DirectoryPickerError("directory-create-failed", path, `cannot create under "${path}": not a fully qualified parent path`);
+    }
+    const parent = resolve(path);
+    if (name.trim() === "" || name === "." || name === ".." || /[/\\]/.test(name)) {
+      throw new DirectoryPickerError("directory-create-failed", join(parent, name), `"${name}" is not a single path segment`);
+    }
+    const target = join(parent, name);
+    try {
+      await mkdir(target);
+      return target;
+    } catch (error) {
+      if (typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST") {
+        throw new DirectoryPickerError("directory-exists", target, `${target} already exists`);
+      }
+      throw new DirectoryPickerError("directory-create-failed", target, `cannot create ${target}: ${messageOf(error)}`);
+    }
+  }
+}
+
+export default WslDirectoryPicker;
+export { ancestryCrumbs, boundedInsert, breadcrumbs, fullyQualified } from "./listing.js";

package/lib/sandbox.js

@@ -0,0 +1,162 @@
+/**
+ * The Linux-side confinement this plugin applies to commands that run inside a
+ * distro.
+ *
+ * ## Why this is not `ctx.sandbox`
+ *
+ * DSH's local sandbox provider selects its runner chain by `process.platform`.
+ * This harness process is Windows, so it selects the windows-acl runner — and
+ * that runner's restricted, low-integrity token **cannot reach WSL at all**
+ * (`wsl.exe` fails with `Wsl/E_ACCESSDENIED`). The confinement that governs a
+ * distro command therefore has to be *built* on the host and *executed* inside
+ * the distro, which is what this module produces: an argv whose program is
+ * `bwrap`, handed to `wsl.exe --exec` like any other distro command.
+ *
+ * Consuming the seam is deliberately not part of this: `dsh-tool-bash` reads
+ * `ctx.shell.sandboxMode` (the executor's capability fact) plus
+ * `ctx.sandboxPolicy`, and never asks `ctx.sandbox` for anything. A WSL
+ * executor can therefore own its confinement without shadowing the
+ * composition-level provider that host sessions still need.
+ *
+ * ## Fidelity to the upstream Linux rung
+ *
+ * The profile arguments, the denial dialect and the runner-failure rules mirror
+ * `@deepseek-ai/dsh-sandbox-local`'s `bwrap` rung, so a denial reads the same to
+ * the tool layer whether the command ran on a Linux host or inside a distro.
+ * The one deliberate difference is {@link ENFORCEMENT}: see its doc.
+ *
+ * @module dsh-plugin-wsl/sandbox
+ */
+
+import { SandboxUnavailableError } from "@deepseek-ai/dsh-sandbox";
+import { toLinuxPath } from "./paths.js";
+import { runCapture } from "./wsl.js";
+
+/**
+ * bwrap's denial dialect: a write outside the granted mounts fails with EROFS,
+ * whose message is "Read-only file system". Classified case-insensitively.
+ */
+const DENIAL_SIGNATURES = ["read-only file system"];
+
+/**
+ * Runner-side diagnostics. Bubblewrap reports its own failures with a `bwrap: `
+ * prefix and exits 1; exit status alone never proves runner failure (the
+ * upstream rule is signature-only for exactly that reason), so a confined
+ * command that merely prints the signature is not misread as "never ran".
+ */
+const RUNNER_FAILURE_RULES = [{ fatalSignatures: ["bwrap: "] }];
+
+/**
+ * Enforcement is **partial**, not `full` like upstream's Linux rung.
+ *
+ * `SandboxMode` governs file effects. A Linux process under bwrap is fully
+ * governed — but a WSL distro process can execute a *Windows* binary through
+ * interop (`/mnt/c/**\*.exe`), and that Windows process runs outside the Linux
+ * sandbox entirely, under the user's ordinary Windows token: it can write
+ * anywhere the user can. `npm run probe:sandbox` demonstrates it. Claiming
+ * `full` would advertise a boundary that does not hold, so the provider reports
+ * the honest `partial` and README states where the hole is.
+ */
+const ENFORCEMENT = "partial";
+
+/** Probe verdicts, keyed by `wslPath\0distro`; the probe spawns once per pair. */
+const probeVerdicts = new Map();
+
+/**
+ * Build the bwrap profile arguments for one file-effect policy, exactly as
+ * upstream's `bwrapProfileArgs` does.
+ *
+ * `--ro-bind / /` makes the whole distro read-only, `--dev /dev` supplies the
+ * `/dev/null` sink a shell needs, `--unshare-pid` keeps the sandbox's process
+ * view its own, and `--proc /proc` gives it a matching `/proc`. Under
+ * `workspace-write` the workspace is bound read-write and `/tmp` becomes an
+ * ephemeral tmpfs — the temp area the mode promises, without exposing the
+ * distro's real `/tmp`.
+ *
+ * @param policy - the policy to express as bwrap mounts.
+ * @returns profile arguments, before the `--` separator and the command argv.
+ */
+export function bwrapProfileArgs(policy) {
+  const args = ["--ro-bind", "/", "/", "--dev", "/dev", "--unshare-pid", "--proc", "/proc", "--die-with-parent"];
+  if (policy.mode === "workspace-write") {
+    args.push("--tmpfs", "/tmp");
+    args.push("--bind", policy.workspaceRoot, policy.workspaceRoot);
+  }
+  return args;
+}
+
+/**
+ * Confine commands inside one distro with `bwrap`.
+ *
+ * The policy's `workspaceRoot` arrives in whichever coordinate system the
+ * caller speaks — a session workspace is a UNC path — and is translated into the
+ * Linux path `bwrap` must bind inside the distro.
+ */
+export class WslSandbox {
+  /**
+   * @param config - the `wsl.exe` path, overridable for a non-standard install.
+   */
+  constructor(config = {}) {
+    this.wslPath = config.wslPath ?? "wsl.exe";
+  }
+
+  /**
+   * Whether `bwrap` can create a profile inside this distro, probed once per
+   * (`wslPath`, distro) pair. The probe mirrors upstream's: apply the real
+   * read-only profile around `true`, and treat a zero exit as the kernel having
+   * accepted and enforced it. A missing `bwrap` fails the spawn and probes
+   * unusable, which is what makes the provider fail closed rather than silently
+   * run unconfined.
+   *
+   * @param distro - the distro to probe.
+   * @param signal - optional cancellation.
+   * @returns true when a confined command can run there.
+   */
+  async usable(distro, signal) {
+    const key = `${this.wslPath}\u0000${distro}`;
+    const cached = probeVerdicts.get(key);
+    if (cached !== undefined) return cached;
+    let verdict = false;
+    try {
+      const profile = bwrapProfileArgs({ mode: "read-only", workspaceRoot: "/" });
+      await runCapture([this.wslPath, "-d", distro, "--exec", "bwrap", ...profile, "--", "true"], signal);
+      verdict = true;
+    } catch {
+      verdict = false;
+    }
+    probeVerdicts.set(key, verdict);
+    return verdict;
+  }
+
+  /**
+   * Wrap one distro-side argv in the bwrap profile the policy asks for.
+   *
+   * @param argv - the argv to run INSIDE the distro (shell, its flags, command).
+   * @param policy - the resolved confined policy (`mode` is never
+   *   `danger-full-access`; the caller does not confine that case at all).
+   * @param options - the distro to run in and optional cancellation.
+   * @returns the wrapped argv plus the settlement-classification facts, in the
+   *   seam's `ConfinedArgv` shape.
+   * @throws SandboxUnavailableError when the distro has no usable `bwrap`, so a
+   *   requested confinement never degrades into an unconfined run.
+   */
+  async confine(argv, policy, options) {
+    const { distro, signal } = options;
+    if (!(await this.usable(distro, signal))) {
+      throw new SandboxUnavailableError(
+        policy.mode,
+        `bwrap is not usable inside distro "${distro}" (install it: sudo apt install bubblewrap)`,
+      );
+    }
+    const workspaceRoot = toLinuxPath(policy.workspaceRoot, { distro });
+    const profile = bwrapProfileArgs({ ...policy, workspaceRoot });
+    return {
+      argv: ["bwrap", ...profile, "--", ...argv],
+      enforcement: ENFORCEMENT,
+      denialSignatures: DENIAL_SIGNATURES,
+      runnerFailureRules: RUNNER_FAILURE_RULES,
+    };
+  }
+}
+
+export default WslSandbox;

package/lib/shell-env.js

@@ -0,0 +1,74 @@
+/**
+ * Contribute the WSL environment's facts to the managed `DSH_*` namespace.
+ *
+ * `dsh-shell-env` owns `ctx.shellEnv`, the registry that rebuilds the trusted
+ * `DSH_*` variables injected into every model shell call. That is DSH's sanctioned
+ * channel for telling a model what its shell environment actually is — the shell
+ * tool's own description points the model at it ("Managed `$DSH_*` variables
+ * expose current harness environment facts").
+ *
+ * It has one built-in key that looks like it should carry this, and does not:
+ *
+ *     collect() { const values = { [DSH_HOME_ENV]: this.dshHome, [DSH_SHELL_KEY]: "1" } }
+ *
+ * `DSH_SHELL` is a marker FLAG (`=1`) meaning "a DSH-managed shell call", not the
+ * shell path, and it is in `RESERVED_BASH_ENV_KEYS`, so a contributor may not own
+ * it. The supported way to convey the real shell is a `DSH_`-prefixed key of our
+ * own, declared with a description and resolved synchronously.
+ *
+ * Scoping uses the same test as `auto-preset`: the agent's recorded workspace
+ * directory. A session whose workspace is inside a distro is exactly a session
+ * whose shell calls run in that distro — so a host session sees none of these.
+ *
+ * @module dsh-plugin-wsl/shell-env
+ */
+
+import z from "@deepseek-ai/schemastery";
+import { isWslUnc } from "./paths.js";
+import { defaultDistro, defaultShell, linuxHomePath } from "./wsl.js";
+
+export const name = "wsl-shell-env";
+
+export const inject = ["shellEnv"];
+
+export const Config = z.object({
+  /** Distro these facts describe; empty means this machine's default distro. */
+  distro: z.string().default(""),
+});
+
+export async function apply(ctx, config = {}) {
+  // `resolve` is called synchronously by the registry (`Object.entries` of its
+  // result), so every fact has to be resolved up front, not per call.
+  const configured = config.distro ?? "";
+  const distro = configured.length > 0 ? configured : await defaultDistro();
+  const shell = await defaultShell(distro);
+  // The consumer is a shell running INSIDE the distro, so the fact is the POSIX
+  // path, not the host-side world path.
+  const home = await linuxHomePath(distro);
+
+  const variables = {
+    DSH_WSL_DISTRO: {
+      description: `Name of the WSL distro this workspace lives in (${distro}).`,
+    },
+    DSH_WSL_SHELL: {
+      description: `Absolute path of the login shell that model shell calls run in inside ${distro}. Commands are executed by this shell, not by bash.`,
+    },
+    DSH_WSL_HOME: {
+      description: `Home directory of the user model shell calls run as inside ${distro}.`,
+    },
+  };
+
+  const dispose = ctx.shellEnv.register({
+    name: "dsh-plugin-wsl-env",
+    variables,
+    resolve: (execution) => {
+      const cwd = execution?.agent?.session?.header?.cwd;
+      if (!isWslUnc(cwd)) return {};
+      return { DSH_WSL_DISTRO: distro, DSH_WSL_SHELL: shell, DSH_WSL_HOME: home };
+    },
+  });
+
+  // Disposing matters: a config hot-reload re-runs apply(), and the registry
+  // rejects a second contributor claiming the same keys.
+  ctx.effect(() => dispose);
+}

package/lib/shell.js

@@ -0,0 +1,5 @@
+/**
+ * `ctx.shell` entrypoint — load as `dsh-plugin-wsl` in a profile patch.
+ * @module dsh-plugin-wsl/shell
+ */
+export { WslShellExecutor as default, WslShellExecutor } from "./index.js";