dsh-envsel
English | 中文
Session environment selector for DeepSeek Harness (DSH). Per-language slots — Python, R, CLI tools — each hold one first-priority environment drawn from conda, standalone R installs, WSL distributions, or user-pinned custom paths. Selections are per-session, persisted across restarts, and take effect for the model from the very next turn.
This is a standalone, npm-installable DSH plugin. It installs with dsh plugin add — no source patching, no monorepo checkout.
Features
/env command — read, assign, clear, and list environments from the chat.session_env model tool — the agent can list, select, pin, and unpin environments on its own.- Per-turn runtime-context block — the selection is restated in the model's runtime context on every turn, so the model reads which environment this session runs in instead of having to think to ask. A session with no selection of its own — a delegated subagent, for example — inherits the nearest selecting session it descends from.
- States the R that a conda env also carries — when the selected Python environment ships
Rscript of its own, the runtime block says so (- This environment also provides R: …). conda environments routinely carry R beside Python, and without that line the model only sees the R slot and can mix two different R installations. It is omitted when the same install fills both slots.
DSH_ENV_* shell facts — every shell call sees DSH_ENV_PYTHON, DSH_ENV_RSCRIPT, DSH_ENV_CLI_PREFIX for the session's selection.- Header dropdown — a per-language selector in the conversation header (Python / R / CLI tools), with an "Add path" form to pin any interpreter or install directory.
- Cross-platform discovery — conda environments, standalone R (Windows
Program Files, macOS framework + Homebrew, Linux /opt/R), WSL distributions on Windows, and manually pinned paths. WSL scanning is skipped automatically on non-Windows hosts.
- Bilingual UI — product copy (the
/env command, the header dropdown, and discovery warnings) follows the DSH interface language: English by default, Chinese when the DSH language preference is set to 中文.
Requirements
- DeepSeek Harness 0.1.7-rc.1 or newer (the web profile), which now includes the 0.2.0-rc line: every
@deepseek-ai/dsh-* peer is declared as ^0.1.7-rc.1 || ^0.2.0-rc.1. Verified on 0.1.7-rc.2; the range also admits 0.2.0-rc.1, 0.2.0-rc.2 and 0.2.1-alpha.2. DSH skips a plugin bundle whose @deepseek-ai/dsh* peer range excludes the running runtime, so that range — not a version probe — decides whether this plugin loads.
pnpm on PATH (used by dsh plugin).
DSH version compatibility
| Plugin | DeepSeek Harness | Why |
|---|
| 0.3.1 | 0.2.0-rc.1 or newer for the runtime-context block; still loads on 0.1.7-rc.1+ without it | Adds the "- This environment also provides R: …" line, so a selected conda Python environment that ships its own Rscript is reported instead of being invisible next to the R slot. Rendering only — no new DSH API. |
| 0.3.0 | 0.2.0-rc.1 or newer for the runtime-context block; still loads on 0.1.7-rc.1+ without it | Renders the selection into the per-turn runtime context and lets a session with no selection inherit the nearest selecting session it descends from, so delegated subagents keep their parent's environment. The block is contributed through systemPrompt.context(), whose text provider receives the assembling agent as AssembleContext.agent — a binding DSH gained in 0.2.0-rc.1. |
| 0.2.0 | 0.1.7-rc.1 or newer (0.1.7-rc and 0.2.0-rc lines) | Covers DSH 0.2.0-rc: every @deepseek-ai/dsh-* peer now also admits ^0.2.0-rc.1, so the startup compatibility gate no longer skips the bundle. The 18 peers were still pinned to ^0.1.7-rc.1, whose <0.2.0 upper bound rejects a 0.2.x runtime. |
| 0.1.6 | 0.1.7-rc.1 or newer | Fixes the header dropdown on 0.1.7: that release renamed the UI icon set (IconCheckOutline14 became IconCheckOutlineRegular), so 0.1.5's button rendered an undefined element and the slot entry crashed. |
| 0.1.5 | 0.1.7-rc.1 or newer | Emits strict Typert codecs with the create() factory that 0.1.7-rc.1 introduced. Host-side surfaces (/env, session_env, DSH_ENV_*) work; the header dropdown does not. |
| 0.1.3 and earlier (published) | 0.1.0-rc.7 through 0.1.5-rc.x | Emits the eager schema instance those loaders validate. |
DSH changed the strict-codec contract in 0.1.7-rc.1: dsh-typert-loader and dsh-typert-registry (host and browser side) require typeof codec.create === 'function' and no longer validate the eager schema field. A codec carrying only schema therefore fails to load on 0.1.7-rc.1 and newer, and a codec carrying only create() fails on 0.1.0-rc.x, so the two generations cannot share one artifact. This release targets the new contract only; on an older DSH, install the last release published for that line instead (the v0.1.4 tag was never published to npm):
dsh plugin --profile web add @beihaizb/dsh-envsel@0.1.3
Every generated codec here is emitted through strictCodec() (src/strict-codec.ts), which supplies that factory, so the wire contract has one place to change.
Installation
dsh plugin --profile web add @beihaizb/dsh-envsel
Restart dsh web, open an existing session, and the Env dropdown appears in the conversation header; /env and session_env work immediately.
Installing from a local checkout instead:
dsh plugin --profile web add "file:/absolute/path/to/this/repo"
Usage
/env command
/env show the current selection
/env python=mycondaenv set the Python slot (conda name / R name / wsl:distro:name / custom:name)
/env r=R-latest set the R slot
/env cli=base set the CLI slot (PATH prefix)
/env python= clear one slot
/env list [filter] list all discoverable environments
/env add <path> remember an interpreter or install directory on this machine
/env unpin custom:<name> forget a pinned path
/env clear clear every slot
/env wsl rescan WSL distributions (Windows only)
session_env tool
The model can manage selections itself with action=list|get|set|pin|unpin.
Header dropdown
The Env button in the conversation header opens per-language dropdowns. The catalog is scanned lazily on first open (probing conda and WSL takes a few seconds). "Add path" pins any absolute interpreter or install path into the machine-local cache.
Configuration
The plugin works with no configuration. Optional config on the envsel row in your profile's cordis.patch.yml:
| Key | Default | Meaning |
|---|
listTtlMs | 300000 | Catalog cache TTL in milliseconds. |
condaCommand | conda | Conda executable name or absolute path. |
standaloneRRoots | [] | Extra standalone-R roots scanned after the platform defaults. |
wslEnabled | true | Whether WSL discovery is enabled (Windows only). |
registerTool | true | Whether the session_env model tool is registered. |
registerContext | true | Whether the selection is contributed to the per-turn runtime context (needs DSH 0.2.0-rc.1 or newer; a host without the binding renders nothing). |
probeTimeoutMs | 20000 | Per-probe watchdog timeout in milliseconds. |
Example:
# in your profile's cordis.patch.yml, after the bundle layer
- id: envsel
name: '@beihaizb/dsh-envsel'
config:
wslEnabled: false
registerTool: true
How it stores selections
Selections persist in a machine-local JSON store ($DSH_HOME/envsel-state.json, keyed by session id) — not in the session event log. The harness's session-persistence reader refuses a log containing an event type it does not know unless the event is marked ignorable, and Session.append provides no way for a downstream plugin to set that marker. Writing selection changes into the log would make the owning session unreadable after a restart, so this plugin owns its own durable state instead.
A lookup uses the session's own entry when it has one, and otherwise walks the delegating-session chain (SessionHeader.parentSession) for the nearest session that selected anything. DSH gives every delegated subagent its own session, so this is what keeps a subagent's shell calls and notebook kernels on the environment the delegating session chose rather than the host default. The walk is bounded, skips the whole chain when nothing matches, and terminates on a lineage cycle.
Development
pnpm install
pnpm run build # tsc (types) + tsdown (lib/index.js host + lib/client.js browser bundle)
pnpm run test # node:test unit tests
The build produces two artifacts: lib/index.js (the host plugin, loaded from the package root) and lib/client.js (the browser bundle, served by the client-modules scanner from the package's dsh.client declaration). A single package can be both a host row and a client row.
Known limitations
- The runtime-context block needs DSH 0.2.0-rc.1 or newer. It is contributed through
systemPrompt.context(), and the text provider is handed the assembling agent as AssembleContext.agent — a binding DSH added in 0.2.0-rc.1. On 0.1.7-rc the block renders nothing and the selection reaches the model only as DSH_ENV_* shell facts plus /env and session_env; nothing else changes. Set registerContext: false to turn the block off on any host.
- Peer-bound to the 0.1.7-rc and 0.2.0-rc lines. The plugin declares every
@deepseek-ai/dsh-* peer as ^0.1.7-rc.1 || ^0.2.0-rc.1 and is verified up to 0.1.7-rc.2; the 0.2.0-rc line is covered by that range. On DSH 0.1.0-rc.7 through 0.1.5-rc.x install @beihaizb/dsh-envsel@0.1.3 (the last release published for that line) instead; a future DSH release that changes these APIs — or the Typert artifact contract again — needs a matching plugin update. On a line the peer range does not admit, grant an exact-version exemption (dsh plugin allow-version, or the plugin manager) rather than forcing the install.
- Selections are not part of the session log. They survive restarts in
envsel-state.json but are not replayed from (or carried by) session logs.
License
MIT
