dsh-bash-terminal-ts 0.4.0 → 0.6.0

package/lib/index.js

@@ -1,4 +1,4 @@
-// dsh-bash-terminal-ts - one shell tool, four Windows terminals.
+// dsh-bash-terminal - one shell tool, four Windows terminals.
 //
 // Registers a model-facing shell tool. The terminal backend (powershell /
 // gitbash / msys2 / wsl) is chosen by the USER in the Web UI settings (default
@@ -6,11 +6,7 @@
 // choice:
 //   - powershell: pwsh -NoLogo -NoProfile -NonInteractive -Command <cmd>
 //   - gitbash:    Git for Windows bash -lc <cmd>  (POSIX; /d/... paths)
-//   - msys2:      C:\msys64\usr\bin\bash.exe -lc <cmd>  (POSIX; full GCC/mingw64
-//                 toolchain). NOT msys2.exe: that Cygwin launcher allocates a
-//                 console and returns exit 0 with zero bytes under piped stdio.
-//                 MSYSTEM=MINGW64 is injected via buildEnv so /etc/profile picks
-//                 the MINGW64 environment and /mingw64/bin lands on PATH.
+//   - msys2:      MSYS2 bash -lc <cmd>  (POSIX; /c/... paths, full GCC/mingw64 toolchain)
 //   - wsl:        wsl [-d <distro>] -e bash -lc <cmd>  (Linux; /mnt/d/... paths)
 //
 // The tool spawns through the shared ctx.subprocess seam (process-tree
@@ -18,8 +14,13 @@
 // handles with the generic ctx.jobs registry, mirroring the shipped
 // dsh-tool-bash / dsh-tool-pwsh story call-for-call. It deliberately
 // does NOT consume the ctx.shell capability seam: the platform's own
