Foreword¶

When using DSH (DeepSeek Harness) on Windows, models often face three sets of different command syntaxes: PowerShell uses $env:NAME and C:\... paths, Git Bash follows POSIX syntax and /d/WorkSpace mappings, while WSL uses Linux paths like /mnt/d/.... The official built-in pwsh tool only covers PowerShell; if your daily development involves switching between Git Bash or WSL, the model choosing the wrong terminal each time leads to command failures or path resolution errors.

Below, we introduce the community plugin dsh-bash-terminal: it provides an additional shell tool within DSH that executes commands based on the default terminal selected in your Web UI, along with an interactive terminal tool for maintaining session state across turns.

What This Is¶

dsh-bash-terminal is maintained by MAXeaglet, with source code hosted on GitHub. It is licensed under MIT, currently at npm version 0.3.14, and requires Node.js >= 20. The plugin only registers tools on the win32 platform.

Its positioning can be summarized as: a shell tool that unifies the execution of PowerShell, Git Bash, and WSL commands on Windows; the terminal type is selected by the user in the settings page, and the model cannot switch it via tool parameters.

How the Three Backends Execute¶

Each call to shell starts a fresh shell, retaining no cwd, variables, or aliases. To switch the working directory, pass the workdir parameter instead of using cd in the command.

Core Features¶

User-Selected Terminal, Model Cannot Alter¶

The Web UI settings page (Settings → General) provides a “Default Terminal” dropdown, with options for PowerShell, Git Bash, or WSL. The shell tool always uses this setting and does not expose a terminal parameter to the model. Settings are persisted via the DSH settings system into settings.yaml.

Does Not Occupy the Official pwsh Tool¶

The official sandboxed pwsh tool remains available as-is; this plugin’s shell is an additional multi-terminal entry point.

Process Management and Background Tasks¶

The plugin spawns processes via the shared ctx.subprocess seam. Behaviors like process tree termination (Windows taskkill /T), SIGTERM → grace → SIGKILL, and output spill files are consistent with the official dsh-tool-bash / dsh-tool-pwsh. Background tasks register in the general jobs registry, supporting run_in_background, job_output, and job_kill.

Interactive terminal Tool¶

The terminal tool provides a persistent interactive session over the PTY seam, maintaining session state (cwd, variables, aliases) across calls. It is suitable for REPL, ssh, and interactive CLIs:

• action: open starts a session, returning a sessionId; for WSL, you can specify distro to select a distribution.
• action: send writes input and reads new output; action: read reads without writing.
• action: signal sends a signal to the foreground process group (SIGINT maps to Ctrl+C).
• action: close terminates the session.

send waits for output to stabilize (300ms silence, up to 5s) before returning the full response; if output exceeds 1MB, a truncated notice is reported. Input ending with \n (or \r) indicates Enter.

Sandbox Integration¶

shell uses the official DSH sandbox seams (ctx.sandboxPolicy + ctx.sandbox):

• danger-full-access sessions execute directly without wrapping.
• The PowerShell backend is wrapped via ctx.sandbox.confine with fail-closed: in restricted mode with no available backend, it throws SandboxUnavailableError.
• Git Bash is not sandbox-wrapped (DSH Windows ACL restricted tokens are incompatible with Cygwin/MSYS2), reporting enforcement: gitbash-unconfined.
• WSL is not sandbox-wrapped (isolated via independent Linux VM), reporting enforcement: wsl-isolation.
• In restricted mode, if denied, the model can request an upgrade using sandbox_permissions + justification, subject to user approval via ctx.approval.

Installation and Enabling¶

The plugin comes with an official dsh.bundle manifest (cordis.patch.yml inside the package). Once the profile lists this package, DSH automatically applies the mount.

Standard installation steps:

# 1. Install the plugin package
npm install -g dsh-bash-terminal
dsh plugin --profile web add dsh-bash-terminal   # Automatically adds to profile bundles and applies patch

# 2. Patch DSH settings whitelist (DSH restriction, see note below)
powershell -ExecutionPolicy Bypass -File install.ps1 install

# 3. Restart dsh web

