dsh-wsl-tool 1.8.0 → 1.8.2

package/PUBLISHING.md

@@ -0,0 +1,161 @@
+# Publishing
+
+Maintainer notes for releasing this plugin. Four channels carry the same commit
+and they are not interchangeable.
+
+| Channel | What it is | What ships it |
+|---|---|---|
+| GitHub Release asset | what the plugin market installs from | `.github/workflows/release.yml`, on a `v*` tag |
+| npm | the package `dsh-wsl-tool` | the same workflow, as its last step |
+| Catalog entry | the listing line and the install command the market shows | a PR to `awesome-dsh-plugin/awesome-dsh-plugin` |
+| Your working profile | the copy DSH actually loads | `npm run sync`, then a DSH restart |
+
+## The name split is deliberate
+
+The npm package is **`dsh-wsl-tool`**, not `dsh-wsl`. The registry answers
+
+```
+403 Forbidden - PUT https://registry.npmjs.org/dsh-wsl -
+Package name too similar to existing package is-wsl
+```
+
+for the repository name. A name policy is not a permission problem: no token, no
+2FA bypass, and no scope changes it, and the name stays unclaimable. The
+repository, the plugin (`tool-wsl`), and the market listing keep the `dsh-wsl`
+name.
+
+Nothing else depends on that name, because `cordis.patch.yml` names its entry by
+**relative path**:
+
+```yaml
+- insert:
+    - id: tool-wsl
+      name: './index.js'
+```
+
+DSH anchors a relative `name:` beside the patch file that declared it
+(`anchorInsertedPluginNames` in `@deepseek-ai/dsh-app-boot`), so this row loads
+this bundle's own `index.js` whatever the install folder is called —
+`node_modules/dsh-wsl-tool` from npm, `node_modules/dsh-wsl` in a local `file:`
+profile. A bare package name would resolve in only one of those layouts, and
+would silently couple this file to the registry name. `test/smoke.mjs` asserts
+both that the entry stays relative and that it resolves.
+
+## Release checklist
+
+1. Green locally:
+
+   ```sh
+   npm test                                           # shim backend, real WSL
+   DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
+   ```
+
+2. Bump, sync, commit, tag, push:
+
+   ```sh
+   npm version <x.y.z> --no-git-tag-version
+   npm run sync                 # into the profile copy DSH loads
+   git add -A && git commit -m "..."
+   git tag -a v<x.y.z> -m "..."
+   git push origin main && git push origin v<x.y.z>
+   ```
+
+   `npm run sync` defaults to
+   `%USERPROFILE%/.dsh/profiles/web/node_modules/dsh-wsl` — the folder the
+   profile's dependency key created, which need not match the npm name. Pass a
+   path to target another profile. Restart DSH afterwards: the plugin is imported
+   once at load.
+
+3. The tag runs the pipeline. The order is deliberate — the release asset goes
+   **first** because it is the market's critical path, then npm, so a failing npm
+   publish fails the run loudly without withholding the release.
+
+   The build step asks `npm pack --silent` for the tarball name (it follows
+   `package.json`, so it is `dsh-wsl-tool-<version>.tgz`) and copies it to
+   `dsh-wsl.tgz`, which is the fixed name the catalog's URL points at. Never
+   rename that copy: the market install breaks the moment the asset is not called
+   `dsh-wsl.tgz`, and `--latest` is what keeps `releases/latest` resolving to it.
+
+4. Verify each channel.
+
+   **CI** — a check annotation is readable anonymously, unlike the job log:
+
+   ```sh
+   curl -s "https://api.github.com/repos/XINY11451/dsh-wsl/actions/runs?per_page=5"
+   curl -s "https://api.github.com/repos/XINY11451/dsh-wsl/check-runs/<id>/annotations"
+   ```
+
+   A successful publish leaves `published <version> to npm`; a failure leaves
+   `npm publish failed: <the npm error lines>`, which is why the workflow turns
+   npm's stderr into `::error::` instead of only printing it.
+
+   **npm**:
+
+   ```sh
+   curl -s https://registry.npmjs.org/dsh-wsl-tool      # dist-tags.latest
+   npm view dsh-wsl-tool version --registry https://registry.npmjs.org
+   ```
+
+   Fetching `dist.tarball` and unpacking it is the honest check — it proves the
+   artifact, not just the metadata. Scripted requests to `npmjs.com`'s HTML hit a
+   Cloudflare challenge; the registry API is the source of truth.
+
+   **Market asset** (this is what users install, and it is independent of npm):
+
+   ```sh
+   curl -sL -o /tmp/a.tgz https://github.com/XINY11451/dsh-wsl/releases/latest/download/dsh-wsl.tgz
+   tar -xzOf /tmp/a.tgz package/package.json | grep '"version"'
+   ```
+
+   **Catalog**: the catalog's generated data is at
+   <https://awesome-dsh-plugin.com/plugins.json> — look up `dsh-wsl` and read
+   `npm`, `version`, `downloads`, `install`, `tarball`.
+
+## The catalog entry
+
+The listing lives at `data/plugins/XINY11451__dsh-wsl.yml` in
+`awesome-dsh-plugin/awesome-dsh-plugin`, one file per plugin. Only
+`description.en` is required; `description.zh` is optional. Edit it through a
+one-file PR (the web UI's pencil button forks and proposes the change).
+
+Two of its keys are hand-written and must stay:
+
+- `tarball:` — the fixed release URL above. It is what the market's `install`
+  command points at today.
+- `url` / `name` / `category` — `category: wsl`.
+
+Everything else about the entry is **generated** and must never be written by
+hand: `npm`, `version`, `downloads`, `screenshots`, and `install`. In particular
+`scripts/probe-npm.mjs` reads `package.json`'s `name` from the repository's
+`HEAD`, then accepts the package only when the registry document's
+`versions[latest].repository.url` contains `<owner>/<repo>`
+(case-insensitively — that check is what stops name squatting). So keep
+`repository` in `package.json` accurate, or the catalog stops discovering the npm
+package. "Not published" verdicts are re-probed daily, so a freshly published
+version can take a day to appear; when it does, `install` switches from the
+tarball URL to `dsh plugin --profile web add dsh-wsl-tool`.
+
+## Things that bite
+
+- **A tag event runs the workflow from the tag's commit.** To change the
+  pipeline you must commit *and cut a new tag*; re-running an old run reuses the
+  workflow it was created with, and moving a tag is not a fix.
+- **Job logs need authentication; annotations do not.** There is no `gh` and no
+  `GITHUB_TOKEN` on the maintainer machine, so anything that must be diagnosable
+  without a credential belongs in an annotation.
+- **An interactive `npm publish` asks for a one-time password** and cannot be
+  driven from an unattended run. CI authenticates with a granular token that may
+  bypass 2FA, stored as the `NPM_TOKEN` secret; with the secret absent the step
+  skips with a notice instead of failing. Now that the package exists, OIDC
+  trusted publishing is the better replacement.
+- **`publishConfig.registry` in `package.json` wins** over a developer's
+  `~/.npmrc` mirror, so a mirror configured for reads cannot intercept a publish.
+- **The profile's dependency key is not the package name** (`dsh-wsl` versus
+  `dsh-wsl-tool`). Do not "fix" that by hand: the profile is managed by pnpm, and
+  its `pnpm-lock.yaml`, `node_modules/.modules.yaml`, and
+  `node_modules/.package-map.json` all record the key. The relative patch entry
+  means the difference costs nothing.
+- **Short unscoped names ending in `-wsl` are a minefield.** `dsh-wsl` collides
+  with `is-wsl`; longer suffixed names such as `dsh-wsl-workspace` are published
+  by other authors and pass. Prefer npm's suggestion (a scope) or a clearly
+  suffixed name, and check the registry before tagging.

