PTY 会话管理 ch1bug/dsh-pty-session

dsh-pty-session

DSH 插件，把 harness 的 owner-scoped PTY seam（ctx.terminals —— @deepseek-ai/dsh-tool-bash-persistent 跑的就是同一个 seam）暴露成四个与协议无关的工具：pty_open / pty_send / pty_tail / pty_close。

Layer 0 核心：字节流会话，对协议零知识。行分帧、REPL 提示符、协议解析（gdb/MI、ssh banner）都归上层消费方插件，由它们在这层之上构建。

API

| 工具 | 参数 | 返回 | 说明 |
| pty_open | command（必填）、cwd?、env? | sessionId、pid?、status、initialOutput | 在 PTY 上启动进程；shell 类后端会在命令前导出 env 变量（POSIX 引号规则）。会话跨轮次存活。 |
| pty_send | id、data（必填）、submit?（默认 true） | delta、status | 写入字节；返回写入落定期间读到的输出。 |
| pty_tail | id（必填）、lines? | text、lines、truncated | 增量游标：只返回上次 tail 之后的新输出 —— 反复 tail 不会重发。积压超过 lines 时返回最新的若干行，并置 truncated: true。 |
| pty_close | id（必填） | closed | 干净终止 + 回收。每次 close 幂等。 |

生命周期与归属

- 每次调用都要对发起调用的智能体（exec.agent）鉴权；别的智能体碰你的会话会拿到 FOREIGN_SESSION。
- 会话随插件实例存活，不随轮次：同一智能体的新一轮能看到它所有打开的会话。
- 归属方智能体销毁时，owner-scoped 注册表会关掉它所有会话；插件另外装了一个 dispose effect，关掉自己打开过的每个会话。

值得知道的语义

- 按行，不按字节：pty_tail 沿用 seam 基于行的 scrollback 契约（totalLines/lineBegin/lineEnd）。没有结尾换行的输出（REPL 提示符、密码提示符）要等这一行完整了才可见。消费方真需要字节级精确 tail，那是消费层的活。
- pty_send 的 submit：默认 true（写完数据后由后端发 Enter），这样交互式会话才正常；要字节级精确写入就传 submit: false。
- pty_close 把终止交给 seam 的 await 式幂等清理（杀进程树 + 静默等待）—— 机制归 seam 管。
- env 是尽力而为的 POSIX export 行，只在 shell 类后端有意义（seam 的 spawn 请求没有 env 字段）；别对非 shell 后端传 env。

配置

backendType: shell # registered PTY backend type passed to terminals.spawn
tailLines: 200 # default pty_tail budget

消费方插件门面（ctx.pty）

消费方插件（dsh-embedded-debug T5，之后的 ssh）不走这四个工具 shell out —— 它们把同一套核心作为 cordis 服务注入：

const inject = ["tools", "pty"]; // add "pty" to the plugin's inject
// 在 apply(ctx) 内部：ctx.pty 由 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);

这层门面暴露 open/send/tail/close/dispose，语义与工具完全一致（同样的游标，同样的接缝读取——一套内核，两个表面）。owner 显式传入，必须用消费者自己的 exec.agent；接缝会校验归属（FOREIGN_SESSION）。close 是幂等的（会话已经消失时返回 closed:false）。任何注入 "pty" 的消费者，加载这个插件都会变成启动时的硬依赖。

实例矩阵

| 消费者 | 状态 | 原因 |
| gdb（dsh-embedded-debug T5/T6） | 首个消费者 —— 注入 ctx.pty | MI 分帧留在消费者侧；API 形态正被 gdb 的需求压出来。 |
| ssh | 计划中 —— 第二个消费者 | 等第二个消费者出现，再验证这层抽象。 |
| serial（tio）/ probe server / RTT | 明确排除 | 非 PTY 的长时间运行进程：job + tail 已经是正确做法。 |

开发

npm install # vitest
npm test # vitest run

测试就是参考实现：它们驱动真实的工具表面，打到一个假的 terminals 注册表上，而后端跑的是真实的交互式子进程（echo 往返，不做协议解析）。

Harness 依赖（重要）

@deepseek-ai/dsh-tools、@deepseek-ai/schemastery 和 @deepseek-ai/cordis 必须是指向已安装 harness 的 node_modules 的junction/符号链接（绝不要复制）：模块实例重复会让 DSH 插件加载器在入口处报 failed to import。Windows 上：

New-Item -ItemType Junction -Path node_modules/@deepseek-ai/dsh-tools -Target <harness>\node_modules\@deepseek-ai\dsh-tools
same for schemastery and cordis