dsh-plugin-wsl-env 0.7.5 → 0.8.0

package/lib/sandbox.js

@@ -30,21 +30,21 @@
  * module is the shipped binding that hands it the peer's `SandboxUnavailableError`,
  * so `instanceof` consumers keep matching the class their composition knows.
  *
+ * This is a TypeScript source built to `lib/sandbox.js`; edit THIS file and run
+ * `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ *
  * @module dsh-plugin-wsl/sandbox
  */
-
 import { SandboxUnavailableError } from "@deepseek-ai/dsh-sandbox";
 import { createSandboxCore } from "./sandbox-core.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 } from "./bwrap.js";
-
 /**
  * The confinement over WSL: the probe-then-confine class bound to the peer's
  * failure type. See the core module for the probe policy and the profile.
  */
 export const WslSandbox = createSandboxCore({ SandboxUnavailableError });
-
 export default WslSandbox;

package/lib/search-exec.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The agent-backed execution handle for the file-search spawn.
+ *
+ * `dsh-tool-fs-search` consumes a deliberately small slice of the subprocess
+ * handle: it awaits `handle.done` for `{exitCode, signal}`, then reads
+ * `handle.collected.stdout/stderr.readFrom(0)` — nothing else. This module
+ * builds exactly that surface around one resident-agent `exec`, so a distro
+ * search pays one round trip on the warm agent (~10 ms) instead of a one-shot
+ * `wsl.exe` spawn (~400 ms of process startup for a few ms of rg).
+ *
+ * The agent being out is not an error condition here — it is the fallback
+ * cue. `spawnFallback` (the shipped one-shot handle the caller builds) is
+ * consulted lazily inside `done`; from that point the facade proxies the
+ * delegate's `collected` and `done` verbatim. Neither transport ever touches
+ * the 9p share.
+ *
+ * Cancellation shares one channel: the caller's `signal` and `kill()` abort
+ * the agent exec, which settles `done` as killed (`{exitCode: null, signal:
+ * "SIGTERM"}`) — the same shape the one-shot path reports for a killed search.
+ * A genuine agent failure (anything but unavailability) propagates through
+ * `done` as a rejection, which the tool classifies as a search failure.
+ *
+ * Pure shaping over injected collaborators, so the handle semantics are
+ * unit-testable without a distro.
+ *
+ * This is a TypeScript source built to `lib/search-exec.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/search-exec
+ */
+import type { AgentExecRunner } from "./agent-exec.js";
+/**
+ * The output-stream reader the search tool consumes: `handle.collected.stdout`
+ * / `stderr` expose `readFrom(offset)` with the seam's standard shape.
+ */
+export interface SearchCollectedReader {
+    /** Read the stream from a byte offset. */
+    readFrom: (from: number) => {
+        text: string;
+        lossy: boolean;
+        nextOffset: number;
+    };
+}
+/**
+ * The slice of the subprocess handle the file-search tool consumes
+ * (`dsh-tool-fs-search` `runRipgrep`): settle on `done`, then read the
+ * collected streams. Nothing else of the handle is contract.
+ */
+export interface SearchExecutionHandle {
+    /** Settles with the exit code and signal; rejects on a genuine failure. */
+    done: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    /** The collected stream readers; a delegated handle's own on fallback. */
+    collected: {
+        stdout?: SearchCollectedReader | undefined;
+        stderr?: SearchCollectedReader | undefined;
+    };
+    /**
+     * Optional cooperative kill; the tool relies on its `signal` for
+     * cancellation instead.
+     */
+    kill?: () => boolean | void;
+}
+/**
+ * Run one search command through the agent and present it as a search handle.
+ *
+ * @param object - the handle's collaborators.
+ * @returns the search handle (`done`, `collected`, `kill`).
+ */
+export declare function searchExecutionHandle({ agent, cwd, argv, maxOutputBytes, signal, spawnFallback }: {
+    /**
+     * The {@link WslAgent}-like runner: `exec` accepting
+     * `{cwd, argv, maxOutputBytes, signal}` and resolving
+     * `{exitCode, stdout, stderr}`; throws `AgentUnavailableError` when out.
+     */
+    agent: AgentExecRunner;
+    /** The Linux working directory to search from. */
+    cwd: string;
+    /** The distro-side argv (`rg` and its arguments). */
+    argv: string[];
+    /**
+     * Per-stream capture ceiling the agent enforces; the tool's own raw-output
+     * budget rides here.
+     */
+    maxOutputBytes?: number;
+    /** The caller's cancellation. */
+    signal?: AbortSignal;
+    /**
+     * Builds the one-shot handle the facade delegates to when the agent is out;
+     * called at most once, lazily.
+     */
+    spawnFallback: () => SearchExecutionHandle;
+}): SearchExecutionHandle;

