dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/docs/UPSTREAM-TERMINAL-TITLE.md

@@ -2,17 +2,24 @@
 
 Status: proposed upstream as
 [deepseek-ai/deepseek-harness#8769](https://github.com/deepseek-ai/deepseek-harness/discussions/8769)
-(targeting `packages/api/terminal-controller`, version line `0.2.0-rc.x`). This
-is the record of a gap this plugin worked around, could not work around, and
-now documents: the GUI terminal titles every tab from the composition's single
-shell profile, so a per-session shell choice is invisible in the title.
+(targeting `packages/api/terminal-controller`, version line `0.2.0-rc.x`). The
+plugin worked around the execution half of this gap — a Windows-folder
+session's terminal runs a host shell (`subprocess-wsl.hostSessions`) — and
+could not work around the title half. This is the record: the GUI titles every
+tab from the composition's single shell profile, so a per-session shell choice
+is invisible in the title.
 
 ## The gap
 
-`TerminalController.spawn` fixes a terminal's display title from the resolved
-shell profile before the provider is ever consulted:
+The display title is fixed from the resolved shell profile and never revisited.
+The private `TerminalController.spawn` builds `info`, with `title: shell.name`,
+only after `await subprocess.spawnTerminal(...)` has returned, and it does not
+read back what that call started:
 
 ```ts
+const handle = await subprocess.spawnTerminal({
+  argv: [shell.path, ...shell.args], cwd: environment.cwd, cols: request.cols, ...
+})
 const info: WebTerminalInfo = {
   id: request.id, shell, title: shell.name, cwd: environment.cwd, ...
 }
@@ -48,10 +55,15 @@ Three escape hatches were evaluated against `0.2.0-rc.2` and each is closed:
    inserts `terminal-controller`, and the client model that the
    `dsh-client-ui-sidebar-terminal` entry waits for mounts with
    `inject = ['remote', 'remote.terminal']` — the `terminal` namespace the host
-   controller registers in its constructor. Disabling the row fails web boot:
-   `1 entry did not activate: @deepseek-ai/dsh-client-ui-sidebar-terminal:
-   pending (waiting for service: webTerminals)`. Verified live against
-   `dsh-desktop 0.2.0-rc.2`.
+   controller registers in its constructor. Disabling the row fails web boot
+   with this two-line error:
+
+   ```text
+   web boot: 1 entry did not activate
+   @deepseek-ai/dsh-client-ui-sidebar-terminal: pending (waiting for service: webTerminals)
+   ```
+
+   Verified live against `dsh-desktop 0.2.0-rc.2` (Electron 44.0.0).
 3. **Per-session config.** The `shell` profile is composition state; `!!js`
    expressions evaluate once at config resolution and reach no Session
    identity.
@@ -62,7 +74,7 @@ Any one of these closes the gap; the first is the smallest and keeps the
 profile name as the fallback:
 
 - `SubprocessTerminalSpawnSpec` gains an optional `displayTitle` (or the handle
-  exposes the launched `argv`), and `create()` uses it for `info.title` when
+  exposes the launched `argv`), and `spawn()` uses it for `info.title` when
   present — falling back to `shell.name`. A provider that rewrites a launch
   states the program it started; every other launch keeps the profile name.
 - Alternatively, the controller derives the title from the effective program
@@ -71,11 +83,34 @@ profile name as the fallback:
 
 With either, this plugin deletes the limitation paragraph in
 [LIMITATIONS.md](LIMITATIONS.md) and the `WSL`-over-PowerShell title, for any
-provider that rewrites launches — not just WSL.
+provider that rewrites launches — not just WSL. The same limitation is stated
+as current fact in four places. Three go stale the day the proposal lands; the
+fourth is already out of step and needs the corrections above whenever it is
+next touched:
+
+- the GUI-terminal comment block in [`cordis.patch.yml`](../cordis.patch.yml);
+- the closing paragraph of "Why the terminal provider is app-level" in
+  [ARCHITECTURE.md](ARCHITECTURE.md);
+- R4's `残差` (residual) column in [REQUIREMENTS.zh.md](REQUIREMENTS.zh.md);
+- the `WSL` tab-title bullet under "Terminals" in
+  [LIMITATIONS.md](LIMITATIONS.md) — the paragraph named just above. It says
+  the controller titles a tab *before* the provider rewrites the launch, the
+  reverse of the ordering corrected at the top of this file, and it carries the
+  one-line `shellCandidates` workaround that drops the row's `shell` block.
 
 ## Workarounds until then
 
 - Double-click a tab's title to rename it (a shipped client feature; the
   controller's `rename` Remote API accepts 1–120 characters).
-- Add `shellCandidates` to the `terminal-controller` row in a user layer: a
-  manually selected shell is titled after itself.
+- Re-declare the `terminal-controller` row in a user layer with a non-empty
+  `shellCandidates`: a manually selected shell is titled after itself. A patch
+  config replaces the whole config rather than deep-merging it
+  (`packages/boot/app-boot/src/config-schema/document.ts`), so the override has
+  to carry this plugin's `shell` block verbatim — `path: wsl.exe`, `name: WSL`,
+  `args: []` — or the terminal stops being a distro terminal. Expect the menu
+  to grow the host shells discovery finds on the root provider, which receives
+  no directory: executables this terminal never starts (the second bullet of
+  the GUI-terminal comment in [`cordis.patch.yml`](../cordis.patch.yml)).
+  [LIMITATIONS.md](LIMITATIONS.md) still carries the older one-line form of
+  this tip, which drops the `shell` block; the version above is the one that
+  works.

package/lib/agent-confined.d.ts

@@ -0,0 +1,42 @@
+import { WslAgent } from "./agent.js";
+/** One confinement request. */
+export interface ConfinedAgentRequest {
+    /** The distro to run in. */
+    distro: string;
+    /** The `wsl.exe` path. */
+    wslPath?: string;
+    /**
+     * The RESOLVED file-effect policy: the profile binds exactly what the mode
+     * grants.
+     */
+    policy: {
+        mode: string;
+        workspaceRoot: string;
+    };
+    /**
+     * Shadow `/mnt` with an empty tmpfs in the resident's profile; part of the
+     * cache key, since it changes the mount table the resident lives under.
+     */
+    maskWindowsDrive?: boolean;
+    /**
+     * Default TRUE: workspace-write binds the distro's real `/tmp` read-write
+     * into the resident's profile, so a write the fence approved lands where
+     * every reader reads. `false` restores the ephemeral tmpfs — for tests and
+     * probes, not production: a `/tmp` write behind an ephemeral mount reports
+     * success into a directory no reader can see, which is the bug this default
+     * exists to prevent.
+     */
+    realTmp?: boolean;
+}
+/**
+ * The confined agent for one distro and one resolved policy, created on first
+ * use and shared for the process lifetime. A success is remembered; a failed
+ * start is not (the agent's own rebuild rules take over from there).
+ *
+ * @param request - the confinement request.
+ * @returns the confined resident for this key.
+ */
+export declare function confinedAgent({ distro, wslPath, policy, maskWindowsDrive, realTmp }: ConfinedAgentRequest): WslAgent;
+/** Test hook: forget every confined resident (the plain agent has no factory state). */
+export declare function resetConfinedAgents(): void;
+export default confinedAgent;

package/lib/agent-confined.js

@@ -25,63 +25,47 @@
  * a third copy, so nothing compared production's command with a working one and
  * every confined mutation failed the resident's handshake.
  *
+ * This is a TypeScript source built to `lib/agent-confined.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/agent-confined
  */
 import { bwrapArgvPrefix } from "./bwrap.js";
 import { toLinuxPath } from "./paths.js";
 import { agentScriptDigest, agentScriptPath } from "./agent-shared.js";
 import { WslAgent } from "./agent.js";
-
 const confinedAgents = new Map();
-
 /**
  * The confined agent for one distro and one resolved policy, created on first
  * use and shared for the process lifetime. A success is remembered; a failed
  * start is not (the agent's own rebuild rules take over from there).
  *
- * @param {object} request - the confinement request.
- * @param {string} request.distro - the distro to run in.
- * @param {string} [request.wslPath] - the `wsl.exe` path.
- * @param {{mode: string, workspaceRoot: string}} request.policy - the RESOLVED
- *   file-effect policy: the profile binds exactly what the mode grants.
- * @param {boolean} [request.maskWindowsDrive] - shadow `/mnt` with an empty
- *   tmpfs in the resident's profile; part of the cache key, since it changes
- *   the mount table the resident lives under.
- * @param {boolean} [request.realTmp] - default TRUE: workspace-write binds the
- *   distro's real `/tmp` read-write into the resident's profile, so a write
- *   the fence approved lands where every reader reads. `false` restores the
- *   ephemeral tmpfs — for tests and probes, not production: a `/tmp` write
- *   behind an ephemeral mount reports success into a directory no reader can
- *   see, which is the bug this default exists to prevent.
- * @returns {WslAgent} the confined resident for this key.
+ * @param request - the confinement request.
+ * @returns the confined resident for this key.
  */
 export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindowsDrive = false, realTmp = true }) {
-  const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}\0${realTmp ? "real" : "ephemeral"}`;
-  let agent = confinedAgents.get(key);
-  if (agent === undefined) {
-    agent = new WslAgent({
-      distro,
-      wslPath,
-      scriptPath: toLinuxPath(agentScriptPath),
-      expectedDigest: agentScriptDigest,
-      // The prefix is a whole command from the distro's point of view — program,
-      // profile, `--` — because the transport inserts it between
-      // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s
-      // `spawnDefault`). Both confinement sites share that assembly in
-      // `lib/bwrap.js`, whose module doc records what happened when they did not.
-      argvPrefix: bwrapArgvPrefix(
-        { mode: policy.mode, workspaceRoot: toLinuxPath(policy.workspaceRoot, { distro }) },
-        { maskWindowsDrive, realTmp },
-      ),
-    });
-    confinedAgents.set(key, agent);
-  }
-  return agent;
+    const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}\0${realTmp ? "real" : "ephemeral"}`;
+    let agent = confinedAgents.get(key);
+    if (agent === undefined) {
+        agent = new WslAgent({
+            distro,
+            wslPath,
+            scriptPath: toLinuxPath(agentScriptPath),
+            expectedDigest: agentScriptDigest,
+            // The prefix is a whole command from the distro's point of view — program,
+            // profile, `--` — because the transport inserts it between
+            // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s
+            // `spawnDefault`). Both confinement sites share that assembly in
+            // `lib/bwrap.js`, whose module doc records what happened when they did not.
+            argvPrefix: bwrapArgvPrefix({ mode: policy.mode, workspaceRoot: toLinuxPath(policy.workspaceRoot, { distro }) }, { maskWindowsDrive, realTmp }),
+        });
+        confinedAgents.set(key, agent);
+    }
+    return agent;
 }
