dsh-plugin-wsl-env 0.1.10 → 0.3.0

package/lib/sandbox.js

@@ -32,6 +32,12 @@ import { SandboxUnavailableError } from "@deepseek-ai/dsh-sandbox";
 import { createProbeCache } from "./probe-cache.js";
 import { toLinuxPath } from "./paths.js";
 import { runCapture } from "./wsl.js";
+import { bwrapArgvPrefix, bwrapProfileArgs } from "./bwrap.js";
+
+// The profile and the argv prefix are also what `lib/agent-confined.js` builds
+// for its residents, so both live in the peer-free `lib/bwrap.js` and are
+// re-exported here, where the sandbox's callers have always found them.
+export { bwrapProfileArgs };
 
 /**
  * bwrap's denial dialect: a write outside the granted mounts fails with EROFS,
@@ -60,6 +66,22 @@ const RUNNER_FAILURE_RULES = [{ fatalSignatures: ["bwrap: "] }];
  */
 const ENFORCEMENT = "partial";
 
+/**
+ * The one mitigation the profile can offer, and its honest ceiling.
+ *
+ * `maskWindowsDrive` mounts an empty tmpfs over `/mnt`: the Windows drive's
+ * files vanish from the command's view, which takes the drive's data off the
+ * table and makes the on-drive executables unreachable. It does NOT make the
+ * run `full`: binfmt interop dispatches on file CONTENT, so a command that can
+ * write the workspace (which `workspace-write` grants) can write a PE there
+ * and execute it — binfmt launches it as a Windows process outside the Linux
+ * sandbox regardless of where the file sits. The only complete closures are
+ * distro-level (`[interop] enabled=false` in `wsl.conf`, which costs every
+ * legitimate interop user their tooling) — so the provider reports `partial`
+ * either way, and the mask is a decision an operator makes to shrink the hole,
+ * recorded as the `windowsDrive: "masked"` fact the model can see.
+ */
+
 /**
  * Probe verdicts, keyed by `wslPath\0distro`. The policy — a success is durable, a
  * failure is re-probed, concurrent probes are shared — lives in `probe-cache.js`,
@@ -67,29 +89,6 @@ const ENFORCEMENT = "partial";
  */
 const probeVerdicts = createProbeCache();
 
-/**
- * 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`.
  *
@@ -100,9 +99,14 @@ export function bwrapProfileArgs(policy) {
 export class WslSandbox {
   /**
    * @param config - the `wsl.exe` path, overridable for a non-standard install.
+   * @param config.maskWindowsDrive - shadow `/mnt` with an empty tmpfs in every
+   *   profile this sandbox builds, hiding the Windows drive from confined
+   *   commands (see the module doc above {@link ENFORCEMENT} for what that
+   *   does and does not close).
    */
   constructor(config = {}) {
     this.wslPath = config.wslPath ?? "wsl.exe";
+    this.maskWindowsDrive = config.maskWindowsDrive ?? false;
   }
 
   /**
@@ -123,8 +127,8 @@ export class WslSandbox {
   async usable(distro, signal) {
     const key = `${this.wslPath}\u0000${distro}`;
     return probeVerdicts.run(key, async () => {
-      const profile = bwrapProfileArgs({ mode: "read-only", workspaceRoot: "/" });
-      await runCapture([this.wslPath, "-d", distro, "--exec", "bwrap", ...profile, "--", "true"], signal);
+      const prefix = bwrapArgvPrefix({ mode: "read-only", workspaceRoot: "/" });
+      await runCapture([this.wslPath, "-d", distro, "--exec", ...prefix, "true"], signal);
       return true;
     });
   }
@@ -146,16 +150,19 @@ export class WslSandbox {
     if (!(await this.usable(distro, signal))) {
       throw new SandboxUnavailableError(
         policy.mode,
-        `bwrap is not usable inside distro "${distro}" (install it: sudo apt install bubblewrap)`,
+        `bwrap is not usable inside distro "${distro}". Install it with ` +
+          `"scripts/bootstrap.sh ${distro} --install" (from the package), or directly: ` +
+          `wsl.exe -d ${distro} -u root -- apt-get install -y bubblewrap`,
       );
     }
     const workspaceRoot = toLinuxPath(policy.workspaceRoot, { distro });
-    const profile = bwrapProfileArgs({ ...policy, workspaceRoot });
+    const prefix = bwrapArgvPrefix({ ...policy, workspaceRoot }, { maskWindowsDrive: this.maskWindowsDrive });
     return {
-      argv: ["bwrap", ...profile, "--", ...argv],
+      argv: [...prefix, ...argv],
       enforcement: ENFORCEMENT,
       denialSignatures: DENIAL_SIGNATURES,
       runnerFailureRules: RUNNER_FAILURE_RULES,
+      windowsDrive: this.maskWindowsDrive ? "masked" : "visible",
     };
   }
 }

package/lib/shell-env.js

@@ -26,6 +26,8 @@
 import z from "@deepseek-ai/schemastery";
 import { isWslUnc } from "./paths.js";
 import { defaultDistro, defaultShell, linuxHomePath } from "./wsl.js";
+import { sharedAgent } from "./agent-shared.js";
+import { listeningPorts } from "./ports.js";
 
 export const name = "wsl-shell-env";
 
@@ -34,6 +36,8 @@ export const inject = ["shellEnv"];
 export const Config = z.object({
   /** Distro these facts describe; empty means this machine's default distro. */
   distro: z.string().default(""),
