dsh-single-terminal

dsh-single-terminal is a real-terminal drawer plugin for the DeepSeek
Harness (DSH) host. It docks an interactive PTY terminal (xterm.js) to the
bottom of the web app — type into it, Ctrl-C it, resize it, open as many tabs
as you need.

• Real PTY, not an emulator — each tab is a true pseudo-terminal
  (ConPTY on Windows, forkpty on POSIX) driven by node-pty; interactive REPLs,
  full-screen programs and Ctrl-C all behave like a native terminal
• Shell picker — Windows: PowerShell (default) / pwsh 7 / CMD / Git Bash /
  WSL (shells that are not installed are hidden automatically) + custom shells
  from config; POSIX: $SHELL / bash / zsh / fish
• Two drawer modes — Docked pushes the page content up (no occlusion),
  Overlay floats above it; drag the top edge to resize, the drawer remembers
  mode and height. Both modes share the same frosted-glass style (translucent
  background + backdrop-filter blur) — the mode only decides docking
  behavior. Open/close slides with the host's
  easing curve and honors prefers-reduced-motion.
• Theme following — the drawer and the terminal palette follow the host's
  theme (light / dark / custom themes) live; no separate theme config.
• Keep-alive sessions — terminals survive page refreshes and drawer
  close/reopen; on reconnect the recent output is replayed from a ring buffer.
  Opening the drawer with no terminal yet auto-creates one with the default
  shell.
• Workspace-aware cwd — when the current session belongs to a workspace,
  new terminals (including the auto-created one) start in that workspace root
  directory, no manual cd needed; with no session / no workspace the
  defaultCwd rules apply.
• Bilingual UI — follows the host interface language (中文 / English);
  Alt+C toggles the drawer

中文文档

Preview

Screenshot of the terminal drawer (dark theme following, frosted-glass style):
see preview.md.

Features

• Drawer-handle entry (rendered inside the drawer in shell.overlay): a
  >_ prompt tab stuck to the drawer's top-right outer edge — the terminal's
  entry button. It rides the drawer's own slide animation: expanded it sticks
  to the terminal's top-right corner like a drawer handle; minimized it settles
  at the page's bottom-right corner. Clicking toggles the drawer; Alt+C
  toggles from anywhere except while typing inside the terminal (there Alt+C
  is passed to the shell as ESC c).
• Invisible session bridge (conversation.session.header.utilities): a
  null-rendering component that only syncs the current session's workspace
  root into the controller (so new terminals start there); the header shows no
  visible UI for this plugin.
• Drawer (shell.overlay): a frame-level bottom drawer with
  • a tab strip — one PTY session per tab, independent shells, close button
    per tab (terminates the whole process tree; the pid is verified gone),
  • one ＋ button whose dropdown lists all shells found on this machine
    (unavailable ones are not listed), the default shell pinned first and
    marked,
  • a mode switch (Docked / Overlay), a connection status dot and a
    minimize (−) button,
  • a drag handle on the top edge (pointer-capture drag, min 140px).
• Docked mode pushes the app frame up with padding-bottom on the frame
  root element (no host hook exists for bottom docks); when the anchor cannot
  be found it silently falls back to overlay.
• Model tools: none — this plugin is UI-only by design.

Configuration

Schemastery Config (renders on the host Plugins settings page), and / or the
profile cordis.patch.yml:

- insert:
    - id: dsh-single-terminal
      name: dsh-single-terminal
      config:
        defaultShell: powershell   # powershell | pwsh | cmd | gitbash | wsl | <custom id>
        defaultCwd: home           # home | workspace | absolute path
        scrollbackLimit: 200000    # replay ring buffer, bytes per session
        fontSize: 13
        fontFamily: Consolas, "Cascadia Mono", "Courier New", monospace
        customShells:
          - id: nu
            name: Nushell
            command: nu            # resolved through PATH
            args: []

• defaultShell — shell preselected in the ＋ dropdown (pinned first and
  marked "Default"); when unavailable it falls
  back (powershell on Windows, $SHELL/bash on POSIX).
• defaultCwd — start directory when there is no workspace context: home
  (default) starts in the user home; workspace is reserved (currently
  resolves to home); an absolute path must exist. When the current session
  belongs to a workspace the workspace root takes precedence (see above).
• customShells — extra launchers; command may be an absolute path or a
  name resolved through PATH (with PATHEXT on Windows).

Installation

# Local development
dsh plugin --profile web add ./dsh-single-terminal

# Published: npm / tarball / GitHub
dsh plugin --profile web add dsh-single-terminal
dsh plugin --profile web add ./dsh-single-terminal-0.1.0.tgz
dsh plugin --profile web add github:you/dsh-single-terminal#<sha>

dsh --profile web                 # start (restart required for the host half to load)

node-pty is a native dependency of the host half (dependencies, kept
external and loaded via createRequire). It ships prebuilds for common
platforms; on unusual platforms a C/C++ toolchain is needed for
pnpm install to compile it. The browser half inlines xterm.js entirely —
no runtime dependency there.

Publish

The build toolchain is tsc + tsdown (no vite): tsc -b type-checks and
emits declarations, while tsdown (Rolldown core) bundles the host half
(lib/index.js, ESM) and the browser half (lib/client.js, single-file CJS
__ModuleLoader__ factory with auto banner wrapping). Dependency management
uses pnpm 10 (the pnpm-lock.yaml is committed and CI installs with
--frozen-lockfile). Build artifacts are committed to git, so git installs
need no build:

