E2B byte-PTY backend for ctx.pty. It creates persistent interactive shells inside the shared ctx.e2b sandbox while the PTY registry keeps session identity, exact-Agent ownership, and cleanup policy on the host.

Plugin and configuration

The pty-e2b plugin injects e2b and pty, then registers one backend under backendType.

Key	Default	Meaning
`backendType`	`shell`	Registry type selected by `terminal_open`.
`rows` / `cols`	`40` / `160`	Initial remote PTY size.
`scrollbackLines`	`10000`	Maximum retained logical lines.
`scrollbackMaxBytes`	`4194304`	Maximum retained UTF-8 scrollback bytes.
`maxReadBytes`	`262144`	Maximum bytes returned by one read or settled send.
`pollIntervalMs`	`50`	Host readiness-poll interval.
`idleSilenceMs`	`3000`	Output silence that yields `inferred_idle`.
`timeoutMs`	`30000`	Absolute startup and send wait bound.
`disposeGraceMs`	`3000`	TERM-to-KILL cleanup grace.

Numeric values are positive safe integers, backendType is non-empty, and maxReadBytes cannot exceed scrollbackMaxBytes. A relative spawn cwd resolves against ctx.e2b.cwd; an absolute remote path remains absolute.

Runtime contract

The backend uses E2B's byte-oriented PTY callback with a streaming fatal UTF-8 decoder, then the backend-neutral line sanitizer and bounded buffers from dsh-pty. It installs a controlled Bash prompt marker and waits for printable prompt text; when that marker is unavailable, observed output plus the configured silence bound yields inferred_idle. Startup with no output reaches the absolute timeout and fails instead of publishing an empty session.

Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through ps, then signal that group; SIGKILL refuses to target the shell itself. Close sends SIGTERM to the PTY process group, waits, escalates through E2B's PTY kill, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and PtyBackendCleanupError preserves a concurrent cleanup failure.

The remote PTY process and its child processes live in E2B. Prompt/readiness state, scrollback, operation handles, owner authority, and SDK event delivery remain in host memory.

Model Experience

Indirect consumer

What the model sees

Nothing directly. Through @deepseek-ai/dsh-tool-pty, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, signal results, and cleanup failures.

Token effect

None until a consumer returns bounded backend output. Retained host PTY scrollback is not placed in model history by this package.

KV Cache effect

No direct invalidation; the consumer owns prompts, schemas, and appended results.

Known Limitations and Deferred Work

Line-oriented terminal model — CSI/OSC control sequences are removed; alternate-screen and full terminal emulation remain unsupported.
Readiness is marker-or-silence based — E2B exposes foreground process groups but not the local backend's Linux syscall inspection, so inferred_idle is deliberately possible.
UTF-8 only — invalid byte sequences fail the session instead of returning lossy text.
No reconnectable terminal handles — retaining an E2B sandbox preserves remote files, not host ownership, buffers, callbacks, or live PTY sessions.