@monotykamary/dsh-terminal-web 0.1.0-rc.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/terminal/terminal-web/README.md
+README.md: 682b45a2aea14d8569c56140940152567f031ffb
+README.zh.md: 492134c4cd2b3e4023fce3ddb1d4250219b6b260

package/README.md

@@ -0,0 +1,38 @@
+# @monotykamary/dsh-terminal-web
+
+English | [中文](README.zh.md)
+
+Host Consumer that exposes Agent-owned persistent terminals to the same-origin Web client at `/api/terminal`. It registers a full-duplex WebSocket upgrade through `ctx.connection`, so Host/Origin checks and optional identity admission run before this package receives a socket. Every operation resolves the selected Agent and delegates authorization to the Host `ctx.terminals` registry; browser clients cannot attach terminal sessions created for model tools.
+
+## Operations and framing
+
+A new socket starts with one JSON text handshake: `list`, `open`, `attach`, or `kill`. `open` creates a placement-named native interactive login shell in the selected Session cwd and forwards the requested initial grid; `list` returns only terminals owned by that browser placement. Any number of sockets may attach the same PTY: each receives bounded replay plus live output, input is ordered across viewers, and the most recently interactive viewer controls the shared PTY grid. An attached socket carries UTF-8 terminal input as binary client frames, raw PTY output as binary Host frames, and `resize`, `kill`, `ready`, `output-frame-start`, `output-frame-end`, `exit`, `pong`, or failure controls as JSON text frames. Closing a socket detaches only that viewer and does not terminate the persistent process.
+
+Output uses LocalTerm's two-millisecond trailing idle window and a continuous-burst bound: each kernel fragment resets the idle timer, 65,536 bytes flush immediately, and a partial stream flushes within `outputStreamThresholdMs`. A redraw that crosses the byte cap opens `output-frame-start`, sends each transport chunk in order, and closes with `output-frame-end` at the trailing idle edge, so the browser commits the complete redraw as one xterm parse transaction; a burst that reaches `outputStreamThresholdMs` closes its bracket and resumes progressive delivery. Browser attachments retain at most 16 MiB for one staged frame and disconnect on overflow. The sender retains immutable stream buffers without an intermediate copy. A slow browser is disconnected before the WebSocket queue exceeds `maxBufferedBytes`; input size, handshake time, and PTY dimensions are bounded at the wire parser. The shared terminal operation queue starts idle input synchronously, preserves FIFO order across asynchronous providers and viewers, and lets plugin disposal await quiescence.
+
+## Configuration
+
+| Field | Default | Meaning |
+|---|---:|---|
+| `backendType` | `shell` | `ctx.terminals` backend used by `open`. |
+| `maxInputBytes` | 65,536 | Maximum bytes in one client input/control frame. |
+| `outputBatchBytes` | 65,536 | Maximum bytes combined before immediate output flush. |
+| `outputBatchWindowMs` | 2 | Trailing idle delay for a partial output batch. |
+| `outputStreamThresholdMs` | 100 | Maximum duration for a continuous partial output burst. |
+| `maxBufferedBytes` | 4,194,304 | WebSocket queue limit before disconnect. |
+| `handshakeTimeoutMs` | 10,000 | First-frame deadline. |
+| `maxCols` / `maxRows` | 1,000 | Accepted PTY dimension limits. |
+
+## Model Experience
+
+None, as this browser transport adds no model-visible input or output.
+
+#### KV Cache effect
+
+None; WebSocket input bypasses model requests.
+
+## Known Limitations and Deferred Work
+
+- Terminal bytes and attachments remain process-local; a Host restart ends every browser terminal.
+- The wire sends raw output without application-level compression.
+- One socket attaches one terminal; sharing one PTY across viewers uses independent sockets rather than multiplexing several PTYs over one socket.

package/README.zh.md

@@ -0,0 +1,38 @@
+# @monotykamary/dsh-terminal-web
+
+[English](README.md) | 中文
+
+该 Host Consumer 在同源 Web 客户端的 `/api/terminal` 上暴露 Agent 拥有的持久终端。它通过 `ctx.connection` 注册全双工 WebSocket upgrade，因此 Host／Origin 检查与可选身份准入会先于本包接收 socket 执行。每项操作都会解析选中的 Agent，并把授权委托给 Host 的 `ctx.terminals` 注册表；浏览器客户端无法附加模型工具创建的终端会话。
+
+## 操作与帧
+
+新 socket 以一条 JSON 文本握手开始：`list`、`open`、`attach` 或 `kill`。`open` 会在所选 Session cwd 中创建带位置名称的原生交互式 login shell，并转发请求的初始网格；`list` 只返回该浏览器位置拥有的终端。任意数量的 socket 都可以附加同一 PTY：每个 socket 都会收到有界 replay 与实时输出，查看方之间的输入保持有序，最近发生交互的查看方控制共享 PTY 网格。附加后的 socket 使用客户端二进制帧传送 UTF-8 终端输入，使用 Host 二进制帧传送原始 PTY 输出，并使用 JSON 文本帧传送 `resize`、`kill`、`ready`、`output-frame-start`、`output-frame-end`、`exit`、`pong` 或失败控制。关闭 socket 只会分离该查看方，不会终止持久进程。
+
+输出采用 LocalTerm 的两毫秒 trailing idle 窗口与连续 burst 上限：每个 kernel fragment 都会重置 idle timer，达到 65,536 字节时立即刷新，部分 stream 会在 `outputStreamThresholdMs` 内刷新。跨越字节上限的 redraw 会打开 `output-frame-start`，按顺序发送每个 transport chunk，并在 trailing idle 边界发送 `output-frame-end`，使浏览器把完整 redraw 作为一次 xterm parse transaction 提交；达到 `outputStreamThresholdMs` 的 burst 会关闭 bracket 并恢复渐进式交付。浏览器 attachment 最多为一个 staged frame 保留 16 MiB，超过该上限时会断开。发送方会保留不可变 stream buffer，避免中间复制。慢速浏览器会在 WebSocket 队列超过 `maxBufferedBytes` 前断开；wire 解析器会限制输入大小、握手时间和 PTY 尺寸。共享终端操作队列会同步启动 idle 输入、在异步 provider 与查看方之间保持 FIFO 顺序，并让插件释放等待 quiescence。
+
+## 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---:|---|
+| `backendType` | `shell` | `open` 使用的 `ctx.terminals` 后端。 |
+| `maxInputBytes` | 65,536 | 单个客户端输入／控制帧的最大字节数。 |
+| `outputBatchBytes` | 65,536 | 立即刷新前可合并的最大输出字节数。 |
+| `outputBatchWindowMs` | 2 | 部分输出批次的 trailing idle 延迟。 |
+| `outputStreamThresholdMs` | 100 | 连续部分输出 burst 的最长持续时间。 |
+| `maxBufferedBytes` | 4,194,304 | 断开前允许的 WebSocket 队列上限。 |
+| `handshakeTimeoutMs` | 10,000 | 首帧截止时间。 |
+| `maxCols` / `maxRows` | 1,000 | 可接受的 PTY 尺寸上限。 |
+
+## 模型体验
+
+无，因为该浏览器传输不会增加模型可见的输入或输出。
+
+#### KV Cache 影响
+
+无；WebSocket 输入不经过模型请求。
+
+## 已知限制与暂缓事项
+
+- 终端字节与 attachment 仅存在于进程内；Host 重启会结束所有浏览器终端。
+- wire 发送未经应用层压缩的原始输出。
+- 一个 socket 只附加一个终端；多个查看方共享同一 PTY 时使用独立 socket，而不是在一个 socket 上复用多个 PTY。