dsh-win-multi-bash 0.3.1 → 0.4.0

package/lib/tool-bash/types/factory.js

@@ -13,12 +13,16 @@ import { isAbsolute, resolve as resolvePath } from 'node:path';
 import { defineTool, TOOL_ABORTED } from '@deepseek-ai/dsh-tools';
 import { HarnessError } from '@deepseek-ai/dsh-llm';
 import { ESCALATION_TARGETS, approveEscalation, canonicalPath, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox';
-import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-shell';
 import { ownExecutor } from "./backend.js";
 import { processJob, processOutcome, processSources } from "./background.js";
 import { parseExitStatus, renderResult } from "./render.js";
+import { SHELL_FAMILY_ROW_SPECIFIER, composeToolDescription, familyRowComposed } from "./shell-family.js";
+/**
+ * The dialect-owned facts of this plugin's two shell tools. Everything they
+ * share lives in one registered prompt section instead (see
+ * ./shell-family.js), so a fact stated here is stated only here.
+ */
 const DIALECT_FACTS = {
-    posix: { shell: 'bash', invoke: 'bash -c', paths: 'POSIX paths', env: '$VAR', toolchain: 'the full Unix toolchain' },
     msys: {
         shell: 'Git Bash (MSYS2)',
         invoke: 'bash -c',
@@ -35,80 +39,26 @@ const DIALECT_FACTS = {
 };
 /** The tool-layer keys every shell tool instance carries, before its backend partition. */
 const TOOL_CONFIG = {
-    enableRunInBackground: z.boolean().default(true),
+    enableRunInBackground: z.boolean().default(true).volatile(),
 };
 /**
- * Cross-call exit-status guidance for one shell tool instance. It belongs in the
- * prompt rather than the tool schema because the trap is not about one call's
- * arguments but about how a multi-step command is composed: `;` never stops on
- * failure, and a pipeline reports only its last command's status — so the
- * reflex of bounding long output with `| tail`, which this runtime already
- * truncates for the caller, returns `tail`'s status instead of the command's.
- */
-export const SHELL_EXIT_STATUS_SECTION = 'Check the [exit code: N] marker on every bash result; investigate failures before moving on. Chain dependent steps with `&&` or `set -o pipefail`: `;` never stops on failure, and `cmd | tail` returns the status of `tail`, not of `cmd`.';
-/**
- * The model-facing description of one shell tool instance. The POSIX variant
- * keeps the legacy wording byte-for-byte (the ACP/headless tool-schema
- * fixtures pin it); msys/wsl instances mirror the official tool-pwsh
- * skeleton (fresh shell, paths/env, exit codes, sandbox, truncation,
- * background, escalation) with only their dialect's shell/paths/env facts
- * plus at most one short dialect note.
+ * The model-facing description of one shell tool instance: only what this
+ * dialect owns — its shell and invocation, its path form, its variable syntax,
+ * and at most one short dialect note. Everything the family shares (fresh
+ * calls, exit markers, sandbox markers, truncation, path safety, background,
+ * escalation) is registered once for the composition by the
+ * `tool-shell-prompt` row, so no tool description repeats it.
  * @param dialect - the shell dialect the instance runs.
- * @param backgroundEnabled - whether `run_in_background` is advertised.
- * @param escalationModes - the escalation targets this composition advertises;
- *   empty adds no same-turn escalation guidance.
  * @returns the tool description passed to `defineTool`.
  */
-export function shellDescription(dialect, backgroundEnabled, escalationModes) {
-    const background = backgroundEnabled
-        ? '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`.'
-        : 'Background execution is not available; long-running commands must finish within the timeout.';
-    if (dialect === 'posix') {
-        const base = 'Execute a bash command (`bash -c`) and return its stdout/stderr. '
-            + 'Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — '
-            + 'pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. '
-            + `Current harness environment facts are exposed through managed \`\$${DSH_ENV_PREFIX}*\` variables; inspect them when needed. `
-            + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. '
-            + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
-            + background;
-        return base + escalationTail(escalationModes);
-    }
+export function shellDescription(dialect) {
     const facts = DIALECT_FACTS[dialect];
+    if (facts === undefined)
+        throw new Error(`unknown shell dialect "${dialect}"`);
     const note = facts.note === undefined ? '' : ` Note: ${facts.note}.`;
-    const base = `Execute a ${facts.shell} command (${facts.invoke}) and return its stdout/stderr. `
-        + 'Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — '
-        + 'pass `workdir` instead of using `cd`. '
+    return `Execute a ${facts.shell} command (${facts.invoke}) and return its stdout/stderr. `
         + `Paths use ${facts.paths}; read environment variables with ${facts.env}.`
-        + note + ' '
-        + 'Non-zero exits are reported as `[exit code: N]`. '
-        + `Current harness environment facts are exposed through managed \`\$${DSH_ENV_PREFIX}*\` variables; inspect them when needed. `
-        + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. '
-        + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
-        + 'Before any delete or move, verify that the resolved absolute target path is the intended one; never run it against a computed path you have not checked. '
-        + 'An unset variable expands to an empty string, so guard variables in such paths with `${VAR:?}`. '
-        + background;
-    return base + escalationTail(escalationModes);
-}
-/**
- * The same-turn escalation guidance appended after a denial marker. Kept in
- * one place because every dialect shares the exact approval contract.
- * @param escalationModes - the escalation targets this composition advertises.
- * @returns the guidance sentence, or '' when no escalation is advertised.
- */
-function escalationTail(escalationModes) {
-    if (escalationModes.length === 0)
-        return '';
-    return ' Attempting a command the sandbox may deny is safe and expected: run it and read the '
-        + 'marker rather than assuming the denial. When a command is denied and a wider mode would let it '
-        + 'succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry '
-        + 'the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) '
-        + 'plus a one-sentence `justification`. Do not detour through chat to ask permission first — the '
-        + 'approval prompt raised by that retry is how the user consents. If the session states approval '
-        + 'prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. '
-        + 'Never escalate speculatively: ground the request in a real denial — normally the one this command '
-        + 'just hit; escalating up front is fine only when this session already denied the same access. '
-        + 'A rejected escalation is final for that command — stop and explain, never work around '
-        + 'it — but it does not forbid attempting or escalating other commands later.';
+        + note;
 }
 function validateShellArgs(args) {
     if (args.command.trim().length === 0) {
@@ -254,12 +204,19 @@ export function defineShellTool(def) {
     });
     return {
         name: `tool-${def.toolName}`,
+        // The tool registers no prompt section of its own: the family's shared
+        // guidance is owned by the separate `tool-shell-prompt` row (see
+        // ./shell-family.js), so this row needs no `systemPrompt`.
         // The last three are the owned executor's own requirements; injecting
         // them here is what lets the backend be built during apply.
-        inject: ['tools', 'systemPrompt', 'shellEnv', 'subprocess', 'sandbox', 'sandboxPolicy'],
+        inject: ['tools', 'shellEnv', 'subprocess', 'sandbox', 'sandboxPolicy'],
         Config,
         async apply(ctx, config = {}) {
-            const backgroundEnabled = config.enableRunInBackground ?? true;
+            // Volatile: the loader hands a live reference, so a saved value is
+            // read here rather than off a snapshot.
+            const backgroundEnabled = config.enableRunInBackground?.get() ?? true;
+            const familyPresent = familyRowComposed(ctx);
+            if (!familyPresent) ctx.logger?.warn?.(`tool-${def.toolName}: the row that owns the shared shell prompt section (${SHELL_FAMILY_ROW_SPECIFIER}) is not composed, so this tool's description carries that guidance itself. Re-enable that row to state it once for the whole family.`);
             const { executor } = ownExecutor(ctx, def.Executor, config[def.configKey]);
             // The confinement probe is async on 0.1.7 (the provider's `confine`
             // returns a promise), so the escalation surface settles before the
@@ -309,15 +266,14 @@ export function defineShellTool(def) {
                     signal: exec.signal,
                 });
             };
-            // Cross-call guidance belongs in the prompt rather than one-call schema prose.
-            ctx.systemPrompt.section({
-                name: `tool:${def.toolName}`,
-                order: 105,
-                text: SHELL_EXIT_STATUS_SECTION,
-            });
             ctx.tools.register(defineTool({
                 name: def.toolName,
-                description: shellDescription(def.dialect, backgroundEnabled, escalationModes),
+                description: composeToolDescription({
+                    own: shellDescription(def.dialect),
+                    familyPresent,
+                    background: backgroundEnabled,
+                    escalation: escalationModes.length > 0,
+                }),
                 parameters: {
                     command: { type: 'string', required: true, description: 'The bash command to execute.' },
                     description: {

package/lib/tool-bash/types/shell-family.js

@@ -0,0 +1,193 @@
+/**
+ * The shared half of the shell guidance: what every shell tool call in this
+ * composition has in common, stated once for the whole family.
+ *
+ * Why the split exists (measured on 0.3.1: the two tool descriptions were 1299
+ * and 2164 characters, 1117 of them byte-identical, and the same exit-status
+ * paragraph was registered twice — once per tool instance):
+ *  - A tool description is ambient only while that tool is mounted, so it can
+ *    carry only what belongs to that tool. Anything the family shares belongs
+ *    in one prompt section; anything dialect-specific (shell name, path form,
+ *    MSYS note) stays with its own tool.
+ *  - The section has exactly one owner — the `tool-shell-prompt` row — because
+ *    prompt sections live in one global layer keyed by name: two rows
+ *    registering the same name throw, and two names carrying the same text are
+ *    the duplication this module exists to remove.
+ *  - Its text is a function of the tools actually mounted
+ *    (`ctx.tools.get(name, scope)`, read at every assembly), which is what
+ *    keeps git_bash and wsl_bash independently switchable: any subset — either
+ *    one, both, or neither — renders exactly one correct copy, and a
+ *    composition with neither renders nothing at all.
+ *  - dsh's own tool-pwsh description repeats some of this prose and is not ours
+ *    to edit. This section stays self-sufficient on purpose: our tools must
+ *    carry their full guidance whether or not pwsh is in the composition, so we
+ *    never read facts out of another row's description.
+ * @module dsh-win-multi-bash/tool-bash/shell-family
+ */
+
+/** The tool names this plugin contributes to the shell family. */
+export const SHELL_FAMILY_TOOL_NAMES = ['git_bash', 'wsl_bash'];
+
+/**
+ * The single prompt section carrying the family's shared guidance. Named for
+ * the plugin's tool family rather than for one tool, so neither git_bash nor
+ * wsl_bash owns it.
+ */
+export const SHELL_FAMILY_SECTION_NAME = 'tool:win-mb-bash';
+
+/** Fresh-shell fact plus the `workdir` rule that replaces a persistent `cd`. */
+const SHELL_CALL_SECTION = 'Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`.';
+
+/**
+ * Cross-call exit-status guidance. It belongs in the prompt rather than the
+ * tool schema because the trap is not about one call's arguments but about how
+ * a multi-step command is composed: `;` never stops on failure, and a pipeline
+ * reports only its last command's status — so the reflex of bounding long
+ * output with `| tail`, which this runtime already truncates for the caller,
+ * returns `tail`'s status instead of the command's.
+ */
+export const SHELL_EXIT_STATUS_SECTION = 'Check the [exit code: N] marker on every bash result; investigate failures before moving on. Chain dependent steps with `&&` or `set -o pipefail`: `;` never stops on failure, and `cmd | tail` returns the status of `tail`, not of `cmd`.';
+
+/** Managed `$DSH_*` environment facts are the same for every shell tool. */
+const SHELL_HARNESS_FACTS_SECTION = 'Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed.';
+
+/** The confinement marker one shared classifier produces for every dialect. */
+const SHELL_SANDBOX_SECTION = 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way.';
+
+/** Retention contract: the runtime truncates, so no call needs to bound output itself. */
+const SHELL_OUTPUT_SECTION = 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available.';
+
+/** Path-safety rules shared by every dialect (MSYS, Linux, and pwsh alike). */
+const SHELL_PATH_SAFETY_SECTION = 'Before any delete or move, verify that the resolved absolute target path is the intended one; never run it against a computed path you have not checked. An unset variable expands to an empty string, so guard variables in such paths with `${VAR:?}`.';
+
+/** Advertised only while some mounted family tool offers `run_in_background`. */
+export const SHELL_BACKGROUND_SECTION = '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`.';
+
+/**
+ * The same-turn escalation guidance appended after a denial marker. Kept in one
+ * place because every dialect shares the exact approval contract, and included
+ * only while some mounted family tool advertises `sandbox_permissions`. The
+ * opening clause names that dependency because the section speaks for the whole
+ * family: a tool that advertises no such parameter has nothing to escalate
+ * with, and its own schema is what says so.
+ */
+export const SHELL_ESCALATION_SECTION = 'Where a shell tool advertises `sandbox_permissions`: attempting a command the sandbox may deny is safe and expected — run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.';
+
+/**
+ * Compose the family section from the facts that hold for the mounted set.
+ * @param advertised - what the mounted family tools advertise this composition.
+ * @param advertised.background - some mounted family tool offers `run_in_background`.
+ * @param advertised.escalation - some mounted family tool offers `sandbox_permissions`.
+ * @returns the section text, with no fact stated twice.
+ */
+export function shellFamilySectionText({ background, escalation }) {
+    return [
+        SHELL_CALL_SECTION,
+        SHELL_EXIT_STATUS_SECTION,
+        SHELL_HARNESS_FACTS_SECTION,
+        SHELL_SANDBOX_SECTION,
+        SHELL_OUTPUT_SECTION,
+        SHELL_PATH_SAFETY_SECTION,
+        ...background ? [SHELL_BACKGROUND_SECTION] : [],
+        ...escalation ? [SHELL_ESCALATION_SECTION] : [],
+    ].join(' ');
+}
+
+/**
+ * The Loader specifier of the row that owns the family section. After the row
+ * merge that is the package row itself — the row whose `name` is the bare
+ * package specifier, which is also the row the Web client needs in order to
+ * find `dsh.client` and serve the browser half. Exported so the tool rows can
+ * tell whether that owner is composed: the section is the only carrier of the
+ * shared guidance, and the tool descriptions were slimmed on that assumption,
+ * so their absence has to be detected rather than assumed away.
+ */
+export const SHELL_FAMILY_ROW_SPECIFIER = 'dsh-win-multi-bash';
+
+/**
+ * Whether the row that owns the shared shell prompt section is composed and
+ * enabled. The tool descriptions carry only their dialect facts on the
+ * assumption that section states the rest, so this is worth knowing: without
+ * that row the shared guidance would silently vanish from the prompt.
+ *
+ * The Loader tree lists declared rows with their effective enablement before
+ * they activate, so the answer does not depend on row order. A loader that
+ * cannot be read answers `undefined` (treat as composed) — the default
+ * composition has the row, and guessing the other way would duplicate prose.
+ * @param ctx - a context that can reach the Loader (a row's own context).
+ * @returns true/false when known, `undefined` when the loader is unreadable.
+ */
+export function familyRowComposed(ctx) {
+    const loader = ctx.get?.('loader') ?? ctx.loader;
+    if (loader === undefined || typeof loader.entries !== 'function') return undefined;
+    for (const entry of loader.entries()) {
+        if (entry.options?.name !== SHELL_FAMILY_ROW_SPECIFIER) continue;
+        return entry.disabled !== true;
+    }
+    return false;
+}
+
+/**
+ * The family section text for one assembly, resolved from the tools actually
+ * mounted: it states nothing about a tool that is not there (a tool that
+ * advertises no `sandbox_permissions` also gets no escalation paragraph), and
+ * with no family tool mounted it renders no text at all — the section is then
+ * empty and dropped from the rendered prompt.
+ * @param ctx - a context with the `tools` service.
+ * @param scope - the assembly scope `tools.get` takes.
+ * @returns the section text, or `''` when this composition mounts no family tool.
+ */
+export function shellFamilySectionTextFor(ctx, scope) {
+    const mounted = SHELL_FAMILY_TOOL_NAMES
+        .map((toolName) => ctx.tools.get(toolName, scope))
+        .filter((definition) => definition !== undefined);
+    if (mounted.length === 0) return '';
+    const advertises = (parameter) => mounted.some((definition) => definition.parameters?.properties?.[parameter] !== undefined);
+    return shellFamilySectionText({
+        background: advertises('run_in_background'),
+        escalation: advertises('sandbox_permissions'),
+    });
+}
+
+/**
+ * One tool's model-facing description. Normally that is only its dialect facts —
+ * the family section carries the rest once for the whole composition. When the
+ * owning row is **not** composed (a user switched it off, or wired a subset of
+ * the patch by hand), the shared text falls back into this description instead,
+ * so the model never silently loses the exit-marker, sandbox, truncation,
+ * path-safety, background and escalation guidance. The duplicated prose is the
+ * price of that fallback, and it only exists in a configuration that has no
+ * section at all.
+ * @param own - the dialect-owned description from {@link shellDescription}.
+ * @param familyPresent - whether the section's owning row is composed and enabled;
+ *   only a definite `false` falls back, because an unknown state must never
+ *   duplicate prose the section would also state.
+ * @param advertised - what this tool advertises, as {@link shellFamilySectionText} takes.
+ * @returns the description to register.
+ */
+export function composeToolDescription({ own, familyPresent, background, escalation }) {
+    if (familyPresent !== false) return own;
+    return `${own} ${shellFamilySectionText({ background, escalation })}`;
+}
+
+/**
+ * Midpoint of the two placements dsh centrally allocates to shell tools, so the
+ * family section sorts between `tool:bash` and `tool:pwsh` instead of ahead of
+ * every other section. Resolved from the registry rather than hardcoded; the
+ * literals below are only the fallback for a registry that stopped exposing
+ * both names (the midpoint of TOOL_BASH 1000 / TOOL_PWSH 1010 at the time of
+ * writing).
+ * @param systemPrompt - the prompt registry the section is registered on.
+ * @returns a finite order value strictly between TOOL_BASH and TOOL_PWSH.
+ */
+export function shellFamilySectionOrder(systemPrompt) {
+    const bash = systemPrompt.getSectionOrder('TOOL_BASH');
+    const pwsh = systemPrompt.getSectionOrder('TOOL_PWSH');
+    if (Number.isFinite(bash) && Number.isFinite(pwsh) && pwsh > bash)
+        return (bash + pwsh) / 2;
+    if (Number.isFinite(bash))
+        return bash + 1;
+    if (Number.isFinite(pwsh))
+        return pwsh - 1;
+    return 1005;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-win-multi-bash",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "author": "Dinosaur_MC",
   "repository": {
     "type": "git",
@@ -26,6 +26,7 @@
   "main": "lib/index.js",
   "exports": {
     ".": "./lib/index.js",
+    "./client": "./lib/client.js",
     "./tool-git-bash": "./lib/tool-bash/types/git-bash.js",
     "./tool-wsl-bash": "./lib/tool-bash/types/wsl-bash.js",
     "./package.json": "./package.json"
@@ -33,6 +34,8 @@
   "files": [
     "lib/**/*.js",
     "cordis.patch.yml",
+    "install.ps1",
+    "uninstall.ps1",
     "README.md",
     "README.zh.md",
     "README.i18n.yaml",
@@ -45,6 +48,15 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
+      ]
     }
   },
   "peerDependencies": {

package/uninstall.ps1

@@ -0,0 +1,50 @@
+<#
+.SYNOPSIS
+    热拔 dsh-win-multi-bash（自包含版）：从 profile 的 cordis.patch.yml 删除
+    managed 块，并移除 profile node_modules 里的插件 junction。
+    dsh web 会热重载，移除后新会话不再有 git_bash / wsl_bash 工具。
+
+.PARAMETER ProfileName
+    目标 profile 名，默认 web。
+#>
+[CmdletBinding()]
+param(
+    [string]$ProfileName = 'web'
+)
+
+$ErrorActionPreference = 'Stop'
+
+$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $env:USERPROFILE '.dsh' }
+$patchPath = Join-Path $dshHome "profiles\$ProfileName\cordis.patch.yml"
+$linkPath = Join-Path $dshHome "profiles\$ProfileName\node_modules\dsh-win-multi-bash"
+
+$utf8NoBom = [System.Text.UTF8Encoding]::new($false)
+$removed = $false
+
+if (Test-Path $patchPath) {
+    $existing = [System.IO.File]::ReadAllText($patchPath, $utf8NoBom)
+    $pattern = '(?s)# --- dsh-win-multi-bash managed.*?# --- end dsh-win-multi-bash managed ---\r?\n?'
+    $removed = $existing -match $pattern
+    if ($removed) {
+        [System.IO.File]::WriteAllText($patchPath, [regex]::Replace($existing, $pattern, ''), $utf8NoBom)
+        Write-Host "[dsh-win-multi-bash] 已从 $patchPath 移除 managed 块。热重载后新会话不再有 git_bash / wsl_bash 工具。"
+    } else {
+        Write-Host "[dsh-win-multi-bash] $patchPath 中没有 managed 块。"
+    }
+}
+
+if (Test-Path $linkPath) {
+    $item = Get-Item $linkPath -Force
+    if ($item.LinkType -eq 'Junction') {
+        # PS 5.1 的 Remove-Item 删 junction 会抛 NullReferenceException（已知 bug），
+        # 用 cmd rmdir（只删链接本身，绝不触碰链接目标）。
+        cmd /c rmdir "$linkPath"
+        Write-Host "[dsh-win-multi-bash] 已移除插件 junction: $linkPath"
+    } else {
+        Write-Host "[dsh-win-multi-bash] $linkPath 存在但不是 junction，未动（请手动处理）"
+    }
+}
+
+if (-not $removed -and -not (Test-Path $linkPath)) {
+    Write-Host "[dsh-win-multi-bash] 若你是用 bundle 路径安装的（dsh plugin add），请运行: dsh plugin --profile $ProfileName remove dsh-win-multi-bash"
+}