dsh-plugin-wsl-env 0.1.10 → 0.3.0

package/lib/agent-exec.js

@@ -0,0 +1,204 @@
+/**
+ * An agent-backed implementation of the shell execution handle.
+ *
+ * `LocalBashExecutor.executeArgv` builds its handle around a subprocess spawn:
+ * live output readers with byte offsets, spill files beyond the collect
+ * budget, a deadline that kills the Windows process tree. This module builds
+ * the SAME handle shape around one agent `exec` — the shape `dsh-tool-bash`
+ * consumes, so the tool layer cannot tell which path ran. The deliberate
+ * deviations, documented here rather than hidden:
+ *
+ * - **No spill files; the capture cap is the agent's.** The EXEC frame
+ *   carries the caller's per-stream budget and the AGENT cuts stdout and
+ *   stderr at it, so a chatty command costs bounded distro memory AND bounded
+ *   host memory; the RES line's flags say which streams were cut and the
+ *   handle reports them as `truncated: true`. What the budget spares is the
+ *   upstream spill machinery: the capture is still whole-in-memory, just
+ *   whole-at-a-bounded-size.
+ * - **Killed commands report `SIGTERM`**, not a raw exit status: the
+ *   in-distro timeout and `kill()` both mean "we stopped it", and upstream
+ *   reports its own kills the same way.
+ *
+ * Pure shaping over an injected runner, so the handle semantics are
+ * unit-testable without a distro.
+ *
+ * @module dsh-plugin-wsl/agent-exec
+ */
+
+import { CwdError } from "./agent-errors.js";
+
+/**
+ * A memory-backed output reader in the seam's shape.
+ * @param {Buffer} buffer - the complete stream.
+ * @returns {{readFrom: (fromByte: number) => {text: string, lossy: boolean, nextOffset: number}}}
+ */
+function memoryReader(buffer) {
+  return {
+    readFrom(fromByte) {
+      const start = Math.min(fromByte, buffer.length);
+      return {
+        text: buffer.subarray(start).toString("utf8"),
+        lossy: false,
+        nextOffset: buffer.length,
+      };
+    },
+  };
+}
+
+/**
+ * Run one command through the agent and present it as an execution handle.
+ *
+ * @param {object} request - the execution request.
+ * @param {object} request.agent - the {@link WslAgent}-like runner: `exec`
+ *   accepting `{cwd, argv, timeoutMs, signal}` and resolving
+ *   `{exitCode, stdout, stderr}`; throws `AgentUnavailableError` when out.
+ * @param {string} request.cwd - Linux workdir.
+ * @param {string[]} request.argv - the distro-side argv, bwrap-wrapped when confined.
+ * @param {number} [request.timeoutMs] - whole-command budget; the agent TERMs
+ *   at the ceiling second and KILLs after its grace.
+ * @param {number} [request.maxOutputBytes] - per-stream capture ceiling the
+ *   agent enforces; the handle reports a cut stream as `truncated: true`.
+ * @param {AbortSignal} [request.signal] - the caller's cancellation.
+ * @param {(proc: object) => void} [request.onStarted] - provider-facts hook,
+ *   called synchronously before the handle can settle.
+ * @returns {object} the execution handle (`status`, `exitCode`, `signal`,
+ *   `observed`, `done`, `readOutput`, `kill`, `result`).
+ */
+export function agentExecutionHandle({ agent, cwd, argv, timeoutMs = 0, maxOutputBytes = 0, signal, onStarted }) {
+  // Our own controller is the kill channel; the caller's signal races it.
+  const controller = new AbortController();
+  let timedOut = false;
+  let killed = false;
+  let callerAborted = false;
+  if (signal) {
+    if (signal.aborted) callerAborted = true;
+    else signal.addEventListener("abort", () => { callerAborted = true; controller.abort(signal.reason); }, { once: true });
+  }
+  if (timeoutMs > 0) {
+    setTimeout(() => {
+      timedOut = true;
+      controller.abort(new Error("BASH_TIMEOUT"));
+    }, timeoutMs).unref?.();
+  }
+
+  const settle = agent.exec({ cwd, argv, timeoutMs, maxOutputBytes, signal: controller.signal }).then(
+    (result) => ({ ok: true, result }),
+    (error) => {
+      // A workdir the distro cannot enter is the command's own failure, not
+      // the agent's: synthesize the relay-shaped stderr the one-shot path
+      // produces, so the executor's `workdirFailure` check reports it the
+      // same way. An agent that is actually OUT propagates for fallback.
+      if (error instanceof CwdError) {
+        return {
+          ok: true,
+          result: {
+            exitCode: 1,
+            stdout: Buffer.alloc(0),
+            stderr: Buffer.from(`<3>WSL: CreateProcessCommon: chdir(${error.linuxPath}) failed: No such file or directory`, "utf8"),
+          },
+        };
+      }
+      return { ok: false, error };
+    },
+  );
+
+  /** @type {Buffer} */
+  let stdout = Buffer.alloc(0);
+  /** @type {Buffer} */
+  let stderr = Buffer.alloc(0);
+  /** The agent's per-stream capture-cap flags, surfaced as `truncated`. */
+  let stdoutTruncated = false;
+  let stderrTruncated = false;
+  let exitOutcome = { exitCode: null, signal: "SIGTERM" };
+
+  let settleError;
+  const done = settle.then(({ ok, result, error }) => {
+    if (ok) {
+      stdout = result.stdout;
+      stderr = result.stderr;
+      stdoutTruncated = result.truncated?.stdout === true;
+      stderrTruncated = result.truncated?.stderr === true;
+      // The distro timeout and kill() both mean "we stopped it"; a genuine
+      // exit keeps its code.
+      if (timedOut || killed || callerAborted) exitOutcome = { exitCode: null, signal: "SIGTERM" };
+      else exitOutcome = { exitCode: result.exitCode, signal: null };
+    } else if (timedOut || killed) {
+      // OUR kill (the in-distro timeout or kill()): the agent's rejection is
+      // the abort plumbing, not a failure — settle as the killed outcome the
+      // one-shot path reports for the same situation.
+      stdout = Buffer.alloc(0);
+      stderr = Buffer.alloc(0);
+    } else {
+      // The caller's cancellation rejections propagate (upstream keeps
+      // cancellation as a rejection), as does a genuinely out-of-service
+      // agent — that one is the executor's fallback cue.
+      settleError = error;
+    }
+    return exitOutcome;
+  });
+
+  const stdoutReader = () => memoryReader(stdout);
+  const stderrReader = () => memoryReader(stderr);
+
+  let stdoutOffset = 0;
+  let stderrOffset = 0;
+
+  /** @type {object} */
+  const proc = {
+    status: "running",
+    exitCode: null,
+    signal: null,
+    observed: {
+      get stdout() { return stdoutReader(); },
+      get stderr() { return stderrReader(); },
+    },
+    done: done.then(() => {
+      proc.status = exitOutcome.signal !== null || exitOutcome.exitCode === null ? "killed" : "completed";
+      proc.exitCode = exitOutcome.exitCode;
+      proc.signal = exitOutcome.signal;
+    }),
+    readOutput() {
+      const out = stdoutReader().readFrom(stdoutOffset);
+      const err = stderrReader().readFrom(stderrOffset);
+      stdoutOffset = out.nextOffset;
+      stderrOffset = err.nextOffset;
+      const separator = out.text.length > 0 && !out.text.endsWith("\n") ? "\n" : "";
+      return {
+        delta: out.text + (err.text.length > 0 ? `${separator}[stderr]\n${err.text}` : ""),
+        lossy: false,
+      };
+    },
+    kill() {
+      if (proc.status !== "running") return false;
+      // Upstream marks the handle killed SYNCHRONOUSLY, before the process is
+      // observed to die — the second kill() must already be a no-op.
+      proc.status = "killed";
+      killed = true;
+      controller.abort(new Error("killed"));
+      return true;
+    },
+    result() {
+      return done.then(() => {
+        // The spawn-equivalent failure (the agent being out) rejects here,
+        // exactly like upstream's `running.done` rejection carried by result().
+        if (settleError !== undefined) throw settleError;
+        // `truncated` is REQUIRED by the bash tool's canonical result — it
+        // copies the field unconditionally, and an `undefined` fails the wire's
+        // lossless-JSON snapshot ("value is not lossless JSON"). The agent's
+        // capture-cap flags are what make it TRUE instead of a perma-lie.
+        const output = (text, truncated) => ({ text, lossy: false, truncated });
+        return {
+          exitCode: proc.exitCode,
+          signal: proc.signal,
+          timedOut,
+          aborted: callerAborted && !timedOut,
+          timeoutMs,
+          stdout: output(stdout.toString("utf8"), stdoutTruncated),
+          stderr: output(stderr.toString("utf8"), stderrTruncated),
+        };
+      });
+    },
+  };
+  onStarted?.(proc);
+  return proc;
+}

