dsh-bash-terminal-ts 0.2.5

package/lib/index.js

@@ -0,0 +1,759 @@
+// dsh-bash-terminal-ts - 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
+// terminal); the model cannot pick it — the tool always obeys the user's
+// 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.
+//   - wsl:        wsl [-d <distro>] -e bash -lc <cmd>  (Linux; /mnt/d/... paths)
+//
+// The tool spawns through the shared ctx.subprocess seam (process-tree
+// termination, SIGTERM->grace->SIGKILL, spill files) and registers background
+// 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.
+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";
+import { createTerminalRegistry, terminalTool } from "./terminal.js";
+/** Stable Cordis plugin name. */
+export const name = "bash-terminal";
+/** Services required before the tool can register. */
+export const inject = ["tools", "systemPrompt", "shellEnv", "subprocess", "settings", "sandbox", "sandboxPolicy"];
+/** The terminal backends this tool exposes, in catalog order. */
+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. */
+const MAX_TIMEOUT_MS = 600000;
+/** SIGTERM->SIGKILL grace (ms), matching dsh-bash-local's default. */
+const DEFAULT_GRACE_MS = 3000;
+/** Per-stream in-memory cap before spilling (bytes). */
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+/** Per-stream spill file cap (bytes). */
+const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024;
+/** Timeout code stamped on the deadline's TimeoutReason. */
+const TIMEOUT_CODE = "SHELL_TIMEOUT";
+/** Model-friendly environment overrides (same set dsh-bash-local hardcodes). */
+const ENV_OVERRIDES = {
+    NO_COLOR: "1",
+    TERM: "dumb",
+    PAGER: "cat",
+    GIT_PAGER: "cat"
+};
+/** Runtime configuration schema. */
+export const Config = z.object({
+    defaultShell: z.string().default(DEFAULT_SHELL),
+    timeoutMs: z.number().default(DEFAULT_TIMEOUT_MS),
+    maxTimeoutMs: z.number().default(MAX_TIMEOUT_MS),
+    pwshPath: z.string().default(""),
+    gitBashPath: z.string().default(""),
+    msys2Path: z.string().default(""),
+    wslPath: z.string().default("")
+});
+// ---- executable resolution ------------------------------------------------
+function candidateExists(candidate) {
+    try {
+        const stat = lstatSync(candidate);
+        return stat.isFile() || stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function resolveFromCandidates(candidates) {
+    for (const candidate of candidates) {
+        if (candidateExists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Well-known PowerShell install locations plus PATH entries, newest first. */
+export function candidatePwshPaths(env = process.env) {
+    const programFiles = env.ProgramFiles ?? "C:\\Program Files";
+    const systemRoot = env.SystemRoot ?? "C:\\Windows";
+    const candidates = [join(programFiles, "PowerShell", "7", "pwsh.exe")];
+    for (const entry of (env.PATH ?? "").split(";")) {
+        const trimmed = entry.trim().replace(/^"|"$/g, "");
+        if (trimmed.length === 0)
+            continue;
+        candidates.push(join(trimmed, "pwsh.exe"));
+    }
+    candidates.push(join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"));
+    return candidates;
+}
+/**
+ * Git for Windows locations, then PATH bash.exe entries EXCLUDING the
+ * System32 launcher (c:\\windows\\system32\\bash.exe is the WSL
+ * forwarder, not a Git Bash shell).
+ */
+export function candidateGitBashPaths(env = process.env) {
+    const programFiles = env.ProgramFiles ?? "C:\\Program Files";
+    const systemRoot = (env.SystemRoot ?? "C:\\Windows").toLowerCase();
+    const localAppData = env.LOCALAPPDATA ?? "";
+    const candidates = [
+        join(programFiles, "Git", "bin", "bash.exe"),
+        join(programFiles, "Git", "usr", "bin", "bash.exe")
+    ];
+    if (localAppData.length > 0)
+        candidates.push(join(localAppData, "Programs", "Git", "bin", "bash.exe"));
+    for (const entry of (env.PATH ?? "").split(";")) {
+        const trimmed = entry.trim().replace(/^"|"$/g, "");
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.toLowerCase().includes(systemRoot))
+            continue;
+        candidates.push(join(trimmed, "bash.exe"));
+    }
+    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.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.
+ *
+ * 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")) {
+            candidates.push(join(trimmed, "bash.exe"));
+        }
+    }
+    candidates.push("C:\\msys64\\msys2.exe"); // last resort: see the note above
+    return candidates;
+}
+export function defaultWslPath(env = process.env) {
+    const systemRoot = env.SystemRoot ?? "C:\\Windows";
+    return join(systemRoot, "System32", "wsl.exe");
+}
+export function resolveAllPaths(config = {}, env = process.env) {
+    const pwsh = config.pwshPath && config.pwshPath.trim().length > 0
+        ? config.pwshPath
+        : resolveFromCandidates(candidatePwshPaths(env));
+    const gitbash = config.gitBashPath && config.gitBashPath.trim().length > 0
+        ? config.gitBashPath
+        : resolveFromCandidates(candidateGitBashPaths(env));
+    const msys2 = config.msys2Path && config.msys2Path.trim().length > 0
+        ? config.msys2Path
+        : resolveFromCandidates(candidateMsys2Paths(env));
+    const wsl = config.wslPath && config.wslPath.trim().length > 0
+        ? config.wslPath
+        : defaultWslPath(env);
+    return { pwsh, gitbash, msys2, wsl };
+}
+// ---- argv / env construction ------------------------------------------------
+export function buildArgv(shell, command, paths, distro) {
+    switch (shell) {
+        case "powershell":
+            return [paths.pwsh, "-NoLogo", "-NoProfile", "-NonInteractive", "-Command", command];
+        case "gitbash":
+            return [paths.gitbash, "-lc", command];
+        case "msys2":
+            // -lc, not -c: a login shell sources /etc/profile, which is what puts
+            // /usr/bin and /mingw64/bin on PATH. With a bare -c, `tr`, `sed`, `gcc`
+            // and friends are all "command not found".
+            return [paths.msys2, "-lc", command];
+        case "wsl": {
+            const distroArg = distro !== undefined && distro.trim().length > 0 ? ["-d", distro.trim()] : [];
+            return [paths.wsl, ...distroArg, "-e", "bash", "-lc", command];
+        }
+        default:
+            throw new Error(`invalid shell: ${JSON.stringify(shell)} (expected one of ${SHELLS.join(", ")})`);
+    }
+}
+/**
+ * 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).
+ *
+ * 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.
+ */
+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.
+        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.
+            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)
+                .join(":");
+        }
+    }
+    return env;
+}
+function spawnSpec(resolved, argv, env, signal) {
+    const collect = (maxBytes) => ({ maxBytes, spill: { maxBytes: DEFAULT_MAX_SPILL_BYTES } });
+    return {
+        argv,
+        cwd: resolved.workdir,
+        stdio: {
+            stdin: resolved.stdin !== undefined ? { data: resolved.stdin } : "ignore",
+            stdout: collect(resolved.stdoutMaxBytes),
+            stderr: collect(DEFAULT_MAX_OUTPUT_BYTES)
+        },
+        graceMs: DEFAULT_GRACE_MS,
+        signal,
+        env
+    };
+}
+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");
+    }
+    return { stdout, stderr };
+}
+function isCollectedStream(value) {
+    return typeof value === "object" && value !== null && typeof value.readFrom === "function";
+}
+function finalOutput(reader) {
+    const read = reader.readFrom(0);
+    return {
+        text: read.text,
+        truncated: read.lossy,
+        ...(read.spillPath !== undefined ? { spillPath: read.spillPath } : {})
+    };
+}
+async function runForeground(ctx, argv, resolved, env, signal, timeoutMs) {
+    const subprocess = requireSubprocess(ctx);
+    const d = deadline(signal, timeoutMs, TIMEOUT_CODE);
+    try {
+        const handle = subprocess.spawn(spawnSpec(resolved, argv, env, d.signal));
+        const outcome = await handle.done;
+        const collected = collectedOutput(handle);
+        const timedOut = timeoutOf(d.signal, TIMEOUT_CODE) !== undefined;
+        const aborted = d.signal.aborted && !timedOut;
+        return {
+            exitCode: outcome.exitCode,
+            signal: outcome.signal,
+            timedOut,
+            aborted,
+            timeoutMs,
+            stdout: finalOutput(collected.stdout),
+            stderr: finalOutput(collected.stderr)
+        };
+    }
+    finally {
+        d[Symbol.dispose]();
+    }
+}
+function requireSubprocess(ctx) {
+    const subprocess = ctx.subprocess;
+    if (subprocess === null) {
+        throw new Error("dsh-bash-terminal-ts: ctx.subprocess seam unavailable (missing inject service)");
+    }
+    return subprocess;
+}
+function startBackground(ctx, argv, resolved, env, signal) {
+    const subprocess = requireSubprocess(ctx);
+    const running = subprocess.spawn(spawnSpec(resolved, argv, env, signal));
+    const collected = collectedOutput(running);
+    let stdoutOffset = 0;
+    let stderrOffset = 0;
+    let spawnFailureNote;
+    const consumeSpawnFailure = () => {
+        const note = spawnFailureNote ?? "";
+        spawnFailureNote = undefined;
+        return note;
+    };
+    const proc = {
+        status: "running",
+        exitCode: null,
+        signal: null,
+        done: running.done.then((outcome) => {
+            if (proc.status === "running") {
+                proc.status = signal?.aborted === true || outcome.signal !== null ? "killed" : "completed";
+            }
+            proc.exitCode = outcome.exitCode;
+            proc.signal = outcome.signal;
+        }, (error) => {
+            proc.status = "killed";
+            spawnFailureNote = `spawn failed: ${String(error)}`;
+        }),
+        readOutput: () => {
+            const out = collected.stdout.readFrom(stdoutOffset);
+            const err = collected.stderr.readFrom(stderrOffset);
+            stdoutOffset = out.nextOffset;
+            stderrOffset = err.nextOffset;
+            const errText = err.text.length > 0 ? err.text : consumeSpawnFailure();
+            const separator = out.text.length > 0 && !out.text.endsWith("\n") ? "\n" : "";
+            return {
+                delta: out.text + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : ""),
+                lossy: out.lossy || err.lossy,
+                ...(out.spillPath !== undefined ? { stdoutSpillPath: out.spillPath } : {}),
+                ...(err.spillPath !== undefined ? { stderrSpillPath: err.spillPath } : {})
+            };
+        },
+        kill: () => {
+            if (proc.status !== "running")
+                return false;
+            proc.status = "killed";
+            running.terminate();
+            return true;
+        }
+    };
+    return proc;
+}
+function processOutcome(proc) {
+    if (proc.status === "killed") {
+        return { status: "killed", detail: proc.signal !== null ? `signal: ${proc.signal}` : "killed before exit" };
+    }
+    return { status: "completed", detail: `exit code: ${proc.exitCode ?? 0}` };
+}
+// ---- model-facing rendering ---------------------------------------------------
+function streamText(output) {
+    if (!output.truncated)
+        return output.text;
+    return `${output.text}\n[output truncated; full output: ${output.spillPath ?? "(unavailable)"}]`;
+}
+export function renderResult(result) {
+    const out = streamText(result.stdout);
+    const err = streamText(result.stderr);
+    let body = out;
+    if (err.length > 0) {
+        if (body.length > 0 && !body.endsWith("\n"))
+            body += "\n";
+        body += `[stderr]\n${err}`;
+    }
+    if (body.length === 0)
+        body = "(no output)";
+    const markers = [];
+    if (result.timedOut)
+        markers.push(`[timed out after ${result.timeoutMs}ms]`);
+    if (result.signal !== null)
+        markers.push(`[killed by signal: ${result.signal}]`);
+    else if (result.exitCode !== 0)
+        markers.push(`[exit code: ${result.exitCode}]`);
+    if (markers.length === 0)
+        return body;
+    if (!body.endsWith("\n"))
+        body += "\n";
+    return body + markers.join("\n");
+}
+function renderProcessRead(read) {
+    const notices = [];
+    if (read.lossy) {
+        const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((p) => p !== undefined);
+        notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(", ") : "(unavailable)"}]`);
+    }
+    if (notices.length === 0)
+        return read.delta;
+    return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith("\n") ? "\n" : ""}${notices.join("\n")}`;
+}
+// ---- tool description / validation --------------------------------------------
+/** Model-facing lead sentence for each backend. The user's default terminal is
+ * stated up front so the model never has to guess which syntax applies. */
+export const SHELL_DESCRIPTIONS = {
+    powershell: "Execute a PowerShell command (pwsh -NoLogo -NoProfile -NonInteractive -Command <command>) and return its stdout/stderr. PowerShell syntax; native Windows paths (C:\\...); environment variables via $env:NAME.",
+    gitbash: "Execute a bash command (Git for Windows bash -lc <command>) and return its stdout/stderr. POSIX syntax; paths like /d/WorkSpace; PATH includes /usr/bin and /mingw64/bin so git, npm, ssh etc. work; environment variables via $NAME.",
+    msys2: "Execute a bash command (MSYS2 bash -lc <command>) and return its stdout/stderr. POSIX syntax; paths like /c/...; PATH includes /usr/bin and /mingw64/bin so git, npm, gcc, make etc. work; environment variables via $NAME. MSYS2 provides a full GCC/mingw64 toolchain.",
+    wsl: "Execute a Linux bash command (wsl [-d <distro>] -e bash -lc <command>) and return its stdout/stderr. Linux syntax; Windows files under /mnt/d/...; environment variables via $NAME."
+};
+/**
+ * Render the model-facing tool description for one backend. The backend is
+ * whatever the user chose in Settings -> General -> Default terminal; the
+ * description names it explicitly so the model writes the right syntax.
+ * @param backgroundEnabled - advertise `run_in_background` controls.
+ * @param shell - active backend; unknown values fall back to the default.
+ */
+export function toolDescription(backgroundEnabled, shell = DEFAULT_SHELL) {
+    const active = SHELLS.includes(shell) ? shell : DEFAULT_SHELL;
+    const lead = SHELL_DESCRIPTIONS[active];
+    const base = [
+        `The user's chosen default terminal (Settings -> General -> Default terminal) is ${active}; commands run there.`,
+        lead,
+        "Each call spawns a fresh shell: no state (cwd, variables, aliases) persists between calls - pass workdir instead of using cd. Non-zero exits are reported as [exit code: N] markers; investigate failures before moving on. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Commands run under the DSH sandbox: confined modes (read-only / workspace-write) are enforced through ctx.sandbox and deny fail-closed for PowerShell; danger-full-access, Git Bash, MSYS2, and WSL run unconfined."
+    ].join(" ");
+    if (!backgroundEnabled)
+        return base;
+    return base + " Set run_in_background: true for long-running commands: the call returns a job id immediately; read its output with job_output and stop it with job_kill. No timeout applies to background runs.";
+}
+export function validateArgs(args) {
+    if (typeof args.command !== "string" || args.command.trim().length === 0) {
+        throw new Error("invalid command: expected a non-empty string");
+    }
+    if (typeof args.description !== "string" || args.description.trim().length === 0) {
+        throw new Error("invalid description: expected a non-empty string");
+    }
+    if (args.timeoutMs !== undefined && (typeof args.timeoutMs !== "number" || !Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+        throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`);
+    }
+    validateEscalationArgs(args.sandbox_permissions, args.justification);
+    return args;
+}
+/**
+ * Official sandbox seam (mirrors dsh-tool-bash / dsh-pwsh-sandbox): resolve the
+ * per-call policy from ctx.sandboxPolicy, and — unless the call runs
+ * danger-full-access — confine the spawn argv through ctx.sandbox. WSL is a
+ * self-contained Linux VM and is not confined (its isolation IS the sandbox).
+ * 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.
+ */
+function confineSpawn(ctx, argv, policy, shell) {
+    if (policy.mode === "danger-full-access" || shell === "wsl" || shell === "gitbash" || shell === "msys2") {
+        const sandbox = shell === "wsl"
+            ? { mode: policy.mode, enforcement: "wsl-isolation" }
+            : shell === "gitbash"
+                ? { mode: policy.mode, enforcement: "gitbash-unconfined" }
+                : shell === "msys2"
+                    ? { mode: policy.mode, enforcement: "msys2-unconfined" }
+                    : undefined;
+        return { argv, sandbox };
+    }
+    const confined = ctx.sandbox.confine(argv, policy);
+    return {
+        argv: confined.argv,
+        sandbox: { mode: policy.mode, enforcement: confined.enforcement, denialSignatures: confined.denialSignatures }
+    };
+}
+function resolveWorkdir(modelWorkdir, exec) {
+    const headerCwd = exec.agent?.session.header.cwd;
+    if (modelWorkdir === undefined)
+        return headerCwd;
+    if (headerCwd !== undefined && !isAbsolute(modelWorkdir))
+        return resolve(headerCwd, modelWorkdir);
+    return modelWorkdir;
+}
+function canonicalResult(result) {
+    const output = (stream) => ({
+        text: stream.text,
+        truncated: stream.truncated,
+        ...(stream.spillPath !== undefined ? { spillPath: stream.spillPath } : {})
+    });
+    return {
+        kind: "foreground",
+        exitCode: result.exitCode,
+        signal: result.signal,
+        timedOut: result.timedOut,
+        aborted: result.aborted,
+        timeoutMs: result.timeoutMs,
+        stdout: output(result.stdout),
+        stderr: output(result.stderr),
+        ...(result.sandbox !== undefined ? { sandbox: result.sandbox } : {})
+    };
+}
+const BACKGROUND_OUTPUT_PROPERTIES = {
+    kind: { type: "string", required: true, const: "background" },
+    jobId: { type: "string", required: true }
+};
+// ---- plugin -------------------------------------------------------------------
+export function apply(ctx, config = {}) {
+    if (process.platform !== "win32") {
+        ctx.logger?.info?.("dsh-bash-terminal-ts: 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)}`);
+    }
+    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;
+    const approveShellEscalation = (mode, justification, exec, standingPolicy) => {
+        return approveEscalation({
+            requestedMode: mode,
+            justification,
+            effectiveMode: standingPolicy.mode,
+            subject: "command"
+        }, {
+            approver: ctx.get("approval"),
+            agent: exec.agent,
+            callId: exec.callId,
+            toolName: "shell",
+            signal: exec.signal
+        });
+    };
+    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."
+    });
+    const toolName = "shell";
+    const terminalRegistry = createTerminalRegistry(ctx);
+    ctx.tools.register(terminalTool(ctx, terminalRegistry, paths, () => settingsScope.get().defaultShell));
+    // 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 —
+    // settings are hot-reloaded, so a change shows up on the next request
+    // without a restart.
+    ctx.on("system-prompt/assemble", async (_assembly, _context, next) => {
+        const assembled = await next();
+        const description = toolDescription(backgroundEnabled, settingsScope.get().defaultShell);
+        const tools = Array.isArray(assembled.tools)
+            ? assembled.tools.map((tool) => (tool.name === toolName ? { ...tool, description } : tool))
+            : assembled.tools;
+        return { ...assembled, tools };
+    });
+    ctx.tools.register(defineTool({
+        name: toolName,
+        description: toolDescription(backgroundEnabled, settingsScope.get().defaultShell),
+        parameters: {
+            command: {
+                type: "string",
+                required: true,
+                description: "The command to execute in the selected terminal."
+            },
+            description: {
+                type: "string",
+                required: true,
+                description: "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" -> \"List files in current directory\"; \"git status\" -> \"Show working tree status\"; \"npm install\" -> \"Install package dependencies\"."
+            },
+            distro: {
+                type: "string",
+                description: "WSL distribution to use (only when the configured default terminal is wsl). Defaults to the system default distribution."
+            },
+            sandbox_permissions: {
+                type: "string",
+                enum: escalationModes,
+                description: "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval."
+            },
+            justification: {
+                type: "string",
+                description: "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
+            },
+            workdir: {
+                type: "string",
+                description: "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+            },
+            timeoutMs: {
+                type: "number",
+                description: "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+            },
+            run_in_background: {
+                type: "boolean",
+                description: "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies."
+            }
+        },
+        output: {
+            schema: {
+                oneOf: [
+                    { type: "object", additionalProperties: false, properties: BACKGROUND_OUTPUT_PROPERTIES },
+                    {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            kind: { type: "string", required: true, const: "foreground" },
+                            exitCode: { required: true, oneOf: [{ type: "integer" }, { type: "null" }] },
+                            signal: { required: true, oneOf: [{ type: "string" }, { type: "null" }] },
+                            timedOut: { type: "boolean", required: true },
+                            aborted: { type: "boolean", required: true },
+                            timeoutMs: { type: "number", required: true },
+                            sandbox: {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    mode: { type: "string", required: true },
+                                    enforcement: { type: "string", required: true },
+                                    denied: { type: "boolean" }
+                                }
+                            },
+                            stdout: {
+                                type: "object",
+                                additionalProperties: false,
+                                required: true,
+                                properties: {
+                                    text: { type: "string", required: true },
+                                    truncated: { type: "boolean", required: true },
+                                    spillPath: { type: "string" }
+                                }
+                            },
+                            stderr: {
+                                type: "object",
+                                additionalProperties: false,
+                                required: true,
+                                properties: {
+                                    text: { type: "string", required: true },
+                                    truncated: { type: "boolean", required: true },
+                                    spillPath: { type: "string" }
+                                }
+                            }
+                        }
+                    }
+                ]
+            },
+            render: (_args, value) => {
+                if (value.kind === "background")
+                    return [{ type: "text", text: `started background job ${value.jobId}` }];
+                let text = renderResult(value);
+                if (value.sandbox?.denied === true) {
+                    if (!text.endsWith("\n"))
+                        text += "\n";
+                    text += sandboxDenialMarker(value.sandbox.mode) + "\n" + escalationHintMarker("command");
+                }
+                return [{ type: "text", text }];
+            }
+        },
+        async execute(args, exec) {
+            const v = validateArgs(args);
+            const shell = settingsScope.get().defaultShell;
+            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.`);
+            }
+            // Only element 0 (the resolved executable) can be undefined; guarded above.
+            const argv = argv0;
+            const workdir = resolveWorkdir(v.workdir, exec);
+            const timeoutMs = clampTimeout(v.timeoutMs, config.timeoutMs ?? DEFAULT_TIMEOUT_MS, config.maxTimeoutMs ?? MAX_TIMEOUT_MS, "shell timeoutMs");
+            const dshEnv = ctx.shellEnv.collect(exec);
+            const env = buildEnv(shell, dshEnv);
+            let policy = ctx.sandboxPolicy.resolve(exec.agent ? { session: exec.agent.session } : {});
+            if (v.sandbox_permissions !== undefined && v.justification !== undefined) {
+                const approvedMode = await approveShellEscalation(v.sandbox_permissions, v.justification, exec, policy);
+                policy = { ...policy, mode: approvedMode };
+            }
+            const { argv: confinedArgv, sandbox } = confineSpawn(ctx, argv, policy, shell);
+            const resolved = {
+                command: v.command,
+                workdir: workdir ?? process.cwd(),
+                timeoutMs,
+                stdoutMaxBytes: DEFAULT_MAX_OUTPUT_BYTES,
+                ...(v.stdin !== undefined ? { stdin: v.stdin } : {})
+            };
+            if (v.run_in_background === true) {
+                const jobs = ctx.get("jobs");
+                if (jobs === undefined)
+                    throw new Error("background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs");
+                if (exec.signal.aborted) {
+                    const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+                    error.name = "AbortError";
+                    throw error;
+                }
+                return {
+                    kind: "background",
+                    jobId: jobs.start({
+                        kind: `shell/${shell}`,
+                        label: v.command,
+                        ...(exec.agent ? { owner: exec.agent } : {}),
+                        run: () => {
+                            const proc = startBackground(ctx, confinedArgv, resolved, env, exec.signal);
+                            return {
+                                cancel: () => void proc.kill(),
+                                done: proc.done.then(() => processOutcome(proc)),
+                                readOutput: () => renderProcessRead(proc.readOutput())
+                            };
+                        }
+                    })
+                };
+            }
+            const result = await runForeground(ctx, confinedArgv, resolved, env, exec.signal, timeoutMs);
+            if (result.aborted) {
+                const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+                error.name = "AbortError";
+                throw error;
+            }
+            const denied = sandbox?.denialSignatures !== undefined
+                ? sandbox.denialSignatures.some((sig) => result.stderr.text.toLowerCase().includes(sig.toLowerCase()))
+                : false;
+            return canonicalResult({
+                ...result,
+                ...(sandbox !== undefined ? { sandbox: { mode: sandbox.mode, enforcement: sandbox.enforcement, denied } } : {})
+            });
+        },
+        presentCall: (args) => {
+            if (args.run_in_background === true) {
+                return {
+                    card: "generic",
+                    title: args.command,
+                    kind: "execute",
+                    rawInput: args.command,
+                    content: [{ type: "text", text: args.description }]
+                };
+            }
+            return {
+                card: "terminal",
+                title: args.command,
+                description: args.description,
+                ...(args.workdir !== undefined ? { cwd: args.workdir } : {})
+            };
+        },
+        presentResult: (args, result) => {
+            const block = result.content.length === 1 ? result.content[0] : undefined;
+            if (block === undefined || block.type !== "text")
+                return undefined;
+            const raw = block.text ?? "";
+            if (args.run_in_background === true || result.isError) {
+                return { card: "generic", content: [{ type: "text", text: "```console\n" + raw.replace(/\n+$/, "") + "\n```" }] };
+            }
+            const { body, ...exit } = parseExitStatus(raw);
+            return { card: "terminal", output: body, ...exit };
+        }
+    }));
+}
+//#region internals for tests
+export const internals = {
+    candidateExists,
+    resolveAllPaths,
+    resolveWorkdir,
+    renderResult,
+    processOutcome,
+    startBackground,
+    runForeground,
+    spawnSpec,
+    buildEnv,
+    buildArgv,
+    validateArgs,
+    toolDescription,
+    SHELL_DESCRIPTIONS,
+    DEFAULT_TIMEOUT_MS,
+    MAX_TIMEOUT_MS,
+    DEFAULT_MAX_OUTPUT_BYTES
+};