-// sandboxed PowerShell executor keeps serving the pwsh tool, and this tool
-// is an additional, user-selected terminal that runs outside the sandbox.
+// sandboxed PowerShell executor keeps serving the pwsh tool. This tool is
+// an additional, user-selected terminal that still honors the DSH sandbox:
+// confined modes wrap PowerShell's spawn argv through ctx.sandbox
+// (fail-closed), while danger-full-access, Git Bash, MSYS2, and WSL run
+// unconfined. Git Bash and MSYS2 are unconfined because the DSH Windows ACL
+// restricted-token runner cannot host Cygwin/MSYS2: bash aborts with
+// "CreateFileMapping ... Win32 error 5" during startup.
 import { lstatSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { ESCALATION_TARGETS, TOOL_ABORTED, approveEscalation, defineTool, escalationHintMarker, clampTimeout, deadline, parseExitStatus, timeoutOf, sandboxDenialMarker, validateEscalationArgs, z, HarnessError } from "./dsh.js";
@@ -32,8 +33,6 @@ export const inject = ["tools", "systemPrompt", "shellEnv", "subprocess", "setti
 export const SHELLS = ["powershell", "gitbash", "msys2", "wsl"];
 /** The backend used when the caller does not name one. */
 export const DEFAULT_SHELL = "powershell";
-/** Settings namespace backing the user-chosen default terminal. */
-export const SETTINGS_NAMESPACE = "bash-terminal";
 /** Default per-command timeout (ms). */
 const DEFAULT_TIMEOUT_MS = 120000;
 /** Upper bound a caller's timeoutMs is capped to. */
@@ -55,7 +54,7 @@ const ENV_OVERRIDES = {
 };
 /** Runtime configuration schema. */
 export const Config = z.object({
-    defaultShell: z.string().default(DEFAULT_SHELL),
+    defaultShell: z.string().default(DEFAULT_SHELL).volatile(),
     timeoutMs: z.number().default(DEFAULT_TIMEOUT_MS),
     maxTimeoutMs: z.number().default(MAX_TIMEOUT_MS),
     pwshPath: z.string().default(""),
@@ -120,34 +119,30 @@ export function candidateGitBashPaths(env = process.env) {
     return candidates;
 }
 /**
- * MSYS2 locations, in preference order: the real `bash.exe` under usr\bin first,
- * then bin\bash.exe, and `msys2.exe` dead last.
+ * MSYS2 locations, in preference order: the real `bash.exe` under usr\bin
+ * first, then bin\bash.exe, and `msys2.exe` dead last.
  *
  * msys2.exe is NOT a usable backend for piped execution: it is the console-
  * allocating Cygwin launcher, so a spawn with piped stdio returns exit 0 with
- * zero bytes on both stdout and stderr (measured on MSYS2 with bash 5.3.15).
- * Keeping it in the list only as a last-resort fallback preserves the path the
- * config docs reference, but a working bash.exe always wins.
+ * zero bytes on both stdout and stderr (measured on this machine against
+ * MSYS2 with bash 5.3.15). Keeping it in the list only as a last-resort
+ * fallback preserves the path the config docs reference, but a working
+ * bash.exe always wins.
  *
- * MSYS2 uses the same Cygwin/MSYS2 runtime as Git Bash, so it cannot run under
- * the DSH Windows ACL restricted-token sandbox.
+ * MSYS2 uses the same Cygwin/MSYS2 runtime as Git Bash, so it cannot run
+ * under the DSH Windows ACL restricted-token sandbox.
  */
 export function candidateMsys2Paths(env = process.env) {
-    const programFiles = env.ProgramFiles ?? "C:\\Program Files";
     const candidates = [
         "C:\\msys64\\usr\\bin\\bash.exe",
         "C:\\msys64\\bin\\bash.exe"
     ];
-    // Also check 32-bit variant
-    const programFilesX86 = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
-    if (programFilesX86 !== programFiles) {
-        candidates.push("C:\\msys64\\usr\\bin\\bash.exe"); // same path regardless of arch
-    }
     for (const entry of (env.PATH ?? "").split(";")) {
         const trimmed = entry.trim().replace(/^"|"$/g, "");
         if (trimmed.length === 0)
             continue;
-        if (trimmed.toLowerCase().includes("msys64") || trimmed.toLowerCase().includes("mingw64")) {
+        const lower = trimmed.toLowerCase();
+        if (lower.includes("msys64") || lower.includes("mingw64")) {
             candidates.push(join(trimmed, "bash.exe"));
         }
     }
@@ -195,40 +190,42 @@ export function buildArgv(shell, command, paths, distro) {
 }
 /**
  * Merge the DSH_* environment over the process environment. For WSL, only
- * variables explicitly listed in WSLENV cross the boundary, so every DSH_* key is
- * appended to it (WSLENV is a `:` separated VAR[/flag] list).
+ * variables explicitly listed in WSLENV cross the boundary, so every DSH_*
+ * key is appended there — and the list is *layered onto* whatever WSLENV the
+ * host already had (Windows Terminal exports e.g. `WT_SESSION:WT_PROFILE_ID:`),
+ * never rebuilt from scratch: WSLENV is an allow-list, so dropping the
+ * inherited entries would silently stop them crossing into WSL.
  *
- * WSLENV usually already exists for reasons unrelated to us -- Windows Terminal
- * exports e.g. `WT_SESSION:WT_PROFILE_ID:` -- so the list is layered rather than
- * rebuilt, or those entries would be silently dropped from every WSL call.
- * Callers that spawn through a seam which replaces the parent environment
- * wholesale (the PTY path) must pass the inherited value explicitly.
- *
- * @param inheritedWslenv - the WSLENV the child would otherwise inherit.
+ * @param inheritedWslenv - the ambient WSLENV to layer onto. Callers that
+ *   replace the child environment wholesale (the PTY path) must pass
+ *   `process.env.WSLENV` explicitly, because the ambient value is not visible
+ *   through `dshEnv`.
  */
 export function buildEnv(shell, dshEnv, inheritedWslenv = process.env.WSLENV) {
     const env = { ...ENV_OVERRIDES, ...dshEnv };
     if (shell === "msys2") {
-        // Picks the MINGW64 environment, so /mingw64/bin (gcc, make, ...) joins PATH
-        // via /etc/profile. Without it MSYS2 defaults to the bare MSYS environment.
+        // Picks the MINGW64 environment, so /mingw64/bin (gcc, make, ...) joins
+        // PATH via /etc/profile. Without it MSYS2 defaults to the bare MSYS
+        // environment. An explicit caller-supplied value wins.
         if (env.MSYSTEM === undefined)
             env.MSYSTEM = "MINGW64";
     }
     if (shell === "wsl") {
         const keys = Object.keys(dshEnv ?? {});
         if (keys.length > 0) {
-            // An explicit WSLENV from the caller wins over what we would inherit.
+            // An explicit WSLENV in dshEnv wins over the inherited one; otherwise the
+            // inherited value is the base. Either way the base is SPLIT into entries
+            // (the host value ends with a trailing ":", so string concatenation would
+            // produce a malformed empty entry) and the WSLENV key itself is excluded
+            // (it is a key of dshEnv too, and appending it would add a bogus entry).
             const declared = Object.prototype.hasOwnProperty.call(dshEnv ?? {}, "WSLENV");
             const base = declared
                 ? env.WSLENV
                 : (typeof inheritedWslenv === "string" && inheritedWslenv.length > 0 ? inheritedWslenv : env.WSLENV);
-            // Windows Terminal's own value ends with a trailing ':' and the caller's
-            // may too, so split/normalise instead of string-concatenating -- a naive
-            // join yields an empty entry ("A:B::DSH_X"), which WSL flags as malformed.
             const parts = typeof base === "string" ? base.split(":") : [];
             env.WSLENV = [...parts, ...keys.filter((k) => k !== "WSLENV").flatMap((k) => k.split(":"))]
-                .map((part) => part.trim())
-                .filter((part) => part.length > 0)
+                .map((p) => p.trim())
+                .filter((p) => p.length > 0)
                 .join(":");
         }
     }
@@ -252,7 +249,7 @@ function spawnSpec(resolved, argv, env, signal) {
 function collectedOutput(handle) {
     const { stdout, stderr } = handle.collected;
     if (!isCollectedStream(stdout) || !isCollectedStream(stderr)) {
-        throw new Error("dsh-bash-terminal-ts: subprocess implementation dropped a requested collect stream");
+        throw new Error("dsh-bash-terminal: subprocess implementation dropped a requested collect stream");
     }
     return { stdout, stderr };
 }
@@ -293,7 +290,7 @@ async function runForeground(ctx, argv, resolved, env, signal, timeoutMs) {
 function requireSubprocess(ctx) {
     const subprocess = ctx.subprocess;
     if (subprocess === null) {
-        throw new Error("dsh-bash-terminal-ts: ctx.subprocess seam unavailable (missing inject service)");
+        throw new Error("dsh-bash-terminal: ctx.subprocess seam unavailable (missing inject service)");
     }
     return subprocess;
 }
@@ -442,8 +439,9 @@ export function validateArgs(args) {
  * Git Bash and MSYS2 are also not confined: DSH's Windows ACL restricted-token
  * runner cannot start Cygwin/MSYS2 (CreateFileMapping Win32 error 5), so
  * attempting to wrap them would abort every Git Bash / MSYS2 command. A
- * requested confined mode with no usable backend throws the fail-closed
- * SandboxUnavailableError, exactly like the shipped executors.
+ * requested confined mode
+ * with no usable backend throws the fail-closed SandboxUnavailableError,
+ * exactly like the shipped executors.
  */
 function confineSpawn(ctx, argv, policy, shell) {
     if (policy.mode === "danger-full-access" || shell === "wsl" || shell === "gitbash" || shell === "msys2") {
@@ -495,16 +493,24 @@ const BACKGROUND_OUTPUT_PROPERTIES = {
 // ---- plugin -------------------------------------------------------------------
 export function apply(ctx, config = {}) {
     if (process.platform !== "win32") {
-        ctx.logger?.info?.("dsh-bash-terminal-ts: only meaningful on win32; skipping tool registration");
+        ctx.logger?.info?.("dsh-bash-terminal: only meaningful on win32; skipping tool registration");
         return;
     }
     const backgroundEnabled = true;
     const paths = resolveAllPaths(config);
-    const defaultShell = config.defaultShell ?? DEFAULT_SHELL;
-    if (!SHELLS.includes(defaultShell)) {
-        throw new Error(`dsh-bash-terminal-ts: invalid defaultShell ${JSON.stringify(defaultShell)}`);
+    // 0.1.7: `defaultShell` is a `.volatile()` config field — the loader hands
+    // `apply` a live ref and the latest value is resolved on every read; there
+    // is no settings registration call anymore (removed with the 0.1.7 host).
+    const currentShell = () => {
+        const v = config.defaultShell;
+        if (typeof v === "string")
+            return v;
+        const got = typeof v?.get === "function" ? v.get() : undefined;
+        return typeof got === "string" ? got : DEFAULT_SHELL;
+    };
+    if (!SHELLS.includes(currentShell())) {
+        throw new Error(`dsh-bash-terminal: invalid defaultShell ${JSON.stringify(currentShell())}`);
     }
-    const settingsScope = ctx.settings.register(SETTINGS_NAMESPACE, z.object({ defaultShell: z.union(SHELLS.map((s) => z.const(s))).default(defaultShell) }), { base: { defaultShell } });
     /** Official sandbox-escalation surface (mirrors tool-bash): advertise the
      * escalation modes whenever the deployment confines. */
     const escalationModes = ESCALATION_TARGETS;
@@ -525,11 +531,11 @@ export function apply(ctx, config = {}) {
     ctx.systemPrompt.section({
         name: "tool:bash-terminal",
         order: 105,
-        text: "Use the shell tool for terminal commands: it runs in the terminal the user chose in Settings -> General -> Default terminal (PowerShell, Git Bash, or WSL) and honors the DSH sandbox. Prefer it over the pwsh tool for everyday commands; keep the pwsh tool for cases that specifically need the sandboxed PowerShell surface."
+        text: "Use the shell tool for terminal commands: it runs in the terminal the user chose in Settings -> General -> Default terminal (PowerShell, Git Bash, MSYS2, or WSL) and honors the DSH sandbox. Prefer it over the pwsh tool for everyday commands; keep the pwsh tool for cases that specifically need the sandboxed PowerShell surface."
     });
     const toolName = "shell";
     const terminalRegistry = createTerminalRegistry(ctx);
-    ctx.tools.register(terminalTool(ctx, terminalRegistry, paths, () => settingsScope.get().defaultShell));
+    ctx.tools.register(terminalTool(ctx, terminalRegistry, paths, () => currentShell()));
     // The model-facing description must track the user's chosen default
     // terminal: a static description listing every backend leaves the model
     // guessing which syntax applies. Re-render it on every prompt assembly —
@@ -537,7 +543,7 @@ export function apply(ctx, config = {}) {
     // without a restart.
     ctx.on("system-prompt/assemble", async (_assembly, _context, next) => {
         const assembled = await next();
-        const description = toolDescription(backgroundEnabled, settingsScope.get().defaultShell);
+        const description = toolDescription(backgroundEnabled, currentShell());
         const tools = Array.isArray(assembled.tools)
             ? assembled.tools.map((tool) => (tool.name === toolName ? { ...tool, description } : tool))
             : assembled.tools;
@@ -545,7 +551,7 @@ export function apply(ctx, config = {}) {
     });
     ctx.tools.register(defineTool({
         name: toolName,
-        description: toolDescription(backgroundEnabled, settingsScope.get().defaultShell),
+        description: toolDescription(backgroundEnabled, currentShell()),
         parameters: {
             command: {
                 type: "string",
@@ -644,10 +650,10 @@ export function apply(ctx, config = {}) {
         },
         async execute(args, exec) {
             const v = validateArgs(args);
-            const shell = settingsScope.get().defaultShell;
+            const shell = currentShell();
             const argv0 = buildArgv(shell, v.command, paths, v.distro);
             if (argv0[0] === undefined) {
-                throw new Error(`dsh-bash-terminal-ts: ${shell} backend unavailable - executable not found. Install it or set the corresponding *Path config.`);
+                throw new Error(`dsh-bash-terminal: ${shell} backend unavailable - executable not found. Install it or set the corresponding *Path config.`);
             }
             // Only element 0 (the resolved executable) can be undefined; guarded above.
             const argv = argv0;

package/lib/terminal.d.ts

@@ -4,14 +4,23 @@ export type TerminalSignal = (typeof TERMINAL_SIGNALS)[number];
 interface TerminalBufferRead {
     delta: string;
     nextOffset: number;
+    truncated: boolean;
 }
 interface TerminalBuffer {
     append(chunk: string): void;
     readFrom(offset: number): TerminalBufferRead;
     snapshot(): string;
+    wasTruncated(): boolean;
+    lastAppendAt(): number;
 }
 /** Interactive-shell argv (no -c: the terminal itself is the session). */
 export declare function terminalArgv(shell: string, paths: ResolvedPaths, distro?: string): Array<string | undefined>;
+export interface TerminalSessionInfo {
+    sessionId: string;
+    shell: string;
+    pid: number;
+    closed: boolean;
+}
 interface TerminalSession {
     id: string;
     handle: TerminalHandle;
@@ -19,6 +28,9 @@ interface TerminalSession {
     shell: string;
     distro?: string;
     closed: boolean;
+    idleMs: number;
+    idleTimer?: NodeJS.Timeout;
+    touch: () => void;
 }
 export interface TerminalOpenOptions {
     argv: string[];
@@ -29,6 +41,7 @@ export interface TerminalOpenOptions {
     cols: number;
     distro?: string;
     initial?: string;
+    idleMs?: number;
 }
 export interface TerminalRegistry {
     open(options: TerminalOpenOptions): Promise<TerminalSession>;
@@ -37,6 +50,7 @@ export interface TerminalRegistry {
     read(id: string): TerminalBufferRead;
     signal(id: string, sig: string): Promise<TerminalBufferRead>;
     close(id: string): Promise<boolean>;
+    list(): TerminalSessionInfo[];
 }
 /**
  * Terminal-session registry owned by the plugin fiber: opens PTYs through
@@ -51,6 +65,7 @@ export type ValidatedTerminalArgs = {
     command?: string;
     distro?: string;
     workdir?: string;
+    idleMs?: number;
 } | {
     action: "send";
     sessionId: string;
@@ -65,11 +80,14 @@ export type ValidatedTerminalArgs = {
 } | {
     action: "close";
     sessionId: string;
+} | {
+    action: "list";
 };
 export declare function validateArgs(args: Record<string, unknown>): asserts args is ValidatedTerminalArgs;
 export interface TerminalOpenResult {
     kind: "open";
     sessionId: string;
+    jobId?: string;
     pid: number;
     shell: string;
     output: string;
@@ -77,11 +95,16 @@ export interface TerminalOpenResult {
 export interface TerminalSessionResult {
     kind: "session";
     output: string;
+    truncated?: boolean;
 }
 export interface TerminalClosedResult {
     kind: "closed";
     sessionId: string;
 }
-export type TerminalToolResult = TerminalOpenResult | TerminalSessionResult | TerminalClosedResult;
+export interface TerminalListResult {
+    kind: "list";
+    sessions: TerminalSessionInfo[];
+}
+export type TerminalToolResult = TerminalOpenResult | TerminalSessionResult | TerminalClosedResult | TerminalListResult;
 export declare function terminalTool(ctx: BashTerminalContext, registry: TerminalRegistry, paths: ResolvedPaths, defaultShell: () => string): import("./dsh-types.js").ToolDefinition;
 export {};