dsh-plugin-wsl-env 0.9.0 → 0.11.0

package/lib/agent-protocol.d.ts

@@ -14,7 +14,7 @@
  * @module dsh-plugin-wsl/agent-protocol
  */
 /** The protocol version this host side speaks; the agent must match. */
-export declare const PROTOCOL_VERSION = 4;
+export declare const PROTOCOL_VERSION = 5;
 /**
  * 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
@@ -127,15 +127,21 @@ export interface FsFrameRequest {
  */
 export declare function encodeFsFrame({ id, op, args, timeoutMs }: FsFrameRequest): string[];
 /**
- * `HELLO|name|version|digest` — `digest` is the sha256 of the script file the
- * agent is executing (empty when it could not hash it); the host compares it
- * against its own shipped copy.
+ * `HELLO|name|version|digest|pid` — `digest` is the sha256 of the script file
+ * the agent is executing (empty when it could not hash it); the host compares
+ * it against its own shipped copy. `pid` is the agent shell's PID inside the
+ * distro, present from protocol 5 on: the host uses it to deliver an
+ * out-of-band `USR1` cancellation while the agent is blocked in `wait`, which
+ * the serial stdin loop cannot do by frame. It is absent when the agent
+ * itself runs inside a PID namespace (the confined resident), where that PID
+ * is not addressable from a second `wsl.exe`.
  */
 export interface HelloMessage {
     type: "hello";
     name: string;
     version: number;
     digest: string;
+    pid?: number;
 }
 /** `PONG` — the liveness answer to `PING`. */
 export interface PongMessage {

package/lib/agent-protocol.js

@@ -14,7 +14,7 @@
  * @module dsh-plugin-wsl/agent-protocol
  */
 /** The protocol version this host side speaks; the agent must match. */
-export const PROTOCOL_VERSION = 4;
+export const PROTOCOL_VERSION = 5;
 /**
  * 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
@@ -124,8 +124,15 @@ export function encodeFsFrame({ id, op, args, timeoutMs = 0 }) {
  */
 export function parseAgentLine(line) {
     if (line.startsWith("HELLO|")) {
-        const [, name, version, digest] = line.split("|");
-        return { type: "hello", name: name ?? "", version: Number(version), digest: digest ?? "" };
+        const [, name, version, digest, pid] = line.split("|");
+        const agentPid = Number(pid);
+        return {
+            type: "hello",
+            name: name ?? "",
+            version: Number(version),
+            digest: digest ?? "",
+            ...(Number.isSafeInteger(agentPid) && agentPid > 0 ? { pid: agentPid } : {}),
+        };
     }
     if (line === "PONG")
         return { type: "pong" };

package/lib/agent-shared.js

@@ -14,10 +14,12 @@
  * @module dsh-plugin-wsl/agent-shared
  */
 import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { toLinuxPath } from "./paths.js";
-import { WslAgent } from "./agent.js";
+import { pinnedWindowsEnv, WslAgent } from "./agent.js";
+import { configuredAgentBackend, ensureNativeBackend, NATIVE_AGENT_ENV } from "./native-agent.js";
 const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.meta.url));
 // The script the distro reads must be byte-identical to the copy this
 // package shipped: the deployed layout reads it from the /mnt/c mirror, and
@@ -25,6 +27,9 @@ const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.
 // Both resident factories (plain and confined) pin it.
 const AGENT_SCRIPT_DIGEST = createHash("sha256").update(readFileSync(AGENT_SCRIPT_PATH)).digest("hex");
 const sharedAgents = new Map();
+// Distros where the native shared agent failed at runtime; the reads fail open
+// to the shell instead of retrying the same broken binary on every call.
+const nativeFailed = new Set();
 /** The agent script as a host-side path, for factories that need both spellings. */
 export const agentScriptPath = AGENT_SCRIPT_PATH;
 /** The sha256 of the shipped agent script; every resident verifies its HELLO against it. */