-
 /** Test hook: forget every confined resident (the plain agent has no factory state). */
 export function resetConfinedAgents() {
-  confinedAgents.clear();
+    confinedAgents.clear();
 }
-
 export default confinedAgent;

package/lib/agent-errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The error a {@link WslAgent} rejects with when the resident process is out
+ * for this host process — the executor's cue to fall back to the one-shot
+ * `wsl.exe` path. Deliberately its own class: callers must not confuse
+ * "the agent cannot serve" with a failure of the command itself.
+ *
+ * This is a TypeScript source built to `lib/agent-errors.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/agent-errors
+ */
+export declare class AgentUnavailableError extends Error {
+    /**
+     * @param message - why the agent is out, for the log.
+     */
+    constructor(message: string);
+}
+/**
+ * The request's workdir could not be entered inside the distro. Carries the
+ * Linux path so a caller can synthesize the same diagnostic the one-shot
+ * `wsl.exe` path produces from the relay's `chdir(...) failed` text.
+ */
+export declare class CwdError extends Error {
+    /** The path that could not be entered, in the distro's own spelling. */
+    linuxPath: string;
+    /**
+     * @param linuxPath - the path that could not be entered.
+     */
+    constructor(linuxPath: string);
+}

package/lib/agent-errors.js

@@ -4,30 +4,33 @@
  * `wsl.exe` path. Deliberately its own class: callers must not confuse
  * "the agent cannot serve" with a failure of the command itself.
  *
+ * This is a TypeScript source built to `lib/agent-errors.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/agent-errors
  */
 export class AgentUnavailableError extends Error {
-  /**
-   * @param {string} message - why the agent is out, for the log.
-   */
-  constructor(message) {
-    super(message);
-    this.name = "AgentUnavailableError";
-  }
+    /**
+     * @param message - why the agent is out, for the log.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "AgentUnavailableError";
+    }
 }
-
 /**
  * The request's workdir could not be entered inside the distro. Carries the
  * Linux path so a caller can synthesize the same diagnostic the one-shot
  * `wsl.exe` path produces from the relay's `chdir(...) failed` text.
  */
 export class CwdError extends Error {
-  /**
-   * @param {string} linuxPath - the path that could not be entered.
-   */
-  constructor(linuxPath) {
-    super(`could not enter working directory "${linuxPath}"`);
-    this.name = "CwdError";
-    this.linuxPath = linuxPath;
-  }
+    /**
+     * @param linuxPath - the path that could not be entered.
+     */
+    constructor(linuxPath) {
+        super(`could not enter working directory "${linuxPath}"`);
+        this.name = "CwdError";
+        this.linuxPath = linuxPath;
+    }
 }

package/lib/agent-exec.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 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.
+ *
+ * This is a TypeScript source built to `lib/agent-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/agent-exec
+ */
+/** The request one agent `exec` carries. */
+export interface AgentExecRequest {
+    /** Linux workdir. */
+    cwd: string;
+    /** The distro-side argv. */
+    argv: string[];
+    /** Whole-command budget. */
+    timeoutMs?: number;
+    /** Extra environment for this request only. */
+    env?: Record<string, string>;
+    /** Per-stream capture ceiling. */
+    maxOutputBytes?: number;
+    /** The caller's cancellation. */
+    signal?: AbortSignal;
+}
+/** What an agent `exec` resolves with. */
+export interface AgentExecResult {
+    /** The command's exit code. */
+    exitCode: number;
+    /** The captured stdout. */
+    stdout: Buffer;
+    /** The captured stderr. */
+    stderr: Buffer;
+    /** The agent's per-stream capture-cap flags. */
+    truncated?: {
+        stdout: boolean;
+        stderr: boolean;
+    };
+}
+/** The {@link WslAgent}-like runner this module drives. */
+export interface AgentExecRunner {
+    /** Run one command. */
+    exec: (request: AgentExecRequest) => Promise<AgentExecResult>;
+}
+/** How the exec promise settled: the result, or the failure to propagate. */
+export type SettledExec = {
+    ok: true;
+    result: AgentExecResult;
+    error?: undefined;
+} | {
+    ok: false;
+    result?: undefined;
+    error: unknown;
+};
+/** The memory-reader slice of one output stream. */
+export interface OutputReader {
+    /** Read the stream from a byte offset. */
+    readFrom: (fromByte: number) => {
+        text: string;
+        lossy: boolean;
+        nextOffset: number;
+    };
+}
+/** One settled foreground command, the shape `dsh-tool-bash` consumes. */
+export interface AgentExecutionHandle {
+    /** The lifecycle state. */
+    status: "running" | "completed" | "killed";
+    /** The exit code; null until settled or when killed. */
+    exitCode: number | null;
+    /** The terminating signal; null on a clean exit. */
+    signal: string | null;
+    /** The live output readers. */
+    observed: {
+        stdout: OutputReader;
+        stderr: OutputReader;
+    };
+    /** Settles when the command settles. */
+    done: Promise<void>;
+    /** The incremental delta reader. */
+    readOutput: () => {
+        delta: string;
+        lossy: boolean;
+    };
+    /** Stop the command; true on the first call only. */
+    kill: () => boolean;
+    /** The canonical bash result. */
+    result: () => Promise<{
+        exitCode: number | null;
+        signal: string | null;
+        timedOut: boolean;
+        aborted: boolean;
+        timeoutMs: number;
+        stdout: {
+            text: string;
+            lossy: boolean;
+            truncated: boolean;
+        };
+        stderr: {
+            text: string;
+            lossy: boolean;
+            truncated: boolean;
+        };
+    }>;
+}
+/**
+ * Run one command through the agent and present it as an execution handle.
+ *
+ * @param request - the execution request.
+ * @returns the execution handle (`status`, `exitCode`, `signal`, `observed`,
+ *   `done`, `readOutput`, `kill`, `result`).
+ */
+export declare function agentExecutionHandle({ agent, cwd, argv, timeoutMs, maxOutputBytes, signal, onStarted }: {
+    /**
+     * The {@link WslAgent}-like runner: `exec` accepting
+     * `{cwd, argv, timeoutMs, signal}` and resolving `{exitCode, stdout, stderr}`;
+     * throws `AgentUnavailableError` when out.
+     */
+    agent: AgentExecRunner;
+    /** Linux workdir. */
+    cwd: string;
+    /** The distro-side argv, bwrap-wrapped when confined. */
+    argv: string[];
+    /**
+     * Whole-command budget; the agent TERMs at the ceiling second and KILLs
+     * after its grace.
+     */
+    timeoutMs?: number;
+    /**
+     * Per-stream capture ceiling the agent enforces; the handle reports a cut
+     * stream as `truncated: true`.
+     */
+    maxOutputBytes?: number;
+    /** The caller's cancellation. */
+    signal?: AbortSignal;
+    /**
+     * Provider-facts hook, called synchronously before the handle can settle.
+     */
+    onStarted?: (proc: object) => void;
+}): AgentExecutionHandle;