+  /** How often the listening-port snapshot refreshes, in milliseconds. */
+  portsRefreshMs: z.number().default(10 * 1000),
 });
 
 export async function apply(ctx, config = {}) {
@@ -56,7 +60,21 @@ export async function apply(ctx, config = {}) {
     DSH_WSL_HOME: {
       description: `Home directory of the user model shell calls run as inside ${distro}.`,
     },
+    DSH_WSL_PORTS: {
+      description: `Ports with a listener inside ${distro} (comma-separated, ascending), as of the last snapshot — refreshed every ${Math.round(config.portsRefreshMs / 1000)}s, so a dev server started moments ago may not be listed yet. Empty means none were listening at the last scan.`,
+    },
+  };
+
+  // The port snapshot refreshes on a timer and is served synchronously: the
+  // registry's resolve is sync by contract, so live reads are impossible —
+  // the timer bounds staleness instead (see lib/ports.js).
+  let ports = [];
+  const refreshPorts = async () => {
+    ports = await listeningPorts(sharedAgent(distro), 8000);
   };
+  void refreshPorts();
+  const portsTimer = setInterval(() => void refreshPorts(), config.portsRefreshMs);
+  portsTimer.unref?.();
 
   const dispose = ctx.shellEnv.register({
     name: "dsh-plugin-wsl-env",
@@ -64,11 +82,19 @@ export async function apply(ctx, config = {}) {
     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 };
+      return {
+        DSH_WSL_DISTRO: distro,
+        DSH_WSL_SHELL: shell,
+        DSH_WSL_HOME: home,
+        DSH_WSL_PORTS: ports.join(","),
+      };
     },
   });
 
   // Disposing matters: a config hot-reload re-runs apply(), and the registry
   // rejects a second contributor claiming the same keys.
-  ctx.effect(() => dispose);
+  ctx.effect(() => {
+    clearInterval(portsTimer);
+    dispose();
+  });
 }

package/lib/subprocess.js

@@ -74,6 +74,7 @@ import z from "@deepseek-ai/schemastery";
 import { LocalSubprocessRuntime } from "@deepseek-ai/dsh-subprocess-local";
 import { isPosixAbsolute, toLinuxPath, uncToPosix, windowsToLinuxMount } from "./paths.js";
 import { DEFAULT_WSL_PATH, defaultDistro, wslEnvValue, wslTerminalArgv } from "./wsl.js";
+import { terminalRoute } from "./terminal-route.js";
 
 /**
  * Env names a terminal launch keeps for the distro. `TERM` rides along because
@@ -120,6 +121,13 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
     hostCwd: z.string().volatile(),
     /** Extra env names to forward into the distro through WSLENV. */
     forwardEnv: z.array(z.string()).default([]),