pnpm install     # install per pnpm-lock.yaml
pnpm run build   # clean lib → tsc -b (declarations) → tsdown (both halves)
pnpm run verify  # simulate the host module table to check lib/client.js (optional)
pnpm run release # check + build + verify + npm version patch + push tags (triggers the publish workflow)

Automated publishing (GitHub Actions)

Pushing a v* tag (pnpm run release bumps the patch version, rebuilds, and
tags/pushes automatically) triggers
.github/workflows/publish.yml — a single
release job that: sets up Node 26 → pnpm install --frozen-lockfile →
pnpm run check → pnpm run build → pnpm run verify → pnpm pack →
creates a GitHub Release (auto-generated changelog, tarball attached) →
publishes to npm via Trusted Publishing (OIDC --provenance, no
NPM_TOKEN secret; the npm package must have this repository configured as a
Trusted Publisher).

Development

Requirements: Node ≥ 22.19 (or ≥ 24) + pnpm 10 (the packageManager field
pins the pnpm version).

pnpm install           # includes node-pty + ws (runtime) and @xterm/* (bundled into the client)
pnpm run check         # whole-tree TypeScript type check (tsc -b)
pnpm run build         # clean lib → tsc -b (declarations) → tsdown (both halves)
pnpm run watch         # tsdown watch mode
pnpm run verify        # simulate the host seed table to check lib/client.js loads

├── src/                # Source
│   ├── host/           # Host half: index.ts (entry, ws route + config), hub.ts (session hub + frame protocol), shells.ts (registry + probing), types.ts
│   └── client/         # Browser half: plugin.tsx (slots), drawer.tsx (drawer + entry handle), term.tsx, controller.ts, ws.ts, styles.ts, theme.ts, scope.tsx (session bridge), i18n.ts ...
├── lib/                # Build artifacts (committed: git installs need no build)
│   ├── index.js        # Host half (tsdown, ESM)
│   ├── client.js       # Browser half (tsdown → __ModuleLoader__ factory, xterm inlined)
│   └── types/          # Type declarations (generated by tsc -b)
├── assets/preview/     # Screenshots referenced by README / preview.md
├── scripts/            # verify-client.mjs (host-seed simulation check), gen-xterm-css.mjs (regenerates src/client/xterm-css.ts)
├── tsdown.config.ts    # tsdown build config (node half + client bundle banner wrapper)
├── tsconfig.json       # solution: references tsconfig.host.json / tsconfig.client.json
├── cordis.patch.yml    # Bundle patch: plugin row referenced by package name (no paths)
├── package.json        # dsh.bundle + dsh.client(web) manifests + peerDependencies
├── README.md           # This file (English)
├── README.zh.md        # 中文文档
└── preview.md          # Screenshot preview (references assets/preview/*.png)

Implementation notes

• Why the plugin ships its own node-pty: the host subprocess terminal
  primitive (SubprocessTerminalHandle) intentionally exposes no resize,
  which a resize-following terminal needs; a plugin-owned node-pty gets the
  full write / resize / kill control surface with the same ConPTY/forkpty
  substrate the host uses.
• Transport: a dedicated WebSocket route (/api/dsh-single-terminal.ws)
  registered through ctx.webServer.registerUpgrade, gated by
  ctx.connection.requestRejection (same trusted-host fence as the host API
  gateway). The client connects same-origin and rides the dsh-auth cookie.
• Session model: sessions live in a hub Map independent of sockets —
  page refresh / reconnect re-lists, adopts live sessions and attaches
  with a replay of the ring buffer. Exited sessions are pruned so dead tabs
  never resurrect. Multiple browser tabs may attach to one session (output is
  broadcast, input is merged).
• Frame protocol: JSON text frames; client → host open / input / resize / close / list / attach / ping, host → client hello / shells / opened / data / replay / exit / error / pong. input/resize are size-capped and
  clamped server-side.
• Windows process tree: closing a tab runs pty.kill() and additionally
  taskkill /T /F on the session pid — ConPTY closure alone can leave
  PowerShell (+PSReadLine) alive; POSIX kills the foreground process group
  (kill(-pid)).
• Theme following: all plugin CSS consumes the host's semantic alias
  tokens (--dsw-alias-*, defined on body and flipped by
  body[data-ds-dark-theme]), so light / dark / custom themes apply without
  plugin-side logic. The xterm palette is computed at runtime: alias token
  values are read via a hidden probe element (getComputedStyle), the
  background is re-composed with the frosted alpha, and a MutationObserver
  on the body attribute re-applies the palette — theme switches (including
  custom themes projected by the host's ThemePresenter) update live.
• Renderer strategy: xterm 5 ships DOM renderer only by default
  (allowTransparency works there, while WebGL canvases are opaque). Both
  modes share the frosted style, so the plugin stays on the DOM renderer with
  a translucent terminal background under the frosted blur in every mode —
  the WebGL addon was removed rather than swapped at runtime.
• The official deepseek-harness project is not modified; all UI sits in
  existing slots (shell.overlay for the drawer and its entry handle,
  conversation.session.header.utilities for the invisible session bridge).