package/lib/agent-protocol.js

@@ -0,0 +1,174 @@
+/**
+ * Wire protocol for the resident in-distro agent (`agent/wsl-agent.sh`).
+ *
+ * Pure by construction — no Node API, no I/O — so the frame codecs and the
+ * line parser are unit-testable without a distro. The protocol itself is line
+ * oriented with `|` field separators and single-line base64 payloads; see the
+ * agent script's header for the grammar. Base64 was chosen over JSON because
+ * the agent must run under a bare POSIX sh with nothing but coreutils.
+ *
+ * @module dsh-plugin-wsl/agent-protocol
+ */
+
+/** The protocol version this host side speaks; the agent must match. */
+export const PROTOCOL_VERSION = 3;
+
+/**
+ * Upper bound on one `read` op's payload, set by the HOST looping over windowed
+ * requests. Keeping each frame's decoded payload here means the agent's RES
+ * line stays modest even for a large file; the host accumulates chunks.
+ */
+export const FS_READ_CHUNK_BYTES = 1024 * 1024;
+
+/** The agent identifies itself with this name in its HELLO line. */
+export const AGENT_NAME = "wsl-agent";
+
+/**
+ * Rough ceiling on one protocol line, chosen well above the executor's own
+ * 64 KB output budget spill: stdout and stderr ride ONE line each, so a frame
+ * is as large as the largest capture the caller asked for. Documented so a
+ * future streaming design does not inherit it silently.
+ */
+export const MAX_FRAME_BYTES = 256 * 1024 * 1024;
+
+/**
+ * Encode a buffer as the protocol's single-line base64 (no line wraps, no
+ * padding surprises — standard base64 including `=` padding).
+ * @param {string|Uint8Array} value - the payload to encode.
+ * @returns {string} the wire form.
+ */
+export function encodeB64(value) {
+  return Buffer.from(value).toString("base64");
+}
+
+/**
+ * Decode one protocol base64 field.
+ * @param {string} value - the wire form.
+ * @returns {Buffer} the decoded bytes; a malformed field decodes to empty
+ *   rather than throwing, mirroring the agent's own lenient decode.
+ */
+export function decodeB64(value) {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value)) return Buffer.alloc(0);
+  return Buffer.from(value, "base64");
+}
+
+/**
+ * Build the request lines for one EXEC frame: a header line naming the cwd,
+ * the whole-request timeout in whole seconds (0 = none), the argv word count
+ * and the per-stream output capture budget in bytes (0 = unlimited), followed
+ * by one base64 line per argv word.
+ * @param {object} request - the execution request.
+ * @param {string} request.id - caller-chosen request id (unique per agent).
+ * @param {string} request.cwd - Linux path to cd into before exec.
+ * @param {string[]} request.argv - the argv to execute, already bwrap-wrapped.
+ * @param {number} [request.timeoutMs] - in-distro timeout; sub-second
+ *   remainders round up, and `<= 0` disables the timeout.
+ * @param {number} [request.maxOutputBytes] - per-stream capture ceiling the
+ *   AGENT enforces: stdout and stderr are each cut at this many bytes and the
+ *   RES line reports what was cut. 0 (the default) keeps the historical
+ *   unbounded capture.
+ * @returns {string[]} the lines to write to the agent's stdin, in order.
+ */
+export function encodeExecFrame({ id, cwd, argv, timeoutMs = 0, maxOutputBytes = 0 }) {
+  const timeoutSeconds = timeoutMs > 0 ? Math.ceil(timeoutMs / 1000) : 0;
+  const cap = maxOutputBytes > 0 ? Math.floor(maxOutputBytes) : 0;
+  const lines = [
+    `EXEC|${id}|${encodeB64(cwd)}|${timeoutSeconds}|${argv.length}|${cap}`,
+    ...argv.map((word) => encodeB64(word)),
+  ];
+  return lines;
+}
+
+/**
+ * Build a SETENV request line. Note the agent's decode strips trailing
+ * newlines from the value — the same leniency the shell itself applies.
+ * @param {string} key - the variable name.
+ * @param {string} value - the variable value.
+ * @returns {string} the line to write.
+ */
+export function encodeSetEnv(key, value) {
+  return `SETENV|${key}|${encodeB64(value)}`;
+}
+
+/** @param {string} id - the request id to interrupt. @returns {string} */
+export function encodeKill(id) {
+  return `KILL|${id}`;
+}
+
+/**
+ * Build the request lines for one FS frame — the filesystem-substrate request
+ * that lets the model's file tools run inside the distro. The shape mirrors
+ * EXEC: a header naming the op, the timeout in whole seconds and the argument
+ * count, followed by one base64 line per argument.
+ *
+ * Ops (see `agent/wsl-agent.sh` for the server side and the wire grammar):
+ * `stat`, `lstat`, `list`, `realpath`, `read`, `write`. Responses reuse the
+ * EXEC `ACK`/`RES`/`ERR` lines, so the request machinery (pending map, KILL,
+ * the watchdog) is shared unchanged.
+ *
+ * The argument contract: callers pass PLAINTEXT values here; this frame is the
+ * single base64 boundary, and the agent decodes each argument once. A write's
+ * content is no exception — the agent pipes its still-encoded wire line
+ * straight to `base64 -d`, so raw bytes never pass through a shell variable.
+ *
+ * @param {object} request - the filesystem request.
+ * @param {string} request.id - caller-chosen request id (unique per agent).
+ * @param {string} request.op - one of the op names above.
+ * @param {string[]} request.args - op arguments, base64-line encoded here.
+ * @param {number} [request.timeoutMs] - in-distro timeout; sub-second
+ *   remainders round up, and `<= 0` disables the timeout.
+ * @returns {string[]} the lines to write to the agent's stdin, in order.
+ */
+export function encodeFsFrame({ id, op, args, timeoutMs = 0 }) {
+  const timeoutSeconds = timeoutMs > 0 ? Math.ceil(timeoutMs / 1000) : 0;
+  return [
+    `FS|${id}|${op}|${timeoutSeconds}|${args.length}`,
+    ...args.map((word) => encodeB64(word)),
+  ];
+}
+
+/** The line parser's verdict for one line of agent stdout. */
+
+/**
+ * Parse one line of the agent's stdout.
+ * @param {string} line - a line without its terminator.
+ * @returns {object} one of:
+ *   - `{ type: "hello", name, version }`
+ *   - `{ type: "pong" }`
+ *   - `{ type: "ack", id }` — the agent dequeued the request for execution;
+ *     the host arms its stuck-request watchdog here, so queue time never
+ *     counts against a budget
+ *   - `{ type: "result", id, exitCode, stdout, stderr }` — outputs as Buffers
+ *   - `{ type: "agentError", id, reason, message }` — `id` is `""` when the
+ *     agent reports a request-less problem (a protocol violation)
+ *   - `{ type: "unknown", line }` — never thrown; the host decides whether an
+ *     unrecognized line is fatal. (Anything during the handshake is; after it,
+ *     garbage on stdout is logged and dropped, because a `RES` for a request
+ *     the host already gave up on is expected noise.)
+ */
+export function parseAgentLine(line) {
+  if (line.startsWith("HELLO|")) {
+    const [, name, version] = line.split("|");
+    return { type: "hello", name, version: Number(version) };
+  }
+  if (line === "PONG") return { type: "pong" };
+  if (line.startsWith("ACK|")) return { type: "ack", id: line.slice(4) };
+  if (line.startsWith("RES|")) {
+    const [, id, exitCode, stdout, stderr, outTruncated, errTruncated] = line.split("|");
+    return {
+      type: "result",
+      id,
+      exitCode: Number(exitCode),
+      stdout: decodeB64(stdout ?? ""),
+      stderr: decodeB64(stderr ?? ""),
+      // The capture-cap flags the agent appends when the EXEC frame carried a
+      // budget; frames without them (fakes, FS ops) are simply not truncated.
+      truncated: { stdout: outTruncated === "1", stderr: errTruncated === "1" },
+    };
+  }
+  if (line.startsWith("ERR|")) {
+    const [, id, reason, message] = line.split("|");
+    return { type: "agentError", id: id ?? "", reason: reason ?? "protocol", message: decodeB64(message ?? "").toString("utf8") };
+  }
+  return { type: "unknown", line };
+}

package/lib/agent-shared.js

@@ -0,0 +1,32 @@
+/**
+ * The per-distro resident agent shared by every provider in this process.
+ *
+ * Extracted from `lib/index.js` so modules the index does not import back
+ * (`shell-env`, future consumers) can use the same peer without a cycle: the
+ * shell executor's commands, the filesystem's in-distro side work and the
+ * port snapshot all queue on ONE agent per distro, and the per-distro startup
+ * cost is paid once per process.
+ *
+ * @module dsh-plugin-wsl/agent-shared
+ */
+
+import { fileURLToPath } from "node:url";
+import { toLinuxPath } from "./paths.js";
+import { WslAgent } from "./agent.js";
+
+const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.meta.url));
+const sharedAgents = new Map();
+
+/**
+ * The shared agent for one distro, created on first use.
+ * @param distro - the distro name.
+ * @returns {WslAgent} the shared agent.
+ */
+export function sharedAgent(distro) {
+  let agent = sharedAgents.get(distro);
+  if (agent === undefined) {
+    agent = new WslAgent({ distro, scriptPath: toLinuxPath(AGENT_SCRIPT_PATH) });
+    sharedAgents.set(distro, agent);
+  }
+  return agent;
+}