+    /**
+     * Give a session opened on a WINDOWS folder a host shell instead of the
+     * distro's shell started at `/mnt/<drive>/…`. WSL-folder sessions always
+     * get the distro shell — that is this provider's purpose. `false` restores
+     * the composition-owned terminal for every session.
+     */
+    hostSessions: z.boolean().default(true),
   });
 
   constructor(ctx, config) {
@@ -185,6 +193,13 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
    */
   async spawnTerminal(spec) {
     if (!this.launchesDistro(spec.argv)) return super.spawnTerminal(spec);
+    // A session on a Windows folder is a HOST session: it gets the host shell
+    // in its own directory, not the distro's shell at `/mnt/<drive>/…`. The
+    // wsl.exe argv still names this provider's launch, so the substitution
+    // stays inside the override — every other consumer is untouched.
+    if (this.config.hostSessions && terminalRoute(spec.cwd) === "host") {
+      return super.spawnTerminal({ ...spec, argv: ["powershell.exe", "-NoLogo"] });
+    }
     const target = await this.terminalTarget(spec.cwd);
     const argv = wslTerminalArgv({
       wslPath: this.config.wslPath,

package/lib/terminal-route.js

@@ -0,0 +1,31 @@
+/**
+ * Which execution world a terminal launch belongs to.
+ *
+ * The terminal controller hands this provider the request's directory, and the
+ * directory's coordinate system is the evidence of intent: a UNC path under a
+ * distro's share names a WSL session outright, a POSIX absolute path is a
+ * distro path by construction, and a Windows drive path is a session opened on
+ * a Windows folder — which deserves a HOST shell, not the distro's shell
+ * started at `/mnt/<drive>/…`. An empty directory carries no evidence either
+ * way and defaults to the distro, which is what a profile pins.
+ *
+ * Pure by construction.
+ *
+ * @module dsh-plugin-wsl/terminal-route
+ */
+
+import { isPosixAbsolute, uncToPosix, windowsToLinuxMount } from "./paths.js";
+
+/**
+ * @param cwd - the terminal request's working directory, any coordinate system.
+ * @returns `"distro"` when the launch belongs inside the pinned distro,
+ *   `"host"` when it belongs to a Windows-folder session.
+ */
+export function terminalRoute(cwd) {
+  const text = String(cwd ?? "").trim();
+  if (text.length === 0) return "distro";
+  if (uncToPosix(text) !== undefined) return "distro";
+  if (isPosixAbsolute(text)) return "distro";
+  if (windowsToLinuxMount(text) !== undefined) return "host";
+  return "distro";
+}

package/lib/watcher.js

@@ -0,0 +1,127 @@
+/**
+ * In-distro file watching for `WslFileSystem.watch`.
+ *
+ * A 9p share gives Node no usable change notification — chokidar over
+ * `\\wsl.localhost` is the unreliability that made this provider refuse to
+ * watch at all. The seam's contract, however, asks for far less than events:
+ * `watch(target, changed, signal)` wants ONE invalidation callback, invoked
+ * whenever something under `target` may have changed. That is cheap to honor
+ * from inside the distro, where the kernel does know.
+ *
+ * The watcher is a long-lived `wsl.exe` shell loop: periodically
+ * `find <dir> -newer <stamp>` — the directory itself is in the scan, so
+ * creations AND deletions (which bump the parent's mtime) are both seen — and
+ * one `C` line per hit. No `inotifywait` dependency; the mtime walk is exact
+ * for interactive-paced edits, which is the only pace a session watch serves.
+ *
+ * Known blind spot, accepted and documented: a file created with an mtime
+ * older than the stamp (`cp -p`, `tar -x`) is not seen until something else
+ * touches the tree.
+ *
+ * @module dsh-plugin-wsl/watcher
+ */
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+/**
+ * The shell loop the watcher runs, parameterised by argv so no path can break
+ * quoting: `$1` is the Linux directory, `$2` the poll interval in seconds.
+ * Pure text, so it is unit-testable.
+ * @param {number} [intervalSeconds] - poll cadence; must be >= 1.
+ * @returns {string} the `sh -c` script body.
+ */
+export function watchLoopScript(intervalSeconds = 2) {
+  const seconds = Math.max(1, Math.floor(intervalSeconds));
+  // `find` lists the directory itself first: a child's creation or deletion
+  // bumps the parent's mtime, so both edges are seen, not just modifications.
+  return [
+    'D="$1"',
+    'S="${TMPDIR:-/tmp}/wsl-watch.$$.stamp"',
+    'touch "$S"',
+    // The READY line is the activation barrier: everything changed BEFORE it
+    // predates the stamp, so the host must not resolve the watch promise until
+    // it arrives — otherwise a write racing the first tick is invisible forever.
+    'printf \'R\\n\'',
+    // Check first, sleep second: a change made right after activation is seen
+    // on the first cadence, not one cadence later.
+    'while :; do',
+    '  if [ -n "$(find "$D" -newer "$S" -print -quit 2>/dev/null)" ]; then',
+    '    touch "$S"',
+    '    printf \'C\\n\'',
+    '  fi',
+    `  sleep ${seconds}`,
+    'done',
+  ].join("\n");
+}
+
+/**
+ * Arm one in-distro watcher over a Linux directory.
+ *
+ * @param {object} options - the watch request.
+ * @param {string} options.wslPath - the `wsl.exe` path.
+ * @param {string} options.distro - the distro to watch inside.
+ * @param {string} options.linuxPath - the absolute Linux path to observe.
+ * @param {(error: Error) => void} [options.onError] - watcher-level failures
+ *   (an exited loop); the seam reports these through its own channel.
+ * @param {() => void} options.onChange - the invalidation callback.
+ * @param {AbortSignal} options.signal - cancels initialization; the CALLER
+ *   invokes the returned close to stop an armed watcher.
+ * @param {number} [options.intervalSeconds] - poll cadence, default 2.
+ * @param {(wslPath: string, args: string[]) => import("node:child_process").ChildProcess} [options.spawn]
+ *   injectable process factory for tests.
+ * @returns {Promise<() => Promise<void>>} resolves once observation is active,
+ *   with the async close function the seam's contract asks for.
+ */
+export function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError, signal, intervalSeconds = 2, spawn: spawnProcess }) {
+  const doSpawn = spawnProcess ?? ((path, args) => spawn(path, args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true }));
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+      return;
+    }
+    const child = doSpawn(wslPath, ["-d", distro, "--exec", "sh", "-c", watchLoopScript(intervalSeconds), "wsl-watch", linuxPath]);
+    let settled = false;
+    let closed = false;
+    const lines = createInterface({ input: child.stdout });
+    lines.on("line", (line) => {
+      if (line === "R") {
+        if (!settled && !signal?.aborted) {
+          settled = true;
+          resolve(close);
+        }
+        return;
+      }
+      if (line === "C") {
+        onChange();
+      }
+    });
+    const close = async () => {
+      if (closed) return;
+      closed = true;
+      child.removeAllListeners("exit");
+      lines.close();
+      child.stdout.destroy();
+      child.kill();
+      await new Promise((resolveClose) => {
+        if (child.exitCode !== null || child.signalCode !== null) return resolveClose();
+        child.once("exit", resolveClose);
+      });
+    };
+    const fail = (error) => {
+      if (settled) {
+        onError?.(error);
+        return;
+      }
+      settled = true;
+      void close();
+      reject(error);
+    };
+    signal?.addEventListener("abort", () => fail(signal.reason instanceof Error ? signal.reason : new Error("aborted")), { once: true });
+    child.on("error", fail);
+    child.on("exit", (code, signalName) => {
+      if (!closed) fail(new Error(`distro watcher exited unexpectedly (code=${code} signal=${signalName ?? "none"})`));
+    });
+
+  });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.1.10",
-  "description": "Run a DeepSeek Harness session against a WSL distro: commands and the model's file tools run inside it, the folder picker and the GUI terminal open there, and commands are confined by bubblewrap inside the distro",
+  "version": "0.3.0",
+  "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
     "dsh",
