dsh-interactive-terminal
DeepSeek Harness 的交互式终端插件
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:mingzhicode/dsh-interactive-terminal#e96238805b514991b179d3ba3bf3e3f3daa37f91Interactive Terminal 以 dsh-interactive-terminal 发布，当前版本为 0.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
A persistent Bash terminal shared by the model and the user in DeepSeek Harness Web. Each live Agent owns one PTY, rendered with xterm.js above the composer. The model can run terminal tools, and a human can continue the same interactive process without starting a separate shell.
A controller view after a multi-round UTF-8 terminal interaction
A connected Controller view after human input completed a four-round UTF-8 interaction started by the model.
Requirements: macOS or Linux, Bash, Node.js ^22.19 || >=24, and pnpm on PATH. Version 0.1.0 is tested with DSH 0.1.0-rc.8 and pnpm 10.18.3.
npm install -g @deepseek-ai/dsh@0.1.0-rc.8 pnpm@10.18.3
dsh plugin --profile web add dsh-interactive-terminal@0.1.0
dsh --profile web
Open the URL printed by DSH, configure a model if needed, select a workspace and conversation, and click Open terminal. Type echo hello at the idle prompt to verify browser input. Later launches only need:
dsh --profile web
dsh plugin --profile web add dsh-interactive-terminal@0.1.0
dsh --profile web
The plugin command installs the package into the Web profile and activates its bundled cordis.patch.yml; no additional --patch is needed. Installing the package globally with npm install -g does not activate it in DSH.
Installation and startup must use the same DSH_HOME, whose default is ~/.dsh. Restart an already running DSH after adding or updating the plugin. If pnpm reports that no versions are available, verify that the profile uses the public registry:
cd "${DSH_HOME:-$HOME/.dsh}/profiles/web"
pnpm config set registry https://registry.npmjs.org/ --location=project
Use the DSH tag supported by this plugin, then run the repository's source CLI:
git clone --branch dsh-v0.1.0-rc.8 --depth 1 https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm dsh plugin --profile web add dsh-interactive-terminal@0.1.0
pnpm dsh --profile web
The first pnpm dsh is the source equivalent of the installed dsh command. The profile remains under the same DSH_HOME, so later source launches only require the final command.
git clone https://github.com/mingzhicode/dsh-interactive-terminal.git
cd dsh-interactive-terminal
pnpm install
pnpm run build
dsh plugin --profile web add "$PWD"
dsh --profile web
The profile loads the local checkout's built lib/ and dist/ files. After changing the plugin source, rebuild it and restart DSH. When using a DSH source checkout, run pnpm dsh from that repository and pass this plugin's absolute directory to plugin add.
dsh plugin --profile web add ./dsh-interactive-terminal-0.1.0.tgz
dsh --profile web
The tarball contains the host and browser builds and has no build-on-install or postinstall step. Its dependencies may still require registry access. Download a published tarball separately with npm pack dsh-interactive-terminal@0.1.0.
shared_terminal_send to start a program. While the model operation owns the queue, ordinary typing is ignored instead of becoming a later shell command.SIGINT to the re-inspected foreground process group. This interrupts the program and retains ownership until prompt recovery; it is not an input handoff.The settings menu provides Reconnect, local Clear view, text-size controls, and a confirmed Reset Terminal. Collapsing the panel, clearing the view, or reconnecting does not end the shell. Resizing the panel does not change the fixed PTY rows and columns. Host disposal closes the panel and clears the local renderer and unsent input; temporary disconnections reconnect automatically.
Only one browser view controls an Agent's terminal. Additional views and all mobile views are read-only. Take over input transfers the model's current queue operation to the browser Controller; it does not take browser control away from another view. If the header says Read only, close the controlling view, wait for disconnectGraceMs, then use Reconnect.
Add an override to ~/.dsh/profiles/web/cordis.patch.yml, or $DSH_HOME/profiles/web/cordis.patch.yml when using a custom home:
- id: dsh-interactive-terminal
config:
shellPath: /bin/bash
shellArgs: [--noprofile, --norc, -i]
rows: 40
cols: 160
The patch replaces this entry's complete config; include every custom value you want to retain. Omitted fields use the defaults below.
Configuration is resolved when the plugin loads. After editing the patch, restart DSH so the new values take effect. Reset Terminal destroys the current shell and creates a new generation with the configuration already loaded in memory; it does not reread the YAML file.
| Field | Default | Effect |
|---|---|---|
shellPath | /bin/bash | Bash executable; other shells are rejected. Applied when a terminal generation is created. |
shellArgs | --noprofile --norc -i | Interactive-shell arguments; empty arguments are rejected. Applied at shell spawn. |
rows | 40 | Fixed PTY rows for every new generation. |
cols | 160 | Fixed PTY columns for every new generation. |
scrollbackLines | 10000 | Retained history lines, excluding the viewport. Applied to host snapshots and the browser renderer. |
scrollbackMaxBytes | 4194304 | UTF-8 limit for serialized ANSI history, excluding the viewport. |
maxToolOutputBytes | 262144 | Complete tool-result JSON limit; at least 1024 and no greater than scrollbackMaxBytes. |
maxInputBytes | 65536 | Input bytes per model send or accepted human input lease. |
maxQueuedOperations | 128 | Accepted mutations per Agent, including the active operation. |
maxSessions | 32 | Maximum number of live Agent terminals. |
pollIntervalMs | 50 | Delay from one foreground-process check to the next. |
operationTimeoutMs | 30000 | Model mutation deadline before interrupt recovery starts. |
interruptTimeoutMs | 5000 | Controlled-prompt recovery deadline after SIGINT. |
disconnectGraceMs |
disconnectGraceMs; other desktop views and all mobile views are read-only.shared_terminal_read bypasses input ownership.waitReason: human_handoff to the model, and leaves later operations queued.stdin_read, or process exit completes the active operation. macOS DSH rc.8 does not report stdin_read, so interactive prompts require explicit handoff before operationTimeoutMs expires.SIGINT to a freshly inspected foreground process group and holds the queue through prompt recovery. If recovery misses interruptTimeoutMs, the queue becomes blocked; only the earliest accepted reset may replace it.All tools address the executing Agent's terminal. A caller cannot choose another Agent, PTY, working directory, shell, environment, or sandbox.
| Tool | Behavior |
|---|---|
shared_terminal_send({ text, submit? }) | Queue model input. submit defaults to true and appends Enter. Returns on prompt, observed stdin_read, human handoff, exit, or timeout/cancellation recovery. |
shared_terminal_read({ offset?, count? }) | Read the viewport and a newest-relative history page without acquiring input ownership. offset skips lines from the newest end; count selects preceding lines. |
shared_terminal_signal({ signal }) | Queue SIGINT, SIGTERM, SIGKILL, SIGTSTP, or SIGHUP for the re-inspected foreground process group. SIGKILL of the top-level shell is refused. |
shared_terminal_reset({}) | Queue process-tree teardown and a fresh shell generation; also replaces a naturally exited shell. |
Results include generation, output sequence, geometry, viewport, cursor, process and queue status, holder, pending count, and truncation state. Mutations add queue time and waitReason; send and signal add captured operation output. Reads add text, lineBegin (inclusive), lineEnd (exclusive), and totalLines. Cursor coordinates are zero-based.
waitReason: human_handoff means the human owns a still-running interaction, not that the command completed. The model must wait instead of submitting an answer behind that lease. A timeout likewise does not prove that the foreground process exited.
queue is blocked until reset: interrupt recovery missed its deadline. Wait for the earliest accepted reset; later mutations are rejected.terminal queue is full: wait for accepted operations instead of retrying in parallel.terminal capacity reached: dispose an Agent or finish pending cleanup before increasing maxSessions.disconnectGraceMs.TERM=dumb, fixed geometry, and PAGER=cat are intentional. Full-screen or terminal-query-dependent TUIs are unsupported; the browser suppresses generated query replies and the Host has no query responder.The Host decides terminal identity, working directory, and sandbox policy. When confinement is required, unavailable confinement fails startup rather than falling back to unconfined execution. The shell does not inherit Harness credentials.
Browser attachment uses hashed, Agent-bound, single-use tokens valid for ten seconds. The WebSocket accepts no caller-selected Agent, Session, or PTY identifier. Raw terminal output and human keystrokes are not session events; model tool arguments and bounded results are logged normally.
Custom subprocess providers must re-inspect the foreground process group when delivering a signal and refuse top-level shell SIGKILL, as the official DSH rc.8 provider does.
pnpm install
pnpm run build
npm pack --dry-run
npm pack
The generated .tgz can be installed with the tarball command above. For isolated verification, set DSH_HOME to a fresh directory before both installation and startup. The keyless Web tests use a replay model with a real Agent loop and native PTY; they are not a live-model test.
Build and verification do not publish. Before publishing manually, run release checks, inspect the package contents, and confirm the npm account, registry, version, and explicit publishing authorization. Never place credentials in the repository or logs.
MIT. See LICENSE.
15000 |
| Controller reconnect grace before active human input is recovered and released. |
disposeGraceMs | 3000 | Process-tree termination grace during reset or teardown. |