README.md 5.9 KB
description: "Interactive user terminals with execution-environment shell defaults, bounded screen recovery and typed Remote control."
kind: "package-reference"
@deepseek-ai/dsh-api-terminal-controller
English | 中文
Summary
Open the execution environment's default shell in a Session workspace from the Web sidebar. Reconnect to existing processes and close their complete provider-owned process ranges. Terminal output stays outside the Agent transcript. Keeping a terminal open retains its process and a bounded screen buffer.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
The Web bundle mounts this package with the subprocess provider, sandbox policy and Typert Gateway. remote.terminal exposes environment, list, create, follow, write, resize, rename and close; each operation is scoped by Session identity.
New terminals use the execution environment's declared default shell. Only when the provider omits that default does resolution use /bin/sh on POSIX or cmd.exe on Windows. An optional shell profile overrides that choice with executable path, display name and args (default []). The provider verifies the executable during creation; resolution failure is reported without trying another shell. Environment lookup returns the working directory and limits without resolving a shell, so an unavailable default does not prevent reattaching to an existing process. Automatic POSIX profiles start interactively, and PowerShell uses -NoLogo, so completion and startup configuration remain shell-owned. The Session workspace supplies the initial directory; its sandbox policy also applies to the terminal.
| Configuration | Default | Meaning |
|---|---|---|
shell |
omitted | Use the execution environment's default shell, or one explicit profile |
maxTerminals |
8 |
Retained terminals and pending allocations per Session |
maxCols, maxRows |
500, 200 |
Maximum PTY dimensions |
scrollback |
1000 |
Retained screen history rows |
maxBufferedBytes |
2097152 |
Output queued for one follower |
maxInputBytes |
65536 |
Maximum input request bytes |
disposeGraceMs |
1000 |
Provider termination grace in milliseconds |
Understand the implementation
Implementation internals — click to expand
The Host uses `ctx.subprocess.spawnTerminal` with `TERM=xterm-256color`; it never launches a desktop terminal application. Unary control uses the Gateway, and `follow` uses its multiplexed Remote stream transport. Headless xterm and its serializer produce each opening screen after all preceding output writes, then monotone output sequences identify subsequent frames. Slow followers fail explicitly; a new attachment restores the current screen. The latest attachment owns input and resize. Detachment releases input control without killing the process. Explicit close awaits process cleanup and final output; cleanup failure retains the resource for retry. The Session remembers closed identities and rejects their delayed or repeated creation, including creation already in progress when close arrives. A new terminal uses a new identity. Pending allocations remain owned even if cancellation and cleanup both fail. Session owner disposal and controller disposal also terminate owned processes. An open or pending terminal prevents changing that Session's sandbox mode. Client views keep the association between sidebar tabs and terminal identities in memory. Recovery queries the Host for retained terminals; a new view may create a process, while a recovered view reports a missing target without creating a replacement. The Client model acknowledges screen writes after the browser emulator processes them, serializes input and ignores stale attachment responses. Closing saves an unfinished cleanup request before releasing the tab, then awaits Host cleanup in the background. A failure exposes a retry notification. Each request has its own terminal-ID localStorage key and is removed after successful cleanup; startup retries saved requests. This stores cleanup intent, not sidebar layout, open-tab mappings, selected tabs or process PIDs. If browser storage is unavailable, cleanup remains usable in memory but cannot be recovered after reload.Further Exploration
Model Experience
None, as this package handles user terminal interaction without adding model input.
KV Cache effect
None; terminal output travels only between the browser and Host.
Known Limitations and Deferred Work
- Processes and screens survive browser reloads, but not Host or Session owner disposal. There is no durable terminal restoration or automatic shell respawn.
- The subprocess provider determines native PTY availability and process-tree cleanup guarantees. Finding an executable does not prove PTY allocation will succeed.
- Screen recovery retains bounded history, not a complete transcript. Only one attachment at a time can write or resize.