package/README.md

@@ -2,7 +2,18 @@
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
-A model-facing **WSL** tool plugin for DeepSeek Harness (DSH). It lets an agent run Linux commands through `wsl.exe` directly — no hand-written `.sh` scripts or `pwsh` wrappers.
+A model-facing **WSL** tool plugin for DeepSeek Harness (DSH). It lets an agent run
+Linux commands through `wsl.exe` directly — no hand-written `.sh` scripts or `pwsh`
+wrappers — and for command execution it essentially matches a native Linux DSH: a
+real Linux kernel and bash, exit codes and signals, timeouts, truncation with spill
+files, background jobs the built-in job tools read back, stdin, and automatic
+Windows/WSL path translation.
+
+Two limits are worth knowing before you rely on it. A `wsl` call runs below DSH's
+sandbox, so a file policy does not confine it (see [Sandboxing](#sandboxing)); and a
+project kept on a Windows drive keeps **Windows** filesystem semantics — no POSIX
+permissions, case-insensitive names, no file-change notifications — at a fraction
+of the speed (see [Notes](#notes)).
 
 ## Tools
 
@@ -96,18 +107,33 @@ specifier you install under.
    or `dsh plugin add --profile <profile> file:<path-to-this-repo>` from a
    checkout (which names the dependency after this package).
 
-2. Add a `tool-wsl` row to an agent preset's `agent.cordis.yml`:
+2. Nothing else. The package's `cordis.patch.yml` inserts the `tool-wsl` row
+   itself when the bundle is loaded, process-wide, so the three tools are
+   available to every agent preset without further wiring.
 
-   ```yaml
-   - id: tool-wsl
-     name: 'dsh-wsl-tool'
-   ```
-
-   `name` is the installed package name — use your own dependency key if you
-   installed under a different one.
+   Do **not** also list `tool-wsl` in a preset: DSH registers tools by name, and
+   the second registration fails with
+   `tool "wsl" is already registered in this scope`. One row, from the bundle.
 
 3. Restart DSH.
 
+## Compatibility
+
+Verified against DSH **0.1.7-rc.2** (and 0.1.5-rc.2 before it): the tool schemas
+pass DSH's own `assertSupportedJsonSchema`, the subprocess seam is exercised
+against the real provider rather than a shim, and the background-job path is
+checked against the real job registry, including the session-id ownership fence
+that 0.1.7 tightened. `test/real-seam.mjs` is that check and it re-verifies a host
+in about a minute, so point it at any DSH installation after an upgrade:
+
+```sh
+DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
+```
+
+A background job is owned by the calling session (`owner: exec.agent.id`), which
+is what lets the model read it back with `job_output`/`job_kill` and what keeps
+other sessions out; an execution with no agent starts the job unowned.
+
 ## `wsl` parameters
 
 | Param | Required | Type | Notes |
@@ -169,7 +195,21 @@ takes effect on restart.
   workspace: /mnt/d/DSHworkarea (Windows drive mount /mnt/d — builds, installs and git are much slower here; prefer a path under /home when it matters)
   ```
 
-  It is worth believing. Measured on the author's machine: a 128 MB sequential write ran at ~2.1 GB/s on ext4 against ~247 MB/s on `/mnt/d`, and creating 400 small files took under 10 ms against 0.72 s.
+  It is worth believing. Measured on the author's machine: a 128 MB sequential write
+  ran at ~2.1 GB/s on ext4 against ~247 MB/s on `/mnt/d`, and creating 400 small
+  files took under 10 ms against 0.72 s (a later re-run: 884 vs 116 MB/s, and 13 ms
+  against 745 ms — the ratios hold at roughly 8× and 50×).
+
+  It is not only slower. `/mnt/<drive>` is a 9p (drvfs) mount, so it keeps **Windows**
+  filesystem semantics: `chmod`/`chown` do not stick (a `chmod 600` reads back as
+  `777`), names are case-insensitive (so a case-sensitive import only fails on Linux
+  CI), symlinks and the executable bit are synthetic, and **inotify does not work at
+  all** — a watcher inside the distro receives no events for writes from either side
+  (measured with an inotify probe on `/mnt/d`: zero events for a Windows-side write
+  and for a Linux-side write, while the same probe on ext4 reported create, modify
+  and close-write). Dev servers, `--watch` modes and file-watching tests are
+  therefore blind on a Windows drive. Keep a project under `/home` when it matters:
+  it recovers real semantics, real watch events, and the speed above.
 - Destructive commands are refused unless the call passes `allowDangerous: true`:
   - **any recursive delete** — `rm -r`, `rm -rf`, `rm -r -f`, `rm -R --force`, `rm --recursive` — because with stdin on `/dev/null` nothing prompts, so `rm -r tree` deletes silently. Each `rm` invocation is judged on its own command segment, so `rm a -f; rm b -r` cannot combine into a pass;
   - `dd` onto a block device, `mkfs`, partitioning/wiping tools (`fdisk`, `parted`, `wipefs`, `mkswap`, …), power control (`shutdown`, `reboot`, `systemctl reboot`, …), redirection onto a block device, and fork bombs;
@@ -312,6 +352,9 @@ the folder name itself never matters.
 
 then restart DSH — the plugin is imported once at load.
 
+Releasing — the tag-triggered workflow, the npm name, and the catalog entry — is
+documented in [`PUBLISHING.md`](PUBLISHING.md).
+
 ## Listing
 
 The repository carries the `dsh-plugin` topic and is listed under the `wsl`

package/README.zh-CN.md

@@ -2,7 +2,14 @@
 
 [English](README.md) | 简体中文
 
-面向模型（model-facing）的 **WSL** 工具插件，用于 DeepSeek Harness（DSH）。它让智能体直接通过 `wsl.exe` 执行 Linux 命令——无需手写 `.sh` 脚本或 `pwsh` 包装。
+面向模型（model-facing）的 **WSL** 工具插件，用于 DeepSeek Harness（DSH）。它让智能体直接通过
+`wsl.exe` 执行 Linux 命令——无需手写 `.sh` 脚本或 `pwsh` 包装——并且在**命令执行**这一层基本对齐
+Linux 原生 DSH：真实的 Linux 内核与 bash、退出码与信号、超时、截断与落盘、可用内置 job 工具读回的
+后台作业、stdin，以及 Windows/WSL 路径自动转换。
+
+有两点限制值得在依赖它之前知道：`wsl` 调用位于 DSH 沙箱层之下，文件策略约束不到它
+（见[沙箱边界](#沙箱边界)）；项目放在 Windows 盘上时仍是 **Windows** 的文件系统语义——没有 POSIX
+权限位、文件名大小写不敏感、收不到文件变更通知——速度也低一个数量级（见[注意事项](#注意事项)）。
 
 ## 工具
 
@@ -86,17 +93,29 @@ launcher: WSL 版本: 2.6.3.0 · 内核版本: 6.6.87.2-1 · WSLg 版本: 1.0.71
    `dsh plugin add --profile <profile> file:<path-to-this-repo>` 从本地检出安装
    （依赖名会取本包自身的名字）。
 
-2. 在某个 agent preset 的 `agent.cordis.yml` 中加入 `tool-wsl` 行：
-
-   ```yaml
-   - id: tool-wsl
-     name: 'dsh-wsl-tool'
-   ```
+2. 不必再做别的。本包的 `cordis.patch.yml` 会在组合包加载时**自己插入** `tool-wsl` 行
+   （进程级），因此三个工具对所有 agent preset 都可用，无需额外接线。
 
-   `name` 即安装后的包名；若你用了别的依赖名，就填那个名字。
+   **不要**再在 preset 里列一遍 `tool-wsl`：DSH 按名字注册工具，第二次注册会直接失败
+   —— `tool "wsl" is already registered in this scope`。这一行只由组合包提供。
 
 3. 重启 DSH。
 
+## 兼容性
+
+已在 DSH **0.1.7-rc.2** 上验证（此前为 0.1.5-rc.2）：工具 schema 通过 DSH 自己的
+`assertSupportedJsonSchema`；subprocess 接缝是跑在**真实 provider** 上而非替身；后台任务
+路径跑在**真实 job 注册表**上，包含 0.1.7 收紧的「会话 id 属主围栏」。这套检查就是
+`test/real-seam.mjs`，约一分钟即可重验一个新宿主——升级后把它指向新的 DSH 安装即可：
+
+```sh
+DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
+```
+
+后台任务由**调用方会话**持有（`owner: exec.agent.id`），这既是模型能用
+`job_output`/`job_kill` 读回它的依据，也是其他会话读不到它的围栏；exec 里没有 agent 时
+任务则是无主的。
+
 ## `wsl` 参数
 
 | 参数 | 必填 | 类型 | 说明 |
@@ -174,8 +193,17 @@ launcher: WSL 版本: 2.6.3.0 · 内核版本: 6.6.87.2-1 · WSLg 版本: 1.0.71
   workspace: /mnt/d/DSHworkarea (Windows drive mount /mnt/d — builds, installs and git are much slower here; prefer a path under /home when it matters)
   ```
 
-  这个提示值得当真。作者机器实测：128 MB 顺序写在 ext4 上约 **2.1 GB/s**，在 `/mnt/d` 上约 **247 MB/s**；
-  创建 400 个小文件 ext4 **不到 10 ms**，`/mnt/d` 要 **0.72 s**。
+  这个提示值得当真。作者机器实测：128 MB 顺序写在 ext4 上约 **2.1 GB/s**，在 `/mnt/d` 上约
+  **247 MB/s**；创建 400 个小文件 ext4 **不到 10 ms**，`/mnt/d` 要 **0.72 s**
+  （后来复测：**884 vs 116 MB/s**、**13 ms vs 745 ms**，比值稳定在约 8× 与 50×）。
+
+  不只是慢。`/mnt/<盘>` 是 9p（drvfs）挂载，保留的是 **Windows** 的文件系统语义：
+  `chmod`/`chown` 不生效（`chmod 600` 读回来是 `777`）、文件名**大小写不敏感**（大小写写错只在
+  Linux CI 上才炸）、符号链接与可执行位是合成的，而且 **inotify 完全不工作**——发行版里的 watcher
+  对两侧写入都收不到任何事件（用 inotify 探针实测：`/mnt/d` 上 Windows 侧写入与 Linux 侧写入均为
+  **0 事件**，而同一探针在 ext4 上正常报出创建/修改/关闭写入）。因此 dev server、`--watch` 模式
+  与文件监听的测试在 Windows 盘上都是瞎的。需要时把项目放到 `/home` 下：语义、监听事件与上面那档
+  速度一次性都回来。
 - 危险命令默认被拒绝，除非调用时传 `allowDangerous: true`：
   - **任何递归删除**——`rm -r`、`rm -rf`、`rm -r -f`、`rm -R --force`、`rm --recursive`——
     因为 stdin 指向 `/dev/null` 时不会产生任何提示，`rm -r tree` 会静默删除整棵树。
@@ -299,6 +327,8 @@ npm run sync -- /path/to/profiles/<profile>/node_modules/<你的依赖名>
 
 然后重启 DSH——插件在加载时只导入一次。
 
+发版流程（tag 触发的流水线、npm 包名与目录条目）见 [`PUBLISHING.md`](PUBLISHING.md)。
+
 ## 收录
 
 本仓库带有 `dsh-plugin` topic，并已提交至 awesome-dsh-plugin 社区列表的 `wsl` 分类。

package/cordis.patch.yml

@@ -1,5 +1,11 @@
-# This bundle layer registers the wsl tool plugin in an agent preset.
-# Presets can also add the row manually instead of relying on this patch.
+# This bundle layer inserts the wsl tool plugin process-wide, so every agent
+# preset gets the `wsl`/`wsl-path`/`wsl-env` tools without declaring anything.
+#
+# Do NOT also add a `tool-wsl` row to a preset. DSH registers tools by name and
+# the second registration fails with
+# `tool "wsl" is already registered in this scope`. To keep the tools out of a
+# composition, override this row by id in a later patch layer (`- id: tool-wsl`
+# with `disabled: true`) instead of duplicating it.
 
 # The entry name is PATH-RELATIVE on purpose. DSH anchors a relative `name:` to
 # the directory of the patch file that declared it (`anchorInsertedPluginNames`),

package/lib/tools/wsl.js

@@ -71,7 +71,15 @@ export function createWslTool({ ctx, config, runner }) {
         kind: 'wsl',
         label: jobLabel(command),
         outputLimitBytes: config.maxOutputBytes,
-        ...(exec?.agent === undefined ? {} : { owner: exec.agent }),
+        // `owner` is the owner's SESSION ID, not the Agent handle: the registry
+        // resolves it through the live-agent registry (`agents.get(sessionId)`)
+        // and fails with `session "…" has no live agent` for anything else. It
+        // is also the fence key — the model's `job_output`/`job_kill` reach this
+        // job by passing the same session id as their caller. Bound to
+        // `exec.agent.id` exactly as `dsh-tool-bash` and `dsh-tool-pwsh` do.
+        // An execution with no agent starts an unowned job, which is open to any
+        // caller but never listed for a session.
+        ...(exec?.agent === undefined ? {} : { owner: exec.agent.id }),
         // The spawn happens INSIDE run(): the contract says a throw leaves
         // nothing registered, so spawning first and registering second could
         // leak a process if registration failed.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-wsl-tool",
-  "version": "1.8.0",
-  "description": "Model-facing WSL tools for DeepSeek Harness: run Linux commands from Windows with background jobs, stdin, path translation, destructive-command guard and WSL capability diagnostics.",
+  "version": "1.8.2",
+  "description": "Run Linux commands from Windows through WSL, essentially matching a native Linux DSH for command execution: background jobs, stdin, path translation, a destructive-command guard and a WSL capability report. WSL calls run below the DSH sandbox, and a project on a Windows drive keeps Windows filesystem semantics.",
   "type": "module",
   "main": "index.js",
   "license": "MIT",
@@ -29,6 +29,7 @@
     "cordis.patch.yml",
     "README.md",
     "README.zh-CN.md",
+    "PUBLISHING.md",
     "screenshots.json",
     "assets",
     "LICENSE"