package/lib/search-exec.js

@@ -23,92 +23,65 @@
  * Pure shaping over injected collaborators, so the handle semantics are
  * unit-testable without a distro.
  *
+ * This is a TypeScript source built to `lib/search-exec.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ *
  * @module dsh-plugin-wsl/search-exec
  */
-
 import { AgentUnavailableError } from "./agent-errors.js";
-
-/**
- * The output-stream reader the search tool consumes: `handle.collected.stdout`
- * / `stderr` expose `readFrom(offset)` with the seam's standard shape.
- *
- * @typedef {Object} SearchCollectedReader
- * @property {(from: number) => {text: string, lossy: boolean, nextOffset: number}} readFrom
- */
-
-/**
- * The slice of the subprocess handle the file-search tool consumes
- * (`dsh-tool-fs-search` `runRipgrep`): settle on `done`, then read the
- * collected streams. Nothing else of the handle is contract.
- *
- * @typedef {Object} SearchExecutionHandle
- * @property {Promise<{exitCode: number|null, signal: string|null}>} done
- * @property {{stdout: SearchCollectedReader, stderr: SearchCollectedReader}} collected
- * @property {() => boolean|void} [kill] - optional cooperative kill; the tool
- *   relies on its `signal` for cancellation instead.
- */
-
 /**
  * Run one search command through the agent and present it as a search handle.
  *
  * @param object - the handle's collaborators.
- * @param {object} object.agent - the {@link WslAgent}-like runner: `exec`
- *   accepting `{cwd, argv, maxOutputBytes, signal}` and resolving
- *   `{exitCode, stdout, stderr}`; throws `AgentUnavailableError` when out.
- * @param {string} object.cwd - the Linux working directory to search from.
- * @param {string[]} object.argv - the distro-side argv (`rg` and its arguments).
- * @param {number} [object.maxOutputBytes] - per-stream capture ceiling the
- *   agent enforces; the tool's own raw-output budget rides here.
- * @param {AbortSignal} [object.signal] - the caller's cancellation.
- * @param {() => object} object.spawnFallback - builds the one-shot handle the
- *   facade delegates to when the agent is out; called at most once, lazily.
- * @returns {object} the search handle (`done`, `collected`, `kill`).
+ * @returns the search handle (`done`, `collected`, `kill`).
  */
 export function searchExecutionHandle({ agent, cwd, argv, maxOutputBytes = 0, signal, spawnFallback }) {
-  const state = { delegate: undefined, stdout: undefined, stderr: undefined };
-  const controller = new AbortController();
-  if (signal?.aborted) controller.abort(signal.reason);
-  else signal?.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
-
-  const reader = (slot) => ({
-    readFrom(from) {
-      const buffer = state[slot] ?? Buffer.alloc(0);
-      const start = Math.min(from, buffer.length);
-      return { text: buffer.subarray(start).toString("utf8"), lossy: false, nextOffset: buffer.length };
-    },
-  });
-
-  /** @type {object} */
-  const handle = {
-    get collected() {
-      if (state.delegate !== undefined) return state.delegate.collected;
-      return { stdout: reader("stdout"), stderr: reader("stderr") };
-    },
-    done: (async () => {
-      let result;
-      try {
-        result = await agent.exec({ cwd, argv, maxOutputBytes, signal: controller.signal });
-        state.stdout = result.stdout;
-        state.stderr = result.stderr;
-      } catch (error) {
-        if (!(error instanceof AgentUnavailableError)) {
-          if (controller.signal.aborted) {
-            // Our kill() or the caller's cancellation: the killed outcome the
-            // one-shot path reports, not a failure.
-            return { exitCode: null, signal: "SIGTERM" };
-          }
-          throw error;
-        }
-        const delegate = spawnFallback();
-        state.delegate = delegate;
-        return delegate.done;
-      }
-      return { exitCode: result.exitCode, signal: null };
-    })(),
-    kill() {
-      controller.abort(new Error("killed"));
-      state.delegate?.kill?.();
-    },
-  };
-  return handle;
+    const state = { delegate: undefined, stdout: undefined, stderr: undefined };
+    const controller = new AbortController();
+    if (signal?.aborted)
+        controller.abort(signal.reason);
+    else
+        signal?.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+    const reader = (slot) => ({
+        readFrom(from) {
+            const buffer = state[slot] ?? Buffer.alloc(0);
+            const start = Math.min(from, buffer.length);
+            return { text: buffer.subarray(start).toString("utf8"), lossy: false, nextOffset: buffer.length };
+        },
+    });
+    const handle = {
+        get collected() {
+            if (state.delegate !== undefined)
+                return state.delegate.collected;
+            return { stdout: reader("stdout"), stderr: reader("stderr") };
+        },
+        done: (async () => {
+            let result;
+            try {
+                result = await agent.exec({ cwd, argv, maxOutputBytes, signal: controller.signal });
+                state.stdout = result.stdout;
+                state.stderr = result.stderr;
+            }
+            catch (error) {
+                if (!(error instanceof AgentUnavailableError)) {
+                    if (controller.signal.aborted) {
+                        // Our kill() or the caller's cancellation: the killed outcome the
+                        // one-shot path reports, not a failure.
+                        return { exitCode: null, signal: "SIGTERM" };
+                    }
+                    throw error;
+                }
+                const delegate = spawnFallback();
+                state.delegate = delegate;
+                return delegate.done;
+            }
+            return { exitCode: result.exitCode, signal: null };
+        })(),
+        kill() {
+            controller.abort(new Error("killed"));
+            state.delegate?.kill?.();
+        },
+    };
+    return handle;
 }

package/lib/search-route.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Which execution world a file-search spawn belongs to, and the `wsl.exe`
+ * argv it becomes there.
+ *
+ * `dsh-tool-fs-search` spawns the packaged ripgrep binary through
+ * `ctx.subprocess` with the session workspace as the working directory. Left
+ * alone, that spawn runs the Windows binary over the distro's 9p share — the
+ * one model-facing I/O path that still crossed the share, and in the slow
+ * direction: measured at ~17 ms per file of metadata round trips where the
+ * distro's own ext4 answers in microseconds. The interception point is the
+ * subprocess provider's `spawn`, and the decision lives here — pure,
+ * peer-free, and unit-testable, mirroring `terminal-route.js`.
+ *
+ * The rewrite is deliberately narrow. A spawn is intercepted only when the
+ * working directory NAMES the distro outright — a `\\wsl.localhost\<distro>`
+ * UNC — because that is the form a distro session's search carries and the
+ * only one that resolves without an async distro query: `spawn` hands back
+ * its handle synchronously, so the override must stay synchronous. A Windows
+ * drive directory keeps the host binary, which is native there and touches
+ * no share; anything else passes through untouched, exactly as before.
+ *
+ * The rewritten argv forwards every rg argument verbatim, so the tool reads
+ * the output format and exit codes of the distro's own rg. One addition is
+ * made: when the tool named no search path — its pattern rides `--regexp=`,
+ * and a bare `--` separator is exactly how it spells an explicit path — the
+ * rewrite appends `-- .`. Reason: `wsl.exe --exec` hands the distro-side rg a
+ * relay FIFO for stdin, and rg's readable-stdin heuristic then searches stdin
+ * (instantly empty) instead of walking the working directory; the packaged
+ * binary under the old path saw a non-readable NUL stdin and walked it. An
+ * explicit path makes the search deterministic on either transport.
+ *
+ * The distro-side binary must therefore exist — `scripts/bootstrap.sh` reports
+ * it — and a distro without one surfaces rg's own "command not found" instead
+ * of a silent fall-back to the share.
+ *
+ * This is a TypeScript source built to `lib/search-route.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/search-route
+ */
+/**
+ * Whether a spawn's program is the ripgrep binary.
+ *
+ * A bare `argv[0]` is judged by its own name, so the packaged binary's
+ * absolute path and any other spelling of `rg` match alike.
+ *
+ * @param program - the spawn's `argv[0]`.
+ * @returns true when the spawn is a ripgrep launch.
+ */
+export declare function isSearchProgram(program: unknown): boolean;
+/**
+ * The distro-side rewrite of one search spawn, when it belongs in the distro.
+ *
+ * Two argv forms come back for one decision. `rgArgv` is the distro command
+ * itself (`rg` and its arguments) — what the resident agent execs. `wslArgv`
+ * is the same command wrapped for a one-shot `wsl.exe --exec` launch — the
+ * fallback transport for when the agent is out. The working directory becomes
+ * the `--cd` the distro starts in; `wsl.exe` itself must start in a Windows
+ * directory, so the caller supplies its own host cwd when applying `wslArgv`.
+ *
+ * @param object - the spawn's inputs.
+ * @returns the rewrite, or undefined when the spawn is not a distro search and
+ *   must run exactly as the shipped implementation would run it.
+ */
+export declare function searchSpawnRewrite({ argv, cwd, wslPath }: {
+    argv: readonly string[];
+    cwd: string;
+    wslPath: string;
+}): {
+    distro: string;
+    linuxCwd: string;
+    rgArgv: string[];
+    wslArgv: string[];
+} | undefined;