@@ -37,9 +42,32 @@ export const agentScriptDigest = AGENT_SCRIPT_DIGEST;
  */
 export function sharedAgent(distro) {
     let agent = sharedAgents.get(distro);
-    if (agent === undefined) {
-        agent = new WslAgent({ distro, scriptPath: toLinuxPath(AGENT_SCRIPT_PATH), expectedDigest: AGENT_SCRIPT_DIGEST });
-        sharedAgents.set(distro, agent);
-    }
+    if (agent !== undefined && !agent.unavailable)
+        return agent;
+    if (agent !== undefined)
+        nativeFailed.add(distro);
+    agent = new WslAgent({
+        distro,
+        scriptPath: toLinuxPath(AGENT_SCRIPT_PATH),
+        expectedDigest: AGENT_SCRIPT_DIGEST,
+        prepare: async () => {
+            if (configuredAgentBackend() === "shell" || nativeFailed.has(distro))
+                return undefined;
+            const prepared = await ensureNativeBackend({ wslPath: "wsl.exe", distro, source: process.env[NATIVE_AGENT_ENV] ?? "" });
+            if (prepared === undefined)
+                return undefined;
+            return {
+                scriptPath: prepared.path,
+                expectedDigest: prepared.digest,
+                signalable: false,
+                spawnTransport: ({ wslPath, distro: target, argvPrefix }) => spawn(wslPath, ["-d", target, "--exec", ...argvPrefix, prepared.path], {
+                    stdio: ["pipe", "pipe", "pipe"],
+                    windowsHide: true,
+                    env: pinnedWindowsEnv(process.env),
+                }),
+            };
+        },
+    });
+    sharedAgents.set(distro, agent);
     return agent;
 }

package/lib/agent.d.ts