DSH’s api-gateway has a hardcoded whitelist for the settings namespace exposed to the Web settings client. Third-party plugin settings are rejected by default with settings-not-exposed. install.ps1 automatically patches the whitelist (adding bash-terminal and backing up the original file). After upgrading DSH, you need to run install.ps1 again; install.ps1 uninstall reverts changes when uninstalling.

Verify the composition tree (no restart needed):

node "$env:APPDATA\nvm\v24.16.0\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile web --dump-config | Select-String dsh-bash-terminal

Typical Usage¶

Set Default Terminal in Web UI¶

Open Settings (gear icon) → General → “Default Terminal” dropdown, and select PowerShell, Git Bash, or WSL. Changes take effect immediately and are persisted.

shell One-Off Commands¶

Once the model sees the shell tool, it automatically uses your selected terminal to execute commands:

shell(command: "git status", description: "Check git status")

When the default terminal is WSL, you can specify a distribution:

shell(command: "ls -la /mnt/d/WorkSpace", description: "List directory")

When the default terminal is PowerShell:

shell(command: "Get-Process node", description: "Check node processes")

terminal Maintains State Across Turns¶

terminal(action: "open")                    # Note the sessionId
terminal(action: "send", sessionId, input: "cd /d/project\n")
terminal(action: "send", sessionId, input: "npm run dev\n")
terminal(action: "close", sessionId)

Other operations: terminal(action: "list") to view active sessions; terminal(action: "signal", sessionId, signal: "SIGINT") to interrupt a running program; after sandbox denial, use shell(command: ..., sandbox_permissions: "workspace-write", justification: "...") to escalate privileges.

Configuration Options¶

Web UI Settings (recommended): Settings → General → “Default Terminal”.

Plugin config defaults:

Use Cases and Notes¶

Who it’s for: Developers using DSH on Windows who mix PowerShell, Git Bash, and WSL in daily development; need the model to execute commands using your preferred terminal syntax without the model choosing the backend itself.

Security Note: shell is an additional multi-terminal entry point and does not inherit the ConstrainedLanguage restrictions of the official pwsh tool. Git Bash in restricted mode is not sandbox-wrapped, running with the same privileges as the DSH process; WSL relies on independent VM isolation. For sandbox-protected PowerShell, continue using the official pwsh tool. DSH file operation tools (read/write/edit) remain constrained by the file sandbox. Use only in sessions you trust; review source code and license before installing.

Interactive Terminal Known Limitations (ConPTY):

• PowerShell 5.1 cannot start interactive sessions in ConPTY; install PowerShell 7 instead. One-off commands are unaffected.
• wsl.exe in interactive mode may occasionally encounter RPC errors under ConPTY; one-off wsl -e bash -lc ... works normally.
• On Windows, node-pty’s signal only maps SIGINT to Ctrl+C; other signals degrade to terminating the session.
• Git Bash interactive sessions work normally.

Other Limitations:

• WSL background processes may briefly linger in the distribution after timeout or interruption.
• Git Bash is an msys2 environment, differing from WSL Linux in behavior (path mapping, package availability).
• This plugin only registers tools on Windows.

Uninstallation¶

Recommended to run:

powershell -ExecutionPolicy Bypass -File install.ps1 uninstall

This deletes junctions, restores the settings whitelist, cleans up residual mount blocks, and removes dsh-bash-terminal from dsh.profile.bundles. Then restart dsh web.

For manual uninstallation, besides deleting node_modules\dsh-bash-terminal, also remove dsh-bash-terminal from the profile’s package.json dsh.profile.bundles.

Conclusion¶

dsh-bash-terminal converges three common terminals on Windows into a single shell tool: you select the default terminal in settings, and the model executes commands using that backend. Paired with the terminal tool, it maintains interactive sessions across turns. It does not replace the official pwsh but provides an additional entry point for developers using a mix of multiple terminal environments.

• Community directory page: https://www.skillhub.cn/plugins/MAXeaglet/dsh-bash-terminal
• GitHub repository: https://github.com/MAXeaglet/dsh-bash-terminal