package/lib/search-route.js

@@ -33,29 +33,30 @@
  * it — and a distro without one surfaces rg's own "command not found" instead
  * of a silent fall-back to the share.
  *
+ * This is a TypeScript source built to `lib/search-route.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
  * @module dsh-plugin-wsl/search-route
  */
-
 import { uncToPosix } from "./paths.js";
-
 /** The one program this rewrite passes through to the distro. */
 const SEARCH_PROGRAM = "rg";
-
 /**
  * Whether a spawn's program is the ripgrep binary.
  *
  * A bare `argv[0]` is judged by its own name, so the packaged binary's
  * absolute path and any other spelling of `rg` match alike.
  *
- * @param unknown - the spawn's `argv[0]`.
+ * @param program - the spawn's `argv[0]`.
  * @returns true when the spawn is a ripgrep launch.
  */
 export function isSearchProgram(program) {
-  if (typeof program !== "string" || program.length === 0) return false;
-  const base = program.slice(Math.max(program.lastIndexOf("/"), program.lastIndexOf("\\")) + 1);
-  return base.toLowerCase().replace(/\.exe$/u, "") === SEARCH_PROGRAM;
+    if (typeof program !== "string" || program.length === 0)
+        return false;
+    const base = program.slice(Math.max(program.lastIndexOf("/"), program.lastIndexOf("\\")) + 1);
+    return base.toLowerCase().replace(/\.exe$/u, "") === SEARCH_PROGRAM;
 }
-
 /**
  * The distro-side rewrite of one search spawn, when it belongs in the distro.
  *
@@ -67,29 +68,27 @@ export function isSearchProgram(program) {
  * directory, so the caller supplies its own host cwd when applying `wslArgv`.
  *
  * @param object - the spawn's inputs.
- * @param {unknown[]} object.argv - the spawn's argv; `argv[0]` is the program.
- * @param {unknown} object.cwd - the spawn's working directory, any coordinate system.
- * @param {string} object.wslPath - path to `wsl.exe`.
- * @returns {{distro: string, linuxCwd: string, rgArgv: string[], wslArgv: string[]}|undefined} the
- *   rewrite, or undefined when the spawn is not a distro search and must run
- *   exactly as the shipped implementation would run it.
+ * @returns the rewrite, or undefined when the spawn is not a distro search and
+ *   must run exactly as the shipped implementation would run it.
  */
 export function searchSpawnRewrite({ argv, cwd, wslPath }) {
-  if (!Array.isArray(argv) || !isSearchProgram(argv[0])) return undefined;
-  const named = uncToPosix(cwd);
-  if (named === undefined) return undefined;
-  const linuxCwd = named.linuxPath.length > 0 ? named.linuxPath : "/";
-  // No bare `--` means the tool named no search path; without one, distro-side
-  // rg reads the relay fifo on stdin (rg's readable-stdin heuristic) instead of
-  // walking the directory. `.` is the working directory — the same directory
-  // the packaged binary walked when the host spawned it directly.
-  const forwarded = argv.slice(1);
-  const tool = forwarded.includes("--") ? forwarded : [...forwarded, "--", "."];
-  const rgArgv = [SEARCH_PROGRAM, ...tool];
-  return {
-    distro: named.distro,
-    linuxCwd,
-    rgArgv,
-    wslArgv: [wslPath, "-d", named.distro, "--cd", linuxCwd, "--exec", ...rgArgv],
-  };
+    if (!Array.isArray(argv) || !isSearchProgram(argv[0]))
+        return undefined;
+    const named = uncToPosix(cwd);
+    if (named === undefined)
+        return undefined;
+    const linuxCwd = named.linuxPath.length > 0 ? named.linuxPath : "/";
+    // No bare `--` means the tool named no search path; without one, distro-side
+    // rg reads the relay fifo on stdin (rg's readable-stdin heuristic) instead of
+    // walking the directory. `.` is the working directory — the same directory
+    // the packaged binary walked when the host spawned it directly.
+    const forwarded = argv.slice(1);
+    const tool = forwarded.includes("--") ? forwarded : [...forwarded, "--", "."];
+    const rgArgv = [SEARCH_PROGRAM, ...tool];
+    return {
+        distro: named.distro,
+        linuxCwd,
+        rgArgv,
+        wslArgv: [wslPath, "-d", named.distro, "--cd", linuxCwd, "--exec", ...rgArgv],
+    };
 }

package/lib/shell-env.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ *
+ * This is a TypeScript source built to `lib/shell-env.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/shell-env
+ */
+import z from "@deepseek-ai/schemastery";
+import type { Context } from "@deepseek-ai/cordis";
+export declare const name = "wsl-shell-env";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    /** Distro these facts describe; empty means this machine's default distro. */
+    distro: z<string, string, "defined">;
+    /** How often the listening-port snapshot refreshes, in milliseconds. */
+    portsRefreshMs: z<number, number, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    /** Distro these facts describe; empty means this machine's default distro. */
+    distro: z<string, string, "defined">;
+    /** How often the listening-port snapshot refreshes, in milliseconds. */
+    portsRefreshMs: z<number, number, "defined">;
+}>>, "plain">;
+/** The config schema's validated output. */
+export interface ShellEnvConfig {
+    /** Distro these facts describe; empty means this machine's default distro. */
+    distro?: string;
+    /** How often the listening-port snapshot refreshes, in milliseconds. */
+    portsRefreshMs?: number;
+}
+/**
+ * The execution slice the shell-env registry hands a contributor's `resolve`;
+ * the harness's execution object is structural here.
+ */
+export interface ShellEnvExecution {
+    /** The executing session's agent stub. */
+    agent?: {
+        session?: {
+            header?: {
+                cwd?: string | undefined;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}
+/**
+ * The cordis context extended with the `shellEnv` registry slice this plugin
+ * contributes through. The registry belongs to the harness and its
+ * declaration is not visible to this plugin, so it is spelled structurally on
+ * top of the framework's {@link Context}.
+ */
+export type ShellEnvContext = Context & {
+    shellEnv: {
+        register: (contributor: {
+            name: string;
+            variables: Record<string, {
+                description: string;
+            }>;
+            resolve: (execution: ShellEnvExecution | undefined) => Record<string, string>;
+        }) => () => void;
+    };
+};
+/**
+ * Contribute the WSL environment's facts to the shell-env registry.
+ *
+ * @param ctx - the cordis context.
+ * @param config - the schema-validated plugin config.
+ */
+export declare function apply(ctx: ShellEnvContext, config?: ShellEnvConfig): Promise<void>;