dsh-web-terminal

dsh-web-terminal

A terminal dock merged into the DSH web GUI: hideable, split-screen with the chat (it owns the shell's real bottom band, so the columns shrink instead of being covered), and integrable with terminal-designed TUI plugins.

┌─────────────────────────────┐
│  session header     [终端] │  ← toggle (conversation.session.header.utilities)
├─────────────────────────────┤
│  conversation (chat)        │  ← keeps its own scrollport, stays mounted
├─────────────────────────────┤  ← shell.bottom slot
│  [Shell] [Panel] ×          │  ← dock tab bar
│  xterm.js terminal / TUI    │  ← full-emulation ConPTY
└─────────────────────────────┘

• Hide / show: header button or `Ctrl+``. Hiding collapses the band to zero height; the xterm instance and the PTY session survive (VS Code style).
• Split-screen: the dock is the occupant of shell.bottom, a shipped slot whose rendered height is subtracted from the three columns. No DOM injection, no padding hacks. Height is draggable (120–900 px) and persisted in localStorage (dsh.webTerminal.v1).
• TUI integration: any terminal-designed TUI runs unchanged inside the PTY (vim, htop, tian-shu-tui, …), plus a registerView API so plugins can add their own views.

Install

dsh plugin --profile desktop add link:D:\Deepseek Harness\dsh-web-terminal
# restart the GUI, then use the header toggle or Ctrl+`

The bundle patch inserts the host half (lib/index.js: node-pty PTY + WebSocket bridge + webTerminal registry) and the client half (lib/client.js: the dock component).

Architecture (0.2)

Piece	File	Notes
Plugin entry (host)	src/index.ts	webServer inject, routes + webTerminal service under ctx.effect, Config schema drives the settings page
Routes + WS terminal	src/routes.ts	loopback fence, WebSocketServer({noServer:true}), 1MB/512KB backpressure
PTY layer	src/pty.ts	node-pty direct (^1.1.0, prebuilt win32-x64 ConPTY), TERM/COLORTERM env, powershell.exe default
Shared protocol	src/protocol.ts	frame types + WT_API paths + clamps
TUI registry	src/tui-registry.ts	webTerminal.registerView(def) extension seam
Client entry	src/client/index.ts	registers into shell.bottom + conversation.session.header.utilities, `Ctrl+``
Dock UI	src/client/dock.tsx	xterm + FitAddon, tabs, drag resize, TUI channel
TUI channel	src/client/tui-channel.ts	window CustomEvent channel
Demo adapter	src/examples/*	one dom view (demo:panel, proves the CustomEvent channel)

Client bundle rules

• The browser artifact registers a lazy factory under the package name: window.__ModuleLoader__.load({ id: 'dsh-web-terminal', factory(require) { … } }).
• React, react-dom and react/jsx-runtime come from the loader's module table via require() — never an inlined second copy (two React instances break hooks and the shell's renderer). @xterm/* is not in that table and stays bundled.
• apply(ctx) only registers slots/effects; keep the factory free of side effects.

Wire protocol (/api/dsh-web-terminal/*, loopback-fenced)

server→client: {type:'ready',view,cols,rows} | {type:'output',data}
               | {type:'title',title?} | {type:'exit',code,error?}
client→server: {type:'input',data} | {type:'resize',cols,rows}

TUI plugin integration API

Host side — any DSH plugin registers a view inside its own ctx.effect:

const webTerminal = ctx.get('webTerminal')
ctx.effect(() => webTerminal?.registerView({
  id: 'my-plugin:my-tui',        // namespaced 'pluginId:viewId'
  label: 'My TUI',
  order: 10,
  spawn: ({ cols, rows, env }) => ({
    command: 'npx',
    args: ['--yes', 'my-tui'],
    shell: true,                 // run through the default Windows shell
    env: { ...env, MY_FLAG: '1' },
  }),
}), 'my-plugin: tui view')

Client side — the browser half of the same plugin:

import { dispatchRegister, dispatchUnregister, onTuiEvent, TUI_EVENTS } from 'dsh-web-terminal/client'

ctx.effect(() => {
  dispatchRegister({ id: 'my-plugin:my-tui', label: 'My TUI', kind: 'pty' })
  return () => dispatchUnregister('my-plugin:my-tui')
}, 'my-plugin: tui client')

Events: adapter→dock register / unregister; dock→adapter ready (re-register, self-heal), activate ({id,container} — dom views render here), deactivate, view-state ({id,state:'running'|'exit'|'error',code?,error?}).

Security

• Every route + the WS upgrade carry the loopback-only fence (remoteAddress ∈ {127.0.0.1, ::1, ::ffff:127.0.0.1}, Host localhost, sec-fetch-site and Origin checks) — LAN-exposed dsh web deployments must not serve these.
• Client frames are strictly validated; only input/resize are accepted, cols/rows clamped.
• The PTY is killed on socket close/error, tab close, dock unmount, and plugin dispose (ctx.effect disposer); no fs access from the browser.

Windows caveats

• node-pty never sets TERM from the name option on Windows — the plugin sets TERM=xterm-256color/COLORTERM=truecolor explicitly in the env.
• kill(signal) throws on Windows — bare kill() only; Ctrl+C is \u0003.
• Default shell: powershell.exe (pwsh if installed, cmd.exe last resort). cmd.exe may need chcp 65001 for UTF-8 TUI output.
• ConPTY emits CRLF natively — the bridge never converts EOL (convertEol:false).

Build

pnpm install        # node-pty ^1.1.0 prebuilt win32-x64 — no compiler needed
pnpm build          # tsc typecheck + tsdown → lib/index.js + lib/client.js

Compatibility

• Target: DSH 0.2.x (shell.bottom slot era). The 0.1 line mounted the dock into the conversation column with DOM injection; that path is gone.
• Verified on 0.2.1-rc.3 (Windows, ConPTY).