dsh-msys2-bash-executor

Readme

# dsh-msys2-bash-executor

[中文说明](README.zh-CN.md)

A standalone, configurable Bash executor for DeepSeek Harness on Windows. It can run agent shell calls through MSYS2/UCRT64 Bash or Git Bash, and adds a visual configuration card to the DSH Web settings page.

This package does not depend on `dsh-anchored-standard` or `dsh-anchored-standard-bash`. Its bundle registers one isolated global Bash tool and can expose it globally or only to selected preset IDs.

## Features

- Direct `argv` spawning through DSH's managed `subprocess` service. It does not use Node's `shell: true` mode.
- Automatic detection of MSYS2, UCRT64, Git Bash, and `bash` on `PATH`.
- Configurable executable, Bash arguments, `PATH` prefixes, and environment variables.
- Foreground timeouts, abort handling, bounded output, spill files, background jobs, incremental reads, and process-tree termination.
- DSH Web settings card with English and Chinese copy.
- Global activation or per-preset activation for Standard, Code, Cordis, Minimal, and custom preset IDs.
- Minimal-specific shadowing that bypasses DSH's unsupported Windows persistent-terminal inspection path.
- The Host PowerShell provider remains installed for presets where Bash is disabled.

## Security

This executor is unsandboxed. Commands run with the full permissions of the DSH process, equivalent to `danger-full-access`. It does not provide the Windows ACL sandbox used by the stock PowerShell sandbox executor.

Only use it with trusted prompts, repositories, and tools.

## Install from a local package

The package is not published to npm yet. Build and pack it locally:

```powershell
npm.cmd run check
npm.cmd pack
dsh plugin --profile web add "C:\path\to\dsh-msys2-bash-executor-0.1.1.tgz"
```

To build from GitHub:

```powershell
git clone https://github.com/3223698962/dsh-msys2-bash-executor.git
cd dsh-msys2-bash-executor
npm.cmd install
npm.cmd run check
npm.cmd pack --cache .npm-cache
dsh plugin --profile web add "C:\path\to\dsh-msys2-bash-executor-0.1.1.tgz"
```

Restart `dsh web` after installing or updating the plugin. Activation changes affect newly created sessions; running sessions keep the tool set they started with.

## Configure in DSH Web

Open Settings, then Plugins, then the configurable plugins tab. The **MSYS2 / Git Bash** card provides:

- **Use Bash for every preset**: expose global `bash` and hide `pwsh` in all newly created sessions.
- **Preset activation**: independently enable Standard, Code, Cordis, Minimal, or any custom preset ID when global mode is off.
- **Bash executable**: for example `C:\msys64\usr\bin\bash.exe` or `C:\Program Files\Git\bin\bash.exe`.
- **Bash arguments**: JSON array placed before the command. The normal value is `["-c"]`.
- **PATH entries to prepend**: one Windows path per line.
- **Environment variables**: a JSON object containing string values.

For UCRT64 when DSH was not started from an existing UCRT64 terminal, a typical configuration is:

```text
Bash executable:
C:\msys64\usr\bin\bash.exe

PATH entries to prepend:
C:\msys64\ucrt64\bin
C:\msys64\usr\bin

Environment variables:
{"MSYSTEM":"UCRT64","CHERE_INVOKING":"1"}
```

Settings are stored in the package-owned `msys2-bash` namespace. This keeps Bash activation and launch configuration independent from the Host PowerShell provider. The Web card reads and writes that namespace through the plugin's own typed Remote, because DSH 0.1.0-rc.6 exposes only a fixed built-in namespace allowlist through its generic settings API.

When Bash is enabled for Minimal, the plugin registers the standalone Bash definition in the agent's nearest tool layer. That shadows Minimal's built-in persistent Bash tool and avoids `subprocess-local: terminal inspection is unsupported on platform win32`. Shell state is therefore not persistent between calls in this mode.

## Activation model

The bundle mounts an isolated Bash executor and `@deepseek-ai/dsh-tool-bash` at the Host layer. For each newly created agent it reads the effective preset ID:

- enabled preset: expose global `bash` and hide inherited `pwsh`;
- disabled preset: hide global `bash` when it would otherwise be visible;
- Minimal enabled: shadow the persistent terminal tool with the standalone Bash definition;
- Minimal disabled: leave its stock persistent tool untouched.

Set `globalEnabled: true` to cover every preset, or keep it false and list IDs in `enabledPresets`.

## Manual preset mount

Add an isolated shell group to the preset's `agent.cordis.yml`:

```yaml
- id: shell-bash
  name: cordis:group
  group: true
  isolate:
    shell: true
  config:
    - id: msys2-bash-executor
      name: dsh-msys2-bash-executor/bash-executor
      disabled: !!js process.platform !== 'win32'

    - id: tool-bash
      name: '@deepseek-ai/dsh-tool-bash'
```

The `shell` isolation is required because the executor provides `ctx.shell`. Mounting another shell provider in the same realm as the Host PowerShell provider causes a duplicate-service error.

On non-Windows systems, the recommended `disabled` expression leaves the executor off and lets `tool-bash` resolve the Host Bash provider. Remove the expression only when an unsandboxed local Bash executor is also desired there.

## Resolution order

If the executable field is empty, the resolver checks:

1. `DSH_BASH_PATH`.
2. `MSYS2_ROOT` and `MSYS_ROOT`.
3. `C:\msys64\usr\bin\bash.exe` and `C:\msys64\ucrt64\bin\bash.exe`.
4. Git Bash under Program Files and Local AppData.
5. Each Windows `PATH` entry.
6. The command name `bash`.

An explicitly configured executable is always used as-is, so a bad path fails visibly at spawn time.

## Scope

This plugin changes DSH agent tool visibility inside the Web profile. It does not reconfigure external Codex CLI or Claude Code subprocess providers. Those products need their own shell or environment configuration, although they can independently invoke the same MSYS2/Git Bash executable.

## Development

```powershell
npm.cmd run build
npm.cmd test
npm.cmd run check
npm.cmd run pack:dry
```

`src/client.js` is the browser source. `scripts/build-client.mjs` generates `lib/client.js` in the `window.__ModuleLoader__` format required by DSH Web.

## Troubleshooting

- If Bash starts in the wrong MSYS2 subsystem, set `MSYSTEM` and prepend the matching toolchain directory.
- Use Windows paths in the settings card because the executable is spawned by Windows Node.
- Start DSH with Windows-native Node. The MSYS2 build of Node is not compatible with the current DSH Windows launcher.
- Node warning `DEP0190` is not emitted by this executor: it passes a complete `argv` to DSH subprocess and never sets `shell: true`. Trace that warning to the plugin that calls `child_process.spawn` with both an argument array and `shell: true`.

## License

MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).