@local/dsh-shell-boot-timeout
小型单文件 DSH 插件：为首次 shell-tool 调用设置超时限制，使永远无法进入就绪状态的持久 shell 以一条可操作的错误信息失败，而不是持续等待。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:dongkid/dsh-shell-boot-timeout#9c7005cdd95ac5b53f00fc498a96a649de480286Shell Boot Timeout 以 @local/dsh-shell-boot-timeout 发布，当前版本为 1.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
点击下方 Badge 复制 Markdown，粘贴到 README 即可。
验证 package.json 声明的 GitHub 仓库，即可管理这个公开页面。认领后，Hub 会优先安排当前版本的安全扫描，并在通过后公开展示结果。
认领这个 Plugin →English | 中文
A small, single-file DeepSeek Harness plugin.
It adds one tools/execute listener that bounds the first shell-tool call, so a
persistent shell which never finishes starting reports one clear error instead of
spinning silently until the backend's own deadline.
It is deliberately tiny: zero dependencies, one file, one inserted row in the profile patch. It patches no shipped package and changes no preset.
Read this before installing. This is a workaround pinned to specific upstream behaviour, so the version matters.
| Version | |
|---|---|
| Verified against | @deepseek-ai/dsh 0.2.0-rc.2 |
Declared range (package.json → dsh.supported) | >=0.2.0-rc.2 <0.3.0 |
| Platform verified | Windows only |
| Not tested | 0.1.x, 0.3.x, macOS, Linux |
The declared range is an expectation, not a guarantee: the behaviour it depends on was
only reproduced on 0.2.0-rc.2. The version guard is soft — on an unverified
version the plugin logs a warning and keeps working, rather than failing your profile.
What it depends on, and therefore what an upstream change could break:
tools/execute waterfall (mode, ordering, signal-replacement rules);defineTool normalizing parameters into a JSON Schema with properties;If a future release changes any of those, the plugin degrades to not bounding — its
handshake check returns false rather than inventing a new failure in a mode that
works.
In Minimal mode, the shell tool is @deepseek-ai/dsh-tool-pwsh-persistent, which
runs commands over a persistent PTY session. Its first call must spawn the shell
and wait for readiness.
dsh-terminal-bash installs a PowerShell prompt function that emits an OSC 133;D;
marker, and accepts only waitReason === 'stdin_read' as proof the shell is up:
"function prompt { [Console]::Write([char]27 + ']133;D;' + [int]$LASTEXITCODE + [char]7); 'dsh> ' }"
On Windows, under the ACL sandbox's read-only mode, pwsh starts in
ConstrainedLanguage (its AppLocker temp probe cannot write). There
[Console]::Write fails with:
InvalidOperation: Cannot create type. Only core types are supported in this language mode.
So the marker is never emitted. Because the Windows process inspector reports
isStdinWaiting() === false, the marker is the only route to stdin_read; the
startup loop ignores the inferred_idle fallback and re-sends forever. Nothing is ever
executed, so nothing can fail — the call just hangs.
Required combination: Minimal mode + read-only sandbox. Other modes use the
one-shot pwsh tool, which needs no boot handshake and works under every mode.
Does: turn that silent stall into a fast, structured error:
Error: the shell behind the `pwsh` tool never reported readiness within 20000ms, so no
command was run. ... Switch the permission preset to `workspace-write` ...
It aborts the call first, which unblocks the pending PTY spawn, so the abandoned call stops instead of running to the backend deadline.
Does not: make pwsh work in Minimal + read-only. The stall is an upstream
bootstrap bug that a profile plugin cannot fix; this only makes the failure fast and
self-explanatory.
Bounding must not apply to Standard / PTC / Creator mode, where the tool is the
one-shot pwsh and the first call is already a real command (npm install, a test
suite) that may legitimately outlast any fixed budget. The two tools are told apart by
their declared parameters:
| Tool | Mode | Declares | Bounded? |
|---|---|---|---|
@deepseek-ai/dsh-tool-pwsh | standard, ptc, cordis | command, description, timeoutMs, workdir | no |
@deepseek-ai/dsh-tool-pwsh-persistent | minimal | command only | yes |
A tool that accepts its own per-command timeoutMs runs a real command immediately, so
it is already bounded by the caller and is left alone. An unreadable or unrecognized
schema also returns "not bounded".
A bounded call that fails does not mark the shell booted, so a retry is bounded again instead of silently reverting to the 300s stall. After a genuine successful boot the bound is dropped for that Agent, so long-running commands keep their configured budget.
This plugin is a DSH bundle: a package whose package.json declares
dsh.bundle.patch. Install it with the plugin manager (install_bundle, given this
directory), which performs package installation and bundle selection itself.
Package vs repository name. The package is named
@local/dsh-shell-boot-timeout; the repository is named for the patch row id (shell-boot-timeout). The package isprivate: trueand never published to npm —@local/is just a convention for local-only bundles, so the name only matters for DSH's module resolution.
pnpm ≥ 10 is required. DSH's profile scaffold reads pnpm settings from
pnpm-workspace.yaml, which only pnpm ≥ 10 does; pnpm 9 fails withERR_PNPM_ADDING_TO_ROOT. This is an environment requirement, not specific to this plugin.
Editing the module file requires a host restart to take effect: Node's ESM loader caches the imported module, so toggling the row off and on re-uses the old code.
| Field | Default | Meaning |
|---|---|---|
bootTimeoutMs | 20000 | Budget for the first shell-tool call. Raise on a very slow host. |
toolNames | ['pwsh', 'bash'] | Tool names eligible to be bounded; the handshake check still applies. |
verifiedDshVersion | 0.2.0-rc.2 | Verified floor; drift below it logs a warning only. |
Invalid configuration throws at activation (a non-positive bootTimeoutMs, or an empty
toolNames).
Both suites run on plain Node — no DSH boot, no network:
node tests/offline.test.mjs # 12 cases: timeout, pass-through, retry safety, config
node tests/discriminator.test.mjs # 7 cases: the real shipped tool declarations
discriminator.test.mjs reads the parameter names out of the shipped tools' own source
and normalizes them with DSH's own parameterSchemaSpecToJsonSchema, so the
"bounded?" decision is proven against the real declarations rather than hand-written
fakes. It needs an installed @deepseek-ai/dsh to read those files from.
plugins
list — that list is config data of the preset-<id> row, not a Loader group. A
patch targeting persistent-shell reports patch insert: entry "persistent-shell" not found. Targeting preset-minimal instead would mean restating the entire
shipped preset on every upgrade.terminals injection. Minimal mode's terminals provider lives inside the
preset's isolate: terminals: true realm, which a host-plane row cannot reach. The
tools/execute waterfall is the public seam that sees every preset.tools), no new
tool, no prompt change, no change to any mode that already works.MIT