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

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

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 \node_modules\@deepseek-ai\dsh-tools
# same for schemastery and cordis