refactor(e2b): group remote providers

packages/e2b/pty-e2b/README.md

@@ -0,0 +1,54 @@
+# @deepseek-ai/dsh-pty-e2b
+
+English | [中文](README.zh.md)
+
+E2B byte-PTY backend for [`ctx.pty`](../../pty/pty/README.md). 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.