@@ -59,6 +59,14 @@ export interface ExecResult {
 export interface PendingRequest {
     /** The request id, as the agent echoes it. */
     id: string;
+    /** Which metric bucket this request belongs to. */
+    kind: "fs" | "exec";
+    /** When the frame was written, for the queue measurement. */
+    sentAt: number;
+    /** When the agent ACKed it, for the execution measurement. */
+    ackedAt?: number;
+    /** Whether the metrics recorded this request's settle. */
+    measured: boolean;
     /** The frame lines (kept so a rebuild can re-send). */
     lines: string[];
     /** Settles a RES. */
@@ -73,6 +81,57 @@ export interface PendingRequest {
     onAbort: (() => void) | null;
     /** Arms `watchdog`; null when the request carries no timeout. */
     armWatchdog: (() => void) | null;
+    /** Whether the agent has ACKed this request (it is the running one). */
+    started: boolean;
+    /** The caller cancelled it; the entry stays until the agent answers. */
+    cancelled: boolean;
+    /** The caller was already settled; a late answer only cleans up. */
+    settled: boolean;
+}
+/** Per-kind request metrics. */
+export interface RequestMetrics {
+    /** Requests that settled (successful, failed or cancelled). */
+    requests: number;
+    /** Total queue wait (sent -> ACK), ms. */
+    queueMs: number;
+    /** Largest single queue wait, ms. */
+    queueMaxMs: number;
+    /** Total execution time (ACK -> settle), ms. */
+    execMs: number;
+    /** Largest single execution time, ms. */
+    execMaxMs: number;
+    /** Settled with an error (not cancellation). */
+    failed: number;
+    /** Cancelled by the caller. */
+    cancelled: number;
+    /** Rejected before tracking: queue full, already aborted, or send failed. */
+    rejected: number;
+}
+/** The agent's cumulative request metrics. */
+export interface AgentMetrics {
+    /** FS frames. */
+    fs: RequestMetrics;
+    /** EXEC frames (commands, ping). */
+    exec: RequestMetrics;
+    /** Peak number of pending requests. */
+    inFlightMax: number;
+}
+/** The entry an async preparation may select before the first spawn. */
+export interface WslAgentPrepared {
+    /** The agent entrypoint (the shell script or the native cache path). */
+    scriptPath: string;
+    /** The HELLO digest to verify. */
+    expectedDigest?: string;
+    /** Whether USR1 can reach the agent (false for the native KILL-frame path). */
+    signalable?: boolean;
+    /** The process factory for this entry. */
+    spawnTransport?: (options: {
+        wslPath: string;
+        distro: string;
+        scriptPath: string;
+        argvPrefix: string[];
+        leaseMs: number;
+    }) => ChildProcess;
 }
 /**
  * The Windows environment the transport starts from, pinned.
@@ -134,13 +193,36 @@ export declare class WslAgent {
         distro: string;
         scriptPath: string;
         argvPrefix: string[];
+        leaseMs: number;
     }) => ChildProcess) | undefined;
+    /** The explicit lease, when the caller supplied one (independent of idleMs). */
+    configuredLease: number | undefined;
+    /** The injectable signal sender, when the caller supplied one. */
+    configuredSignal: ((options: {
+        wslPath: string;
+        distro: string;
+        pid: number;
+        signal: NodeJS.Signals;
+    }) => void) | undefined;
+    /** The agent shell's PID from its HELLO, when a second wsl.exe can address it. */
+    agentPid: number | undefined;
+    /**
+     * Whether a second `wsl.exe` can deliver `USR1` to the agent's HELLO pid.
+     * True for the plain agent; false for a resident inside a PID namespace. A
+     * session runtime has a prefix (scope + mounts) but no PID namespace, so it
+     * opts in explicitly.
+     */
+    signalable: boolean;
+    /** The maximum requests allowed in flight on this resident. */
+    maxPending: number;
     /** The live resident process, when any. */
     process: ChildProcess | null;
     /** The lifecycle state. */
     state: "idle" | "starting" | "ready" | "dead";
     /** The in-flight start, shared by concurrent callers. */
     startPromise: Promise<void> | null;
+    /** The in-flight start's settler, so close() can fail a start it interrupts. */
+    startSettler: ((error?: unknown) => void) | null;
     /** The next request id. */
     nextRequestId: number;
     /** The requests in flight, keyed by their current id. */
@@ -151,6 +233,10 @@ export declare class WslAgent {
     idleTimer: NodeJS.Timeout | null;
     /** The last failure, for `unavailableReason` and log messages. */
     lastError: string;
+    /** Cumulative request metrics; see {@link metrics}. */
+    requestMetrics: AgentMetrics;
+    /** The optional async preparation hook. */
+    prepare: (() => Promise<WslAgentPrepared | undefined>) | undefined;
     /**
      * @param config - the agent configuration.
      */
@@ -166,6 +252,13 @@ export declare class WslAgent {
         wslPath?: string;
         /** Idle shutdown delay; 0 disables. */
         idleMs?: number;
+        /**
+         * The client lease in ms, independent of `idleMs`. A session runtime holds
+         * the agent for the session's lifetime (no idle close) but still wants the
+         * lease's last-resort self-termination; a positive value here overrides the
+         * idle-derived lease.
+         */
+        leaseMs?: number;
         /**
          * The sha256 of the agent script as this package shipped it; a HELLO whose
          * digest differs is refused the same way a version mismatch is (the script
@@ -180,6 +273,13 @@ export declare class WslAgent {
          * Empty for the plain agent.
          */
         argvPrefix?: string[];
+        /**
+         * Whether a second `wsl.exe` can signal the agent's pid. Defaults to
+         * "true when the argv prefix is empty": the plain agent shares the distro's
+         * PID namespace, a confined resident does not, and a session runtime has a
+         * prefix but no PID namespace and must opt in.
+         */
+        signalable?: boolean;
         /** Hard ceiling in bytes on one stdout protocol line; defaults to {@link MAX_FRAME_BYTES}. */
         frameCapBytes?: number;
         /** Injectable process factory for tests. */
@@ -188,7 +288,25 @@ export declare class WslAgent {
             distro: string;
             scriptPath: string;
             argvPrefix: string[];
+            leaseMs: number;
         }) => ChildProcess;
+        /**
+         * Injectable out-of-band signal delivery for tests. The real path spawns a
+         * second `wsl.exe` to send USR1 to the agent's PID.
+         */
+        signalTransport?: (options: {
+            wslPath: string;
+            distro: string;
+            pid: number;
+            signal: NodeJS.Signals;
+        }) => void;
+        /**
+         * Maximum requests in flight on one resident; a submission past it is
+         * refused instead of growing the request map without bound.
+         */
+        maxPending?: number;
+        /** Optional async preparation selecting the entry before the first spawn. */
+        prepare?: () => Promise<WslAgentPrepared | undefined>;
     });
     /**
      * Whether the agent is permanently out — the executor's fallback cue.
@@ -205,6 +323,18 @@ export declare class WslAgent {
      * @returns resolved once the state is `ready`.
      */
     start(): Promise<void>;
+    /**
+     * Apply an async preparation entry to this agent before the first spawn.
+     *
+     * @param entry - the selected entry.
+     */
+    private applyPrepared;
+    /**
+     * Spawn the process and run the handshake.
+     *
+     * @returns resolved once the state is `ready`.
+     */
+    private beginStart;
     /**
      * One stdout line from the agent. The first must be a matching HELLO.
      *
@@ -217,6 +347,7 @@ export declare class WslAgent {
      * The process died. Requests in flight ride exactly one rebuild; a second
      * death is permanent.
      *
+     * @param child - the process that exited.
      * @param code - the exit code, null when killed by a signal.
      * @param signalName - the killing signal, null on a normal exit.
      */
@@ -310,6 +441,53 @@ export declare class WslAgent {
      * @returns resolved on PONG.
      */
     ping(signal?: AbortSignal): Promise<void>;
+    /**
+     * Deliver an out-of-band signal to the resident shell. The serial stdin loop
+     * cannot consume a frame while a command runs, so cancellation is a signal;
+     * a second `wsl.exe` is the only channel that reaches the agent while it is
+     * blocked in `wait`.
+     *
+     * Only an agent that shares the distro's PID namespace is addressable: the
+     * plain agent, or a session runtime (its prefix is a scope plus mounts, but
+     * no PID namespace). A confined resident runs inside a PID namespace whose
+     * PIDs do not exist in the distro, so signalling its HELLO PID could hit an
+     * unrelated process; there the KILL frame remains the (delayed) fallback.
+     *
+     * @param signal - the signal to deliver (`SIGUSR1` is the cancel trap).
+     */
+    /**
+     * The cumulative request metrics: queue wait (sent -> ACK) and execution
+     * time (ACK -> settle) per request kind, plus the peak in-flight count.
+     *
+     * @returns a snapshot the caller can keep.
+     */
+    metrics(): AgentMetrics;
+    /** Reset the cumulative metrics (diagnostics/probes). */
+    resetMetrics(): void;
+    /**
+     * The metric bucket for a request kind.
+     * @param kind - fs or exec.
+     * @returns the bucket.
+     */
+    private kindMetrics;
+    /**
+     * Record a request that never entered the pending map.
+     * @param kind - the bucket.
+     */
+    private noteRejected;
+    /**
+     * Record the dequeue ACK: the request's queue wait.
+     * @param pending - the request.
+     */
+    private recordAck;
+    /**
+     * Record a settle: the requests count, the execution time (or the queue wait
+     * for a request that never ACKed), and the outcome.
+     * @param pending - the request.
+     * @param error - the failure, when any.
+     */
+    private recordSettle;
+    private signalAgent;
     /**
      * Shut the agent down: SHUTDOWN first, then kill after a short grace. The
      * agent becomes reusable — a later `exec` starts a fresh process.
@@ -317,6 +495,15 @@ export declare class WslAgent {
      * @returns resolved once the process is gone.
      */
     close(): Promise<void>;
+    /**
+     * Release the host's ends of a dead child's stdio. A descendant that
+     * inherited a pipe's write end would otherwise keep the read side — and the
+     * fd — open until that descendant exits; the agent's own helpers are
+     * redirected at their spawn sites, but the host must not depend on it.
+     *
+     * @param child - the process whose streams are being released.
+     */
+    private teardownStreams;
     /**
      * Write one frame to the live process.
      *