dsh-as-mcp 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The dsh-as-mcp Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,621 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="icon.svg" width="96" alt="dsh-as-mcp">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">dsh-as-mcp</h1>
+
+<p align="center">English | <a href="README.zh.md">中文</a></p>
+
+<p align="center">
+  <a href="https://github.com/xiseliuli/dsh-as-mcp/actions/workflows/ci.yml"><img src="https://github.com/xiseliuli/dsh-as-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/xiseliuli/dsh-as-mcp/releases"><img src="https://img.shields.io/github/v/release/xiseliuli/dsh-as-mcp?label=release&color=2f81f7" alt="Release"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/xiseliuli/dsh-as-mcp?color=3fb950" alt="License: MIT"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%5E22.19.0%20%7C%7C%20%3E%3D24-339933?logo=nodedotjs&logoColor=white" alt="Node"></a>
+  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-server-8B5CF6" alt="MCP server"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-plugin-4B8BBE" alt="DSH plugin"></a>
+</p>
+
+Expose a running **DeepSeek Harness** as an **MCP server**, so any other agent — Claude
+Code, Codex, another DSH, a CI job, your own script — can drive it: create workspaces,
+start sessions, hand the DSH agent a coding task, read and write files, run commands.
+
+The endpoint runs *inside* the DSH host process, so a session created over MCP is a real
+DSH session. It appears live in the DSH UI, runs inside the DSH sandbox, and is subject to
+the same permission policy as anything you type yourself. Nothing about the agent is
+reimplemented.
+
+## How it works
+
+```mermaid
+flowchart LR
+  subgraph clients["Any MCP client"]
+    direction TB
+    c1["Claude Code"]
+    c2["Codex"]
+    c3["another DSH"]
+    c4["a CI job"]
+    c5["your own script"]
+  end
+
+  subgraph host["DSH host process"]
+    direction TB
+    plugin["dsh-as-mcp<br/>(this plugin)"]
+    tools["workspace_* · session_*<br/>file_* · shell_* · dsh_tool_*"]
+    services["the harness's own services<br/>workspace · session · fs · shell"]
+    plugin --> tools --> services
+  end
+
+  clients -- "Streamable HTTP or stdio<br/>bearer token" --> plugin
+```
+
+---
+
+## Install
+
+Three channels install this bundle into a profile; pick whichever matches where you got the
+package from.
+
+**From npm:**
+
+```bash
+dsh plugin --profile <name> add dsh-as-mcp
+```
+
+From a source checkout, the equivalent is `pnpm dsh plugin --profile <name> add dsh-as-mcp`.
+
+**From GitHub:**
+
+```bash
+dsh plugin --profile <name> add github:xiseliuli/dsh-as-mcp
+```
+
+A git install fetches source, not the built `lib/`, so pnpm must run this package's `prepare`
+script (`tsdown && node scripts/build-client.mjs`) to produce it. pnpm ≥10 refuses to run that
+script — and the `esbuild` postinstall the build depends on — until the profile allows them, so
+the first `add` fails with `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`.
+
+A bare package name in `allowBuilds` works for `esbuild` (a registry dependency) but never for
+`dsh-as-mcp` here: pnpm only approves a git-hosted build by its exact resolved key, never by
+name alone ([pnpm docs](https://pnpm.io/settings/build#allowbuilds)). The failed `add` prints
+that exact key in its error; copy it verbatim into the profile's `pnpm-workspace.yaml`
+(`~/.dsh/profiles/<name>/pnpm-workspace.yaml`) and re-run the `add`. Don't rely on pnpm having
+written a placeholder entry for you — on this failure path it does not. The result looks like:
+
+```yaml
+allowBuilds:
+  '<the exact git spec pnpm wrote, including its commit hash>': true
+  esbuild: true
+```
+
+Treat that allowance as permission to run this package's code on your machine at install time;
+pin a commit (`github:xiseliuli/dsh-as-mcp#<sha>`) so a later push cannot silently change what runs.
+`dsh plugin add` runs the pnpm version DSH pins (v11.7.0 as of DSH 0.1.7-rc.2 — its output ends
+with `using pnpm v…`), so the following applies only once DSH ships a newer pnpm. If the
+profile's pnpm is ≥11.19.0 (≥11.11.0 for a cloned, non-`github:` git dependency), you can instead
+approve the repository itself — `'dsh-as-mcp@git+https://github.com/xiseliuli/dsh-as-mcp.git': true`, with
+no `#<sha>` — so a later commit on the same repo keeps building without re-approval; on an older
+pnpm the exact-commit key is your only option and needs re-approving after every update
+([pnpm 11.11 release notes](https://pnpm.io/blog/releases/11.11-11.14),
+[pnpm/pnpm#12367](https://github.com/pnpm/pnpm/issues/12367)).
+
+**From a tarball:**
+
+```bash
+pnpm pack
+dsh plugin --profile <name> add /abs/path/to/dsh-as-mcp-<version>.tgz
+```
+
+Reinstalling from the *same* tarball path silently keeps the previous build — see the warning
+under "Installing into DSH Desktop" below for why, and give each rebuild a unique filename.
+
+---
+
+`dsh plugin add` records the package in the profile's `dsh.profile.bundles`, and the
+bundle's `cordis.patch.yml` supplies the plugin row and its defaults. **Restart DSH
+afterwards**: bundle patches are read at boot, not hot-reloaded.
+
+Confirm the layer composed:
+
+```bash
+dsh --profile <name> --dump-config | grep -A 30 '# == dsh-as-mcp'
+```
+
+**For publishers:** tag the GitHub repository with the topic `dsh-plugin` — that is what plugin
+discovery keys on — and keep npm's `latest` dist-tag pointed at an exact, stable version (no
+prerelease, no range), since that is what `dsh plugin add dsh-as-mcp` resolves.
+
+## Connect a client
+
+Every request needs a bearer token. It is resolved in this order:
+
+1. `auth.token` in the plugin config;
+2. `$DSH_HOME/dsh-as-mcp/token`;
+3. otherwise generated and persisted there on first run, with mode `0600`.
+
+The default endpoint is `http://127.0.0.1:8790/mcp`.
+
+A client that cannot set a header may pass `?token=<token>` instead. Prefer the header: a
+credential in a URL is one your shell history, a reverse proxy's access log, or a browser's
+history may keep. DSH itself does not log query strings (`webserver/src/index.ts:224`) and the
+plugin does not log the token, so this is a habit worth keeping rather than a leak this code
+introduces.
+
+**HTTP-capable client** (Streamable HTTP):
+
+```json
+{
+  "mcpServers": {
+    "dsh": {
+      "type": "http",
+      "url": "http://127.0.0.1:8790/mcp",
+      "headers": { "Authorization": "Bearer <token>" }
+    }
+  }
+}
+```
+
+**stdio-only client** — use the bundled bridge, which forwards each JSON-RPC message to the
+endpoint over HTTP:
+
+```json
+{
+  "mcpServers": {
+    "dsh": {
+      "command": "npx",
+      "args": ["-y", "dsh-as-mcp"],
+      "env": { "DSH_AS_MCP_TOKEN": "<token>" }
+    }
+  }
+}
+```
+
+`dsh-as-mcp --help` prints the endpoint and token state it will use. The bridge sends a token
+read from the token file to loopback endpoints only; pointing `DSH_AS_MCP_URL` off-host requires
+setting `DSH_AS_MCP_TOKEN` explicitly, so a copied client config cannot quietly exfiltrate the
+machine-local credential. "Loopback" means an exact match — `localhost`, `::1`, or a literal
+`127.x.x.x` address — so a name such as `127.0.0.1.example.com` is treated as the remote host it
+is. A scheme is optional: `127.0.0.1:8790/mcp` is accepted and understood.
+
+Start with **`dsh_info`**. It reports the endpoint, where its token comes from, which tool groups are enabled,
+and — importantly — which harness services the current profile actually provides, so a client
+can tell "this profile has no shell" from "the command failed".
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `dsh_info` | Endpoint, token source, enabled groups, available harness services. |
+| `workspace_create` | Register a directory as a DSH workspace (creating it if needed). |
+| `workspace_list` | Every registered workspace with id, path, title, session count, directory status. |
+| `session_create` | Start a DSH agent session bound to a workspace or bare directory. |
+| `session_list` | Live session summaries, most recently updated first. |
+| `session_prompt` | Send one task to a DSH session; by default waits for the turn and returns the reply plus every tool call the agent made. |
+| `session_messages` | Read a session's user/assistant transcript. |
+| `session_cancel` | Ask the agent to stop its current turn. |
+| `file_read` | Read a UTF-8 file through DSH's filesystem service. |
+| `file_write` | Create or replace a file through DSH's filesystem service. |
+| `file_list` | List a directory through DSH's filesystem service. |
+| `shell_run` | Run one command through DSH's shell service. |
+| `dsh_tool_list` | The agent tools this endpoint permits, with the schema DSH's own agent sees. |
+| `dsh_tool_call` | Run one of them directly, through the same pipeline the agent uses. |
+
+The typical coding flow:
+
+```
+workspace_create { path: "/Users/me/project" }
+  -> session_create { workspaceId: "..." }
+  -> session_prompt { sessionId: "...", prompt: "Add a --verbose flag to the CLI and a test for it." }
+```
+
+`session_prompt` is how you get work done *by* DSH: the DSH agent plans, edits files, runs
+its own tools, and can spawn subagents. `file_*` and `shell_run` are for when you want to do
+something yourself without involving the agent.
+
+`dsh_tool_call` is the third option: it runs one of DSH's *own* tools without spending a model
+turn to decide to call it. Call `dsh_tool_list` first — it reports exactly what is permitted, and
+a name it does not report is refused. Both require a `sessionId`, because that session's agent
+*is* the policy: it is what makes the harness apply a sandbox, run guards, and file the call under
+a transcript.
+
+There is deliberately no session-less form. DSH registers a tool into the scope of the context
+that registers it, and every tool package ships inside an agent preset, so the global layer is
+empty — an unscoped listing really does return zero tools, and an unscoped call answers
+`unknown tool`. A `dsh_tool_list` without a session therefore **fails loudly** rather than
+reporting an empty toolbox, which would read as "nothing is permitted". For the agentless path
+use `file_read` / `file_write` / `file_list` / `shell_run`, which resolve the deployment policy
+directly and need no session.
+
+The permitted set is an **allow-list**, and it is deliberately narrow. Everything absent is
+refused *and* hidden from `dsh_tool_list`. The omissions that matter:
+
+- **`run_code`** is DSH's programmatic-tool-calling entry point: one call runs a program that
+  can invoke *any other tool by name*. Exposing it would void the list entirely.
+- **`cordis_run`, `cordis_define`, …** execute arbitrary plugin code. No shipped bundle mounts
+  them, so a deny-list written against today's profile would be blind in exactly the profile
+  that adds them — which is why this is an allow-list.
+- **`ask_user_question` and `present`** reach the human at the keyboard.
+- **`workflow`, `ralph`, `send_message`, `spawn_teammate`, `schedule_create`** start work that
+  outlives the call; **`create_goal` and `update_goal`** sustain unattended execution.
+
+An operator can widen this deliberately with the `agentTools.allow` setting, or subtract from
+the default with `agentTools.deny`.
+
+## Security
+
+This endpoint is remote control of a coding agent that has shell access. Treat the token like
+an SSH key — and note that the plugin does too: no tool returns its value. `dsh_info` reports
+where the token comes from (a file path or the composition), never the literal, so a calling
+agent's transcript never accumulates the credential. A pinned token shorter than 16 characters
+draws a warning at boot, and a generated one is 43 characters of CSPRNG output.
+
+- The listener binds to `127.0.0.1` and every request is bearer-checked, including requests on
+  a route mounted on DSH's own web server. That check is the *only* gate there: an exact route
+  registered on the web server is matched **before** DSH's authorization fence — anything
+  unmatched is handed to that fence as a fallback (`webserver/src/index.ts:222-227`) — so with
+  `http.mountOnWebServer: true` the endpoint does not inherit your browser session's
+  protection, it enforces its own. One caveat on DSH Desktop: when ordinary browser access is
+  disabled there, the web server additionally refuses requests that do not carry the renderer
+  header, so the mounted path is unreachable for a plain MCP client — use the plugin-owned
+  listener. Setting `http.host: 0.0.0.0` exposes that same power to your network; the plugin
+  warns at bind time, and you should do it only behind your own gateway.
+- **The token is the entire security boundary, and that boundary is your user account.** There
+  is no path sandbox. Once a caller holds the token, `file_read`/`file_write`/`file_list` reach
+  anything the DSH process can reach, and `shell_run` runs arbitrary commands as you — because
+  that is exactly what the harness's own `fs` and `shell` services do for DSH's own agent. Both
+  properties were verified against a live instance: `file_read` returned `/etc/passwd`,
+  `~/.dsh/settings.yaml`, and this plugin's own token file; `file_write` created a file outside
+  every registered workspace. A workspace sets where a *session's* agent starts; it does not
+  fence these tools.
+- **The bridge is instance-wide, not per-caller.** `session_list` enumerates every session in
+  this DSH instance and `session_messages` reads any of their transcripts — verified reading a
+  session this plugin did not create. Those are the sessions you have been talking to DSH in, so
+  a token holder sees your conversation history, and a calling agent's context accumulates it.
+  This is not an escalation (the same bytes are in `$DSH_HOME/sessions`, reachable through
+  `shell_run`), but it is a privacy consequence worth knowing before you hand out a token.
+- Consequently the `tools` toggles **narrow what a client can discover and call; they are not
+  containment.** `tools.shell: false` removes the shell tool, but `file_write` still writes your
+  shell startup files and `file_read` still reads your credentials, so a profile with the shell
+  tool switched off is not safe to hand to a caller you would not give a login to. For real
+  containment, run the whole DSH instance inside an OS-level sandbox or as a dedicated
+  unprivileged account, and treat the token as that account's password.
+- `approval.policy` decides what happens when the DSH agent wants to run something the harness
+  would normally ask a human about:
+  - `inherit` (default) — the plugin does not answer. With no browser attached, an
+    approval-requiring tool resolves `unavailable` and the agent's action fails closed.
+  - `allow` — the plugin approves every request raised by a session **it created**, and stays
+    out of the waterfall for every other session, so your own interactive sessions keep their
+    policy. This is what makes unattended agent runs work; it is a real widening of what the
+    agent may execute.
+- `file_write` and `shell_run` are the *caller's* actions, not the agent's. They run through
+  the harness's own filesystem and shell services, so the sandbox and policy configured for
+  this DSH instance still apply.
+
+## Installing into DSH Desktop (restart required)
+
+Electron reserves the `desktop` profile, so `dsh plugin --profile desktop add` is refused from a
+plain terminal and the install is manual. DSH Desktop must then be **restarted**.
+
+### Why a restart is required
+
+`patchReload: live` in the profile manifest only governs the **CLI launcher**. The no-restart
+recompose is implemented by `watchUserPatches()`, which lives in the CLI's `runProfile()`
+(`apps/cli/src/profile-boot.ts`). DSH Desktop takes a different path: it calls `boot()` from
+`@deepseek-ai/dsh-app-boot` with the patch list computed once at startup, and the shipping app
+contains no such watcher at all:
+
+```bash
+grep -rn watchUserPatches <dsh-desktop>/dsh-plugin-desktop/src/    # no matches
+```
+
+Measured behaviour agrees: after editing the profile's `cordis.patch.yml`, the app log gained not
+one line and the port never opened.
+
+So: **a CLI-launched profile (`dsh --profile xxx`) applies patch edits immediately; DSH Desktop
+must be restarted.** On either path the watcher only recomposes config rather than replacing
+loaded modules, so editing `lib/` needs a restart regardless.
+
+### If the app will not start afterwards
+
+Reset `~/.dsh/profiles/desktop/cordis.patch.yml` to `[]` and the plugin takes no part in startup.
+To remove it entirely: `cd ~/.dsh/profiles/desktop && pnpm remove dsh-as-mcp`.
+
+### 1. Pack it and install into the desktop profile
+
+```bash
+cd /path/to/dsh-as-mcp && pnpm pack --pack-destination /tmp
+
+# raw pnpm, bypassing the CLI's reserved-profile guard
+cd ~/.dsh/profiles/desktop && pnpm add /tmp/dsh-as-mcp-0.1.0.tgz
+```
+
+> **Reinstalling over an existing install: change the tarball path.**
+> `pnpm` keys a `file:` dependency on the *path*, and a reinstall from the same path
+> reports `added 0` while leaving the previous content linked — a silently stale
+> build that still boots and still runs the old code. Give each build a unique
+> filename and the spec string changes with it:
+>
+> ```bash
+> TARBALL=/tmp/dsh-as-mcp-$(date +%s).tgz
+> cd /path/to/dsh-as-mcp && pnpm pack --pack-destination "$(dirname $TARBALL)"
+> mv /tmp/dsh-as-mcp-0.1.0.tgz "$TARBALL"
+> cd ~/.dsh/profiles/desktop && pnpm remove dsh-as-mcp && pnpm add "$TARBALL"
+> ```
+>
+> Then confirm the bytes actually match, or you are testing the old build:
+>
+> ```bash
+> wc -c ~/.dsh/profiles/desktop/node_modules/dsh-as-mcp/lib/index.js \
+>       /path/to/dsh-as-mcp/lib/index.js
+> ```
+
+### 2. Put the plugin row in the profile's own patch layer
+
+Edit `~/.dsh/profiles/desktop/cordis.patch.yml` (replace the `[]`):
+
+```yaml
+- insert:
+    - id: dsh-as-mcp
+      name: dsh-as-mcp
+      config:
+        http:
+          enabled: true
+          host: 127.0.0.1
+          port: 8790
+          path: /mcp
+        tools:
+          workspace: true
+          session: true
+          files: true
+          shell: true
+```
+
+Then **restart DSH Desktop** to mount the plugin.
+
+> ⚠️ **Do not also add `dsh-as-mcp` to `dsh.profile.bundles`.** The bundle contributes its own
+> row, so the composed result carries **two rows sharing one id** (`dsh --profile <name>
+> --dump-config` shows both). Use the patch layer or the bundle list, never both. Switch to the
+> bundle route via `dsh plugin add` when you want it to persist across restarts.
+
+### 3. Smoke-test it
+
+```bash
+node ~/.dsh/profiles/desktop/node_modules/dsh-as-mcp/scripts/smoke.mjs
+```
+
+It reads `<DSH_HOME>/dsh-as-mcp/token`, shakes hands, lists tools, calls `dsh_info` to report which
+harness services this profile actually mounted, then calls `workspace_list`. The last line is `OK`
+on success and the exit status is non-zero on failure.
+
+For one real round trip (temp workspace → session → hand the DSH agent a task → print the reply and
+tool calls):
+
+```bash
+node ~/.dsh/profiles/desktop/node_modules/dsh-as-mcp/scripts/smoke.mjs \
+  --prompt "In the current workspace create hello.txt containing hi, then read it back to confirm"
+```
+
+### 4. Uninstall
+
+Reset `~/.dsh/profiles/desktop/cordis.patch.yml` to `[]` and restart, and the plugin no longer
+mounts. To remove it entirely: `cd ~/.dsh/profiles/desktop && pnpm remove dsh-as-mcp`.
+
+## Configuration
+
+Defaults ship in `cordis.patch.yml`. A profile's own `cordis.patch.yml` overrides the row by
+`id`, and an override **replaces the row's whole `config` object** rather than deep-merging
+it — restate every key you still want. Unknown keys are rejected at boot with the offending
+key named, because a silently ignored typo means your override is not being applied.
+
+```yaml
+- id: dsh-as-mcp
+  name: dsh-as-mcp
+  config:
+    http:
+      enabled: true          # plugin-owned listener
+      host: 127.0.0.1
+      port: 8790             # 0 asks the OS for a free port
+      path: /mcp
+      mountOnWebServer: false # also serve at http://<dsh host>:<dsh web port>/mcp
+    auth:
+      token: ''              # empty: read/generate $DSH_HOME/dsh-as-mcp/token
+    tools:
+      workspace: true
+      session: true
+      files: true
+      shell: true
+    session:
+      agentPreset: ''        # empty: harness default
+      provider: ''           # must be paired with model
+      model: ''
+      promptTimeoutMs: 900000
+    limits:
+      maxReadBytes: 1048576
+      shellTimeoutMs: 120000
+      agentToolTimeoutMs: 120000
+    approval:
+      policy: inherit        # inherit | allow
+```
+
+## Settings panel
+
+Where the host mounts a settings service — DSH Desktop and `dsh web` both do — the plugin
+contributes an **MCP server** section to the settings panel. It edits the same `dsh-as-mcp`
+namespace the configuration above fills, so the panel and the file are two views of one
+value, not two copies.
+
+The panel covers every setting including the `agentTools.allow` and `agentTools.deny` lists,
+which are edited as comma-separated text. Both are ordinary `string[]` values, so an entry with a
+comma in it cannot be expressed here; use the configuration file for that.
+
+Every change applies **live**:
+
+| Change | Effect |
+| --- | --- |
+| a tool toggle | the group leaves or joins the very next `tools/list`; a disabled tool is genuinely absent, so calling it reports an unknown tool rather than running and being refused |
+| a limit, or a session default | read at the start of the next call |
+| the token | the new value is required by the next request; the old one stops working immediately |
+| `enabled`, `host`, `port`, `path`, `mountOnWebServer` | the listener is moved |
+
+Changing the port is the case worth stating plainly: the plugin stops the old listener and
+starts the new one, so the endpoint really does move. If the new port is taken, the bind error
+is shown in the panel and in `dsh_info` rather than being swallowed.
+
+The token is rendered **write-only**. Its literal never leaves the host process, so the panel
+shows only whether one is set, and a "clear" button. The copyable client configuration uses a
+`<token>` placeholder and points at the token file. Live endpoint state (listening, bind error,
+enabled tool groups) is served by a read-only route on DSH's connection layer — inside that
+layer's Host/Origin and browser-cookie fence, so it inherits DSH's own authorization and is
+never exposed on a bare port.
+
+The panel needs `@deepseek-ai/schemastery` to register a settings namespace; there is no
+schemastery-free path in DSH. It is declared as an **optional** peer and loaded by dynamic
+import, so a host that cannot supply it loses the section and nothing else — the endpoint keeps
+running from the configuration file. `dsh_info` and the smoke script both report which of the
+two you have.
+
+## Compatibility
+
+- **Harness** ≥ `0.1.5-rc.1` (developed and verified against `dsh-v0.1.5-rc.1`, the version
+  bundled with DSH Desktop 2.0.9), declared as `peerDependencies["@deepseek-ai/dsh"]:
+  ">=0.1.5-rc.1"` with no upper bound. DSH's plugin loader reads that range straight from the
+  manifest and semver-checks it against the single running runtime version (prereleases
+  included) *before* the plugin is imported; an incompatible install is refused unless the host
+  grants an exact-version exemption (`dsh plugin allow-version`).
+- **Node** `^22.19.0 || >=24.0.0`.
+- The `@deepseek-ai/dsh` peer is declared **optional**, purely so `dsh plugin add` does not pull
+  a full harness install into every profile just to satisfy it. Optional only changes
+  installation — DSH's compatibility gate reads `peerDependencies` regardless of
+  `peerDependenciesMeta`, so the version check above still applies in full.
+- **No other hard `@deepseek-ai/*` dependency.** This package resolves every other capability
+  structurally through `ctx.get(name)`, and its config schema is a hand-written
+  [Standard Schema](https://standardschema.dev) rather than a schemastery schema — which is all
+  Cordis's `resolveConfig` actually consumes. The one exception is `@deepseek-ai/schemastery`,
+  also declared as an **optional** peer: DSH offers no schemastery-free path to registering a
+  settings namespace, so wanting the panel means declaring it — but optional means a host
+  without it loses only the panel. This is the same stance the installed third-party
+  `dsh-tokenledger` takes.
+
+## Design notes
+
+- **Capability detection, not `inject`.** The plugin loads in a bare CLI profile that has no
+  web server, no session service, and no filesystem seam, and each tool then reports exactly
+  which service is missing and which bundle provides it. Declaring `inject` would make the
+  loader refuse to mount the plugin instead, which is a worse answer for a capability bridge.
+- **Waiting for a turn.** The harness exposes no per-message "await this turn" call —
+  `sessionController.prompt()` returns as soon as the message is queued. So `session_prompt` polls
+  the durable session log for a `user/message` whose `source.rpcId` equals the `requestId` it
+  passed to `prompt()` — the same correlation the session controller's own idempotency check uses
+  — and then waits for *that* turn to close. Attribution is what makes this correct rather than
+  plausible: a queued prompt's log entry sits inside the span of the turn that was already
+  running, so a `turn/end` appearing after our message is usually someone else's turn, not ours.
+  Turns on one session are additionally serialized, so two concurrent callers cannot interleave
+  prompts and then disagree about which reply is theirs. The serialization covers the whole wait,
+  not just the submission: a second `session_prompt` to a session whose first wait is still open
+  does not even submit its message until that wait settles (up to its timeout), and a `steer` sent
+  while another MCP wait is in flight is deferred until it, which turns it into a queued prompt.
+  Callers that only want to queue a message should prefer `session_messages` polling over holding
+  a long wait open.
+- **Filesystem.** Only `workspace_create` touches `node:fs` `mkdir` — the directory it creates
+  *is* the new sandbox root, so by definition it sits outside every root that exists before it,
+  which is why the call cannot go through the filesystem seam and is instead gated on the
+  read-only policy. The harness filesystem service deliberately exposes no `mkdir`; `file_write`
+  relies on the seam's atomic write, which creates parents inside the fence. Every read and
+  write goes through `ctx.fs`, so the same path rules and sandboxing the DSH agent lives
+  under apply to the caller.
+- **No session deletion.** The harness offers `archiveSession`/`unarchiveSession` but no
+  delete, so neither does this plugin.
+
+## Development
+
+```bash
+pnpm install
+pnpm build       # tsdown -> lib/
+pnpm typecheck   # tsc --noEmit
+pnpm test        # vitest
+```
+
+The test suite runs real HTTP against a real listener, spawns the real `bin/mcp-stdio.mjs`,
+and loads the plugin into a real `@deepseek-ai/cordis` context — with `resolveConfig` doing the
+config validation — so the wire protocol, the bridge, and the loader contract are all
+exercised rather than mocked.
+
+Two scripts run against a **live** endpoint, which is a different thing. Both resolve it the
+same way — the `--url`/`--token` flag wins, then `DSH_AS_MCP_URL`/`DSH_AS_MCP_TOKEN`, then the
+loopback default — and both print the endpoint they resolved and where it came from (`arg` /
+`env` / `default`) to stderr before sending anything, so a stray run cannot silently land on
+whatever DSH instance happens to be listening on the default port:
+
+```bash
+node scripts/smoke.mjs       # handshake, tools/list, dsh_info — is the wire up?
+node scripts/exercise.mjs    # ~40 checks: create a workspace, start a session, have the
+                             # DSH agent write code, read it back off disk, run it, check
+                             # the transcript, and confirm the failure paths are legible
+```
+
+`smoke.mjs` answers "does this speak MCP". `exercise.mjs` answers "can an outside agent
+actually drive a DSH instance through it" — and to answer that it hands a real prompt to a real
+DSH agent, making real LLM calls and costing real money against whatever endpoint it resolved
+to, so read the endpoint line it prints before letting it run. It is the only check that catches
+a whole class of bug a green unit suite misses — a test stub more forgiving than the harness
+service it stands in for. That class produced four real failures here, three in a primary use
+case, so run it after any change to the driver. `docs/STUB-FIDELITY-AUDIT.md` is the audit that
+enumerated the class; it is worth reading before writing a double for a harness service.
+
+Two rules this codebase learned the hard way:
+
+- **A double must enforce the service's real preconditions.** A stub that returns `undefined`
+  where the real call *rejects*, or that accepts both arguments where the real one rejects the
+  pair, converts a production failure into a green test. Where a double cannot model a service,
+  the missing double is itself the finding — the filesystem and shell seams had none, and the
+  worst bug lived there.
+- **A test can lock a bug in.** One asserted that a `turn/start` *before* our message meant the
+  turn was not ours; a real session log showed that is exactly the ordinary shape, and the
+  assertion kept every waiting `session_prompt` timing out on turns that had completed.
+
+## Publishing (maintainers)
+
+**One-time setup**, once the GitHub repo exists:
+
+1. Replace every `xiseliuli/dsh-as-mcp` placeholder in this repo (package.json's `repository`,
+   `homepage`, and `bugs`, plus both READMEs) with the real `xiseliuli/dsh-as-mcp` — a single global
+   find-and-replace works, since every occurrence uses the identical spelling.
+2. Tag the repo with the topic plugin discovery keys on:
+   `gh repo edit xiseliuli/dsh-as-mcp --add-topic dsh-plugin`.
+3. Trusted Publishing cannot perform a package's *first* publish — npm requires the package to
+   already exist on the registry before a Trusted Publisher can be attached to it (the
+   [`npm trust` docs](https://docs.npmjs.com/cli/v11/commands/npm-trust/) state the prerequisite
+   outright: "Package must exist: The package you're configuring must already exist on the npm
+   registry."). So the first release has to go out by hand: `npm publish --access public` from a
+   checkout (or `npm login --auth-type=web` first, if you'd rather not touch a long-lived
+   credential at all). Only after that publish succeeds does the package have a Settings page to
+   configure.
+4. On npmjs.com, open the package → **Settings** → **Trusted Publisher**, and add a GitHub
+   Actions publisher with this repo's owner, repo name, and the exact workflow filename
+   `release.yml`. Every release after this one goes out through
+   `.github/workflows/release.yml`'s OIDC flow — no `NPM_TOKEN` involved.
+
+**Every release:**
+
+```bash
+npm version patch   # or minor / major
+git push --follow-tags
+```
+
+The pushed tag triggers `release.yml`, which verifies the tag matches `package.json`'s version,
+builds, tests, and publishes — under the `next` dist-tag instead of `latest` if the version is a
+prerelease.
+
+**After a release, verify it actually installs:**
+
+```bash
+dsh plugin --profile <name> add dsh-as-mcp
+dsh --profile <name> --dump-config | grep -A 30 '# == dsh-as-mcp'
+```
+
+That is the same install/verify pair from "Install" above, run against the version that just
+shipped.
+
+## License
+
+MIT