dsh-pty-session
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.
API
| 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. |
Lifetime & ownership
- Every call is authorized against the calling agent (
exec.agent); another
agent touching your session gets FOREIGN_SESSION.
- Sessions live with the plugin instance, not the turn: a fresh turn on
the same agent sees all its open sessions.
- The owner-scoped registry closes all sessions when the owning agent
disposes; the plugin additionally installs a dispose effect that closes
every session it opened.
Semantics worth knowing
- Lines, not bytes:
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.
Configuration
backendType: shell # registered PTY backend type passed to terminals.spawn
tailLines: 200 # default pty_tail budget
Consumer-plugin facade (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".
Instance matrix
| 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. |
Development
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).
Harness deps (important)
@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
