dsh-pty-session
DSH 插件将按所有者限定的 PTY 接口作为与协议无关的 pty_open/send/tail/close 工具公开——第 0 层核心。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:ch1bug/dsh-pty-session#d94547d211d6183d4615c8aafa7a22076caf857cPty Session 以 dsh-pty-session 发布，当前版本为 0.2.1-alpha.1-r1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
DSH plugin exposing the harness's owner-scoped PTY seam (ctx.terminals
— the same seam @deepseek-ai/dsh-tool-bash-persistent runs on) as four
protocol-agnostic tools: pty_open / pty_send / pty_tail / pty_close.
Layer 0 core: byte-stream sessions with zero protocol knowledge. Line framing, REPL prompts, and protocol parsing (gdb/MI, ssh banners) belong to consumer-layer plugins built on top of this surface.
| Tool | Args | Returns | Notes |
|---|---|---|---|
pty_open | command (required), cwd?, env? | sessionId, pid?, status, initialOutput | Spawns on a PTY; env vars are exported (POSIX quoting) before the command on shell-type backends. Session survives turns. |
pty_send | id, data (required), submit? (default true) | delta, status | Writes bytes; returns output read while the write settled. |
pty_tail | id (required), lines? | text, lines, truncated | Incremental cursor: returns only new output since the last tail — repeated tails never resend. Backlog beyond lines returns the newest lines and sets truncated: true. |
pty_close | id (required) | closed | Clean termination + reclaim. Idempotent per close. |
exec.agent); another
agent touching your session gets FOREIGN_SESSION.pty_tail inherits the seam's line-based scrollback
contract (totalLines/lineBegin/lineEnd). Output without a trailing
newline (a REPL prompt, a password prompt) becomes visible once its line
completes. Byte-exact tail is the consumer layer's job if a consumer ever
needs it.pty_send submit: defaults to true (backend Enter after the data) so
interactive sessions behave; pass submit: false for byte-exact writes.pty_close delegates termination to the seam's awaited, idempotent
cleanup (process-tree kill + quiescence) — the seam owns the mechanics.env is best-effort POSIX export lines and only meaningful on
shell-type backends (the seam's spawn request has no env field); don't
pass env against non-shell backends.backendType: shell # registered PTY backend type passed to terminals.spawn
tailLines: 200 # default pty_tail budget
ctx.pty)Consumer plugins (dsh-embedded-debug T5, later ssh) do not shell out through the four tools — they inject the same core as a cordis service:
const inject = ["tools", "pty"]; // add "pty" to the plugin's inject
// inside apply(ctx): ctx.pty is provided by dsh-pty-session
const opened = await ctx.pty.open(exec.agent, { command: "gdb -q -i=mi2" }, exec.signal);
await ctx.pty.send(exec.agent, opened.sessionId, { data: "-gdb-exit" });
const page = await ctx.pty.tail(exec.agent, opened.sessionId, 100);
await ctx.pty.close(exec.agent, opened.sessionId);
The facade exposes open/send/tail/close/dispose with EXACTLY the tool
semantics (same cursors, same seam reads — one core, two surfaces). The
owner is passed explicitly and must be the consumer's own exec.agent;
the seam enforces ownership (FOREIGN_SESSION). close is idempotent
(closed:false for an already-gone session). Loading this plugin becomes a
hard startup dependency of any consumer that injects "pty".
| Consumer | Status | Why |
|---|---|---|
| gdb (dsh-embedded-debug T5/T6) | first consumer — injects ctx.pty | MI framing lives in the consumer; API shape is being pressed out by gdb's needs. |
| ssh | planned — second consumer | Validates the abstraction once a second consumer exists. |
| serial (tio) / probe server / RTT | explicitly excluded | Non-PTY long-running processes: job + tail is already the correct pattern. |
npm install # vitest
npm test # vitest run
Tests are the reference implementation: they drive the real tool surface
against a fake terminals registry whose backend runs real interactive
child processes (echo round-trips, no protocol parsing).
@deepseek-ai/dsh-tools, @deepseek-ai/schemastery, and @deepseek-ai/cordis
must be junctions/symlinks into the installed harness's node_modules
(never copies): duplicated module instances make the DSH plugin loader fail
the entry with failed to import. On Windows:
New-Item -ItemType Junction -Path node_modules/@deepseek-ai/dsh-tools -Target <harness>\node_modules\@deepseek-ai\dsh-tools
# same for schemastery and cordis