@@ -22,6 +22,7 @@
     "./shell-env": "./lib/shell-env.js",
     "./wsl": "./lib/wsl.js",
     "./paths": "./lib/paths.js",
+    "./agent": "./lib/agent.js",
     "./package.json": "./package.json"
   },
   "dsh": {
@@ -31,12 +32,16 @@
   },
   "files": [
     "lib/**/*.js",
+    "agent/*.sh",
     "cordis.patch.yml",
     "examples/**/*.yml",
     "README.md",
     "docs/README.zh.md",
     "docs/CONFIGURATION.md",
     "docs/LIMITATIONS.md",
+    "docs/PARITY.md",
+    "docs/PEER-PARITY.md",
+    "docs/UPSTREAM-FSIO-EXPORT.md",
     "docs/ARCHITECTURE.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
@@ -48,7 +53,7 @@
     "test": "npm run lint:style && npm run test:syntax && npm run test:unit",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=85 --test-coverage-functions=70 test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs",
     "test:syntax": "node test/syntax.mjs",
-    "test:unit": "node --test test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs",
+    "test:unit": "node --test test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/fs-publish.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "npm test",
     "probe": "bash test/probe/run.sh",
@@ -59,7 +64,11 @@
     "probe:terminal": "bash test/probe/terminal.sh",
     "probe:sandbox": "bash test/probe/sandbox.sh",
     "probe:sandbox-shell": "bash test/probe/sandbox-shell.sh",
-    "sync:windows": "bash test/probe/sync-to-windows.sh"
+    "sync:windows": "bash test/probe/sync-to-windows.sh",
+    "probe:watch": "bash test/probe/watch.sh",
+    "probe:substrate": "bash test/probe/substrate.sh",
+    "probe:exec": "bash test/probe/exec.sh",
+    "bootstrap": "bash scripts/bootstrap.sh"
   },
   "engines": {
     "node": ">=20"