better-dsh 0.2.5 → 0.3.0

package/docs/specs/remote-pty-label/spec.md

@@ -0,0 +1,126 @@
+# remote-pty-label Specification
+
+## Purpose
+
+`remote` 工具的持久化 BYO-PTY 通道从「`spawn` 命令原文即会话键」改为「`target` 选择器寻址的具名会话」。旧实现的池键就是整条 spawn 文本，于是「同一条命令」与「同一个会话」被绑死：改一个 token 就**静默**新开一个 shell（cwd/env 全丢、零提示），roster 又拿整整一条 shell 命令当会话名。本规格固定新契约——`byop:<label>` 是唯一入口、label 由调用方（模型）自选并因此成为复用入口、`spawn` 降格为该 label 首次创建时的伴生参数——并据此定义创建/复用/冲突三分支、失败面，以及裸名候选表的末位新增项。
+
+## Requirements
+
+### Requirement: 单入口寻址
+
+`target` SHALL 是 `remote` 工具的唯一分流入口。以 `byop:` 开头的 target SHALL 被解析为 PTY 选择器，冒号之后的全部内容为 label。`spawn` SHALL 仅在与 `byop:<label>` target 同时出现时合法——它不再是独立入口。
+
+#### Scenario: spawn 不能独立成调用
+
+- **WHEN** 调用只给 `spawn`（无 target，或 target 不是 `byop:` 选择器）
+- **THEN** 系统返回 `[E_PARAMS]` 并在消息内给出正确形状 `{ target: "byop:<label>", spawn: "…", cmd: "…" }`，且不创建、不触碰任何会话
+
+#### Scenario: label 字符集
+
+- **WHEN** label 不匹配 `^[A-Za-z0-9][A-Za-z0-9._-]*$`（空 label、含空白、含 `:` 等）
+- **THEN** 系统返回 `[E_BAD_LABEL]` 并在消息内给出合法形状，且不触碰会话池
+
+#### Scenario: PTY 选择器锁定 mode
+
+- **WHEN** `byop:<label>` target 与显式 `mode:"oneshot"` 同时出现
+- **THEN** 系统返回 `[E_BAD_MODE]`，而不是静默降级或静默改写 mode
+
+### Requirement: label 即复用入口，命名空间按 agent 隔离
+
+PTY 会话 SHALL 以 `` `${agentSessionKey}|p:${label}` `` 为池键。`spawn` 原文 SHALL 作为创建来源（origin）随会话保存，仅用于同 label 重复给 spawn 时的比对。label 首次创建之后，仅给 `{ target: "byop:<label>", cmd }` SHALL 复用该会话，cwd/env 存活。
+
+#### Scenario: 创建后仅凭 label 复用
+
+- **WHEN** 先调用 `{target:"byop:dev3", spawn:"bash", cmd:"cd /tmp && export MARK=live"}`，再调用 `{target:"byop:dev3", cmd:'echo "$MARK" && pwd'}`
+- **THEN** 第二次调用在**同一个** shell 内执行，输出含 `live`、cwd 为 `/tmp`，且结果带 `session: "byop:dev3"`
+
+#### Scenario: 两个 agent 的同名 label 互不可见
+
+- **WHEN** agent A 创建了 `byop:dev3`，agent B 以同一 label 且不给 spawn 调用
+- **THEN** B 得到 `[E_NO_SESSION]`，A 的会话不受任何影响
+
+### Requirement: 同 label 重复 spawn 的三分支
+
+对已存在的 label 再次给 `spawn` 时，系统 SHALL 将其与创建来源比对：相同即复用并在结果内附教学提示；不同即拒绝，且 SHALL NOT 执行任何命令。
+
+#### Scenario: 同一 spawn → 复用 + 提示
+
+- **WHEN** 对活着的 `byop:dev3` 再次传入与创建时逐字相同的 `spawn`
+- **THEN** 调用在既有会话内执行，结果的 `notice` 说明该 PTY 是持久化的、后续可省略 `spawn`（只写 label）
+
+#### Scenario: 不同 spawn → 冲突，什么都不跑
+
+- **WHEN** 对活着的 `byop:dev3` 传入与创建时不同的 `spawn`
+- **THEN** 系统返回 `[E_LABEL_CONFLICT]`，消息内含既有 spawn 原文与「丢掉 spawn 复用它 / 换一个 label 新建」两条出路，**cmd 不执行**，既有会话状态不变
+
+### Requirement: 无会话面 fail-loud 且不保留 spawn
+
+label 从未创建、或已被 idle TTL（默认 600s）回收时，不带 `spawn` 的调用 SHALL 返回 `[E_NO_SESSION]`。spawn 命令 SHALL NOT 被跨会话保留（无墓碑、无自动重建）。
+
+#### Scenario: 回收后必须重贴 spawn
+
+- **WHEN** `byop:dev3` 因 idle TTL 出池后调用 `{target:"byop:dev3", cmd:"echo hi"}`
+- **THEN** 系统返回 `[E_NO_SESSION]`，消息内给出带 `spawn` 的重建形状，并说明 spawn 未被保留
+
+### Requirement: 初始化失败不留任何东西
+
+首建命令未能初始化（`[E_SESSION_DIED]` / `[E_SESSION_START]`）时，该 PTY 会话 SHALL 出池：label 与 TTY SHALL NOT 被建立——这里从来没有过一个可用会话。**已 ready 过**的会话死亡 SHALL 留在池内（那是 reconnect 语义），不受本需求约束。
+
+#### Scenario: 失败的 spawn 之后 label 仍然自由
+
+- **WHEN** `{target:"byop:x", spawn:"…", cmd:"…"}` 的首建命令未能初始化
+- **THEN** 随后不带 spawn 的复用得到 `[E_NO_SESSION]`（而非重跑冻结的 argv 再失败一次），且带**任意** spawn 的调用 SHALL 正常新建——不得被创建来源比对拦成 `[E_LABEL_CONFLICT]`
+
+#### Scenario: 已 ready 的会话死亡仍可重连
+
+- **WHEN** 一个曾经初始化成功的 `byop:<label>` shell 死亡后被复用
+- **THEN** 该会话留在池内、按原创建命令重连并附 reconnect 提示
+### Requirement: 状态面与 roster 以 label 呈现
+
+`{target:"byop:<label>"}`（无 cmd）SHALL 只读池内状态、零拨号。roster SHALL 以 `byop:<label>` 命名会话，SHALL NOT 泄露 spawn 命令。
+
+#### Scenario: 探测不存在的 label
+
+- **WHEN** 对无会话的 `byop:<label>` 做 status 调用
+- **THEN** 返回 `session: none — no live PTY under this label`（不是 transport target 的 "dials on first exec"，也不报错）
+
+#### Scenario: roster 只给 label
+
+- **WHEN** 调用方自己以 `UNIQUESPAWNMARKER bash` 创建了 `byop:dev3`
+- **THEN** roster 包含 `live pty sessions: byop:dev3`，且文本中不出现 `UNIQUESPAWNMARKER`
+
+### Requirement: roster 的活性面按 agent session 作用域
+
+「live pty sessions」段 SHALL 只列调用方 agent session 自己的会话（池键前缀 = 调用方 sessionKey）。`ssh hosts` / `docker containers` / `incus containers` 三段名字候选 SHALL 保持全局可见。理由：名字候选是**静态公共配置**（谁都能 `ssh dev4`），活会话却是**操作环境**——复用别的 agent 留下的 shell 等于继承未知状态，而两个 agent 各开一条线的代价可忽略。BYO-PTY 天然是活的，因此自然落进这个 scope，无需另立规则。
+
+#### Scenario: 两个 agent 各自只看见自己的活会话
+
+- **WHEN** agent `a1` 建了 `byop:mine`、agent `a2` 建了 `byop:theirs`，随后各自调 `{}`
+- **THEN** `a1` 的 roster 含 `byop:mine` 且不含 `byop:theirs`（反之亦然），而两边 `ssh hosts` / `docker containers` / `incus containers` 三段内容相同
+### Requirement: 模型面不得泄露池内部键
+
+面向模型的文本（roster、status、错误消息）SHALL 只出现模型面名字（`byop:<label>`、裸 transport target），SHALL NOT 出现池键（`` `${agentSessionKey}|p:<label>` `` / `|t:<target>`）。key→名字 SHALL 是单一定义（`displayKey`），roster 与错误面共用同一条规则。
+
+#### Scenario: 初始化失败的错误消息
+
+- **WHEN** agent `sess-abc` 的 `byop:x` 初始化失败
+- **THEN** 错误消息含 `'byop:x'`，且不含 `sess-abc`、不含 `|p:`
+
+### Requirement: 裸名候选表末位新增 PTY label
+
+裸名解析顺序 SHALL 保持 ssh config 字面 host → docker → incus **一位不挪**，并在这三段之后、ssh 兜底之前追加「池内活 PTY label」候选。该候选 SHALL 仅在调用面未显式指定 `mode:"oneshot"` 时参与匹配。命中顺序即优先级：同名冲突时更靠前的来源胜出。
+
+#### Scenario: 无重名时裸 label 可达（懒复用）
+
+- **WHEN** 池内有 `byop:lab`，ssh config / docker / incus 均无 `lab`，且调用 `{target:"lab", cmd:"…"}`（未指定 mode）
+- **THEN** 调用落在该 PTY 会话上（mode 为 `pty`），结果 `session` 为 `"byop:lab"`
+
+#### Scenario: 重名时 ssh host 优先
+
+- **WHEN** ssh config 存在 `Host lab`，同时池内有 `byop:lab`
+- **THEN** 裸名 `lab` 仍解析为 ssh transport（现有优先级逐位不变）；要进 PTY 通道必须显式写 `byop:lab`
+
+#### Scenario: 显式 oneshot 不吃 PTY 候选
+
+- **WHEN** 调用显式带 `mode:"oneshot"` 且 target 为裸名
+- **THEN** 该调用不走 PTY 末位候选，裸名在 `mode:"oneshot"` 下的旧行为逐位保留

package/docs/specs/welcome-self-contained/spec.md

@@ -0,0 +1,13 @@
+# Super Dash 自包含 Better Dash 与 DSH 默认策略
+
+2026-10-07 user 裁决：两仓物理独立；Super Dash 每次打包都构建兄弟仓当前 Better Dash 源码，内嵌本地实际产物，不从 registry 取 Better Dash；WebTrust、dev WebMCP、webserver 默认监听及 onboarding/welcome 策略归 Better Dash。
+
+- Better Dash 独立 build/pack；Super Dash 用 npm bundledDependencies 内嵌该本地 tarball 展开的物理包。依赖版本 exact-pin 与源包一致。
+- Super Dash bundle 的有序 patch 文件先读取内嵌 Better Dash YAML，再读取自己的 YAML；消费者 profile 只声明 Super Dash，不单独声明 Better Dash。
+- Better Dash 的 WebTrust 默认组合启用 authentication-only，保留 native cookie 校验；Super Dash 删除重复实现及相关覆盖。
+- Better Dash 禁用原生 webserver 行、以独立 dashr-webserver 行继承原生 Service，并在监听前等待 welcome entry；默认 host 0.0.0.0，保留原生 port/压缩/CLI 配置机制；测试 launcher 默认仅覆盖 4999 端口，不再提供消费包未有的默认 host。
+- Better Dash 关闭 credentialOnboarding，人工模型配置保持可用。
+- `dashr-welcome-notice` 是可单行 disabled 的 Host entry：从实际安装锚的 Models 客户端读取当前 WELCOME_NOTICE_VERSION，经官方 internal/config 与 Entry.update 将确认同步投到原 ui-settings-general，不替换 Models UI，不写死版本，不用客户端 localStorage 假确认。
+- 静态私有常量没有公开 API；普通版本 bump 自动生效，符号/产物结构变化必须显式报错，不能静默保留旧版本。
+- dev WebMCP 移归 Better Dash 仓的开发测试目录，不进入正式插件 tarball；联合 launcher 仅将其作为开发附加 bundle。
+- 真实 tarball 安装、登录、native eval/create/prompt/resume、roster、首次 settings 快照、热禁用恢复为本轮验收；浏览器连接与 dev3 按可用环境如实记录。4999 保持运行。无 npm publish、commit/tag/push、上游或生产修改。

package/docs/specs/zero-npm-runtime-deps/spec.md

@@ -0,0 +1,85 @@
+# better-dsh 归零 npm 运行时依赖（zero-npm-runtime-deps）
+
+状态：**已完成**（round 1–4 全部落地并实测；发布待 user 放行） ｜ 规格路径：`docs/specs/zero-npm-runtime-deps/spec.md`（仓库根 docs；`better-dsh/docs/` 是 `prebuild` 由 `../docs` 重建的产物，别写那里）
+
+## 0. 动机（实证）
+
+一次 DSH UI Plugin Manager 安装的真实日志：
+
+```
++ better-dsh 0.2.5-a
+Packages: +15 -71
+node_modules/zeromq install$ node ./script/install.js     ← 我们的 REPL 原生依赖，cmake 构建
+Done in 3.7s using pnpm v11.7.0
+[WARN] GET …/@oven/bun-linux-aarch64-android/-/…-1.4.2.tgz error (UND_ERR_SOCKET). Will retry in 10 seconds.
+dsh: pnpm printed nothing for 600000ms and was terminated
+```
+
+1. **卡住的东西不是 better-dsh 的**：`bun@1.4.2`（12 个平台包，各 ~86 MB）来自同一 profile 的 `super-dsh@0.1.9`。DSH 把插件 profile 设计成**一个共享 pnpm 工程**，于是"装插件 X" = "重解整个 profile"（`Packages: +15 -71` 是指纹）。
+2. **失败形态是超时、不是构建错误**：Plugin Manager 对每条捕获输出的 pnpm 运行挂 600000 ms 静默上限（`packages/boot/plugin-manager/src/index.ts:184`），超时杀树并打印 `operations.ts:453` 那句；真正的错误只是一条被吞掉的 WARN。
+3. **我们自己也在这条链上**：`zeromq@6.6.0` 是硬 `dependencies`，其 install 脚本用 cmake-ts 现场编译；`src/kernel.ts:20` 是**顶层静态 import**，该原生模块一旦拿不到，**整个插件加载死**（不只是 REPL）。`docs/specs/kernel-provisioning` 的三级自愈只覆盖 Python venv。
+
+user 裁决（2026-10-03）：**不要 declare 任何运行时依赖，不要 postinstall，不要碰 Node 包管理器**；二进制由我们自己的代码在 spin-up 自检与首次使用 lazy 时自装；装不上就那个组件不可用，其他组件照常。
+
+## 1. 目标态（硬契约）— ✅ 已达成
+
+- `package.json`：`dependencies` / `optionalDependencies` / `scripts.postinstall` **全部不存在**；60 条 `peerDependencies` 保留（harness 契约，由 loader 安装域供给）。真实安装器实测 `Packages: +1`（只加自己）。
+- 运行时需要的一切只有两条出路：**构建期进产物**（tsdown `noExternal` 内联；资产随 `files`）或**运行期自装到插件自管目录**（不调用 npm/pnpm/npx）。
+- 供给触发点只剩：**守护进程 spin-up 自检** + **首次使用 lazy**。
+- **fail-open 硬要求**：任何一项失败只让该组件不可用，插件整体加载与其余组件零影响。
+
+## 2. 逐依赖处置与进度
+
+| 依赖 | 用户 | 处置 | 状态 |
+|---|---|---|---|
+| `diff` | hashline `edit-diff.js` | tsdown `noExternal` 内联 | ✅ 已内联（`//#region node_modules/diff/...` 实证），已从 `dependencies` 移除 |
+| `xxhash-wasm` | hashline `hash-assign.js` | 同上（wasm 在 esm 构建里已内联为 `Uint8Array`，无外部资产） | ✅ 已内联，已移除 |
+| `file-type` | hashline `file-view.js`（A/B 实测：该调用点在**改动前就已被 tree-shake**，产物里只剩一条裸 `import "file-type"`） | 直接移除；内联与否不影响运行时 | ✅ 已移除 |
+| `use-sync-external-store` | client 半 | client 构建早已 `noExternal` 内联（产物零引用实证） | ✅ 已移除 |
+| `puppeteer-core` | `dvc://browser`（`await import()`） | 构建期内联（`lib/puppeteer-core-*.js`，206 导出）；实测拉起系统 Chrome 成功；保留 vendor 自装兜底 | ✅ 已移除声明 |
+| `zeromq` | REPL `src/kernel.ts:20` 静态 import | 删除；传输层改 venv 内 Python bridge | ✅ 已删除（`dependencies` 现只剩 `puppeteer-core`；Node 产物零 zeromq 引用） |
+| `@oh-my-pi/pi-natives-<platform>` | AST（`natives-loader.ts` 已 fail-open） | `ensurePiNatives()` 首用自装到 `<packageRoot>/.vendor`；加载器 vendor 精确查找 + 锚点有界 | ✅ 已移除声明，实测通过 |
+
+`scripts.postinstall`：✅ 早已不存在（0.2.2-a 起零 lifecycle script）——本次要消灭的是**依赖带进来的 install script**（zeromq）。
+
+## 3. REPL 传输层重写（round 2 已落地，待 4999 复测）
+
+现状：Node 是 Jupyter 客户端，用 `Dealer`/`Subscriber` 直连 ipykernel 的 shell/iopub/control（`src/kernel.ts:249-344`）。
+
+目标：
+
+```
+Node(TS) ──stdio JSON lines──► bridge.py（venv python + pyzmq/jupyter_client）──ZMQ──► ipykernel
+```
+
+- `pyzmq` / `jupyter_client` 由 `ipykernel` 传递依赖保证在场（实证：`.venv-kernel/lib/python3.11/site-packages/zmq`）。
+- 保留语义：cell 串行、iopub 流式、control 中断 + SIGALRM 升级、超时/dispose 时序、comm（host 请求桥）。
+- Node 侧不得再出现 zeromq/原生 socket；venv 未就绪时 `dashr-repl` 行**不抛**，标为未就绪。
+
+## 4. 供给阶梯（改造后）
+
+1. **守护进程 spin-up 自检**（主路径；`resolveKernelEnv` 已有，新增 bridge 可启动检查）。
+2. **首次使用 lazy**（兜底）。
+3. ~~postinstall~~ 不存在。
+
+## 5. 验收（对齐"改动点同类"红线）
+
+- 清单零 `dependencies`/`optionalDependencies`/`postinstall`；`npm pack` 后 tarball 自足。
+- 断网/无 npm：`dsh plugin add <tarball>` 成功、插件加载成功、REPL 由 venv 自足跑通一次真实 `eval`。
+- 无 zeromq 时：插件加载正常、其余组件全可用、只有 REPL 在缺 venv 时明确报"未就绪"。
+- 4999 第一人称实测 + 报告落 `docs/50_test-reports/`。
+- 发布仍需 user 明确放行。
+
+## 6. 已知风险
+
+- `puppeteer-core` 打包兼容性（动态 require / `import.meta`）未验。
+- Python bridge 多一跳后的中断/流式时序（SIGALRM 升级路径最敏感）。
+- 自装代码自担：版本钉死、sha512 校验、平台探测、并发去重、代理/离线行为。
+
+## 7. 进展日志
+
+- **round 1（2026-10-03）**：`tsdown.config.ts` 增 `BUNDLED_RUNTIME` + `noExternal`（含 `file-type` 的纯 JS 闭包：`@borewit/text-codec`/`@tokenizer/*`/`debug`/`ieee754`/`strtok3`/`token-types`/`uint8array-extras`）；`package.json` 的 `dependencies` 从 6 项降到 2 项（只剩 `puppeteer-core`、`zeromq`）。验证：`npm run build` 通过；产物内联 `diff` + `xxhash-wasm`，除 `puppeteer-core`/`zeromq` 外无任何外部包引用；全量单测 **649 passed / 1 skipped**。
+- 顺手发现：`better-dsh/docs/` 是构建产物（`scripts/copy-docs.mjs` 会 `rmSync + cpSync ../docs`），规格必须写在仓库根 `docs/`。
+- **round 4（2026-10-03）**：清单归零并接线自装器。`vendor.ts` 增 `VENDOR_ROOT = <packageRoot>/.vendor`；`natives-loader` 增 `ensurePiNatives()`（首用 lazy；显式 anchor 永不 provision）+ vendor 精确查找；`ast-device` 两处调用点 `await nativesOrThrow()`；`browser-device.loadPuppeteer()` 失败时走 vendor。删 `dependencies` + `optionalDependencies`（顺带修掉 round 2 我引入的重复 `puppeteer-core` 键）。实测：**`Packages: +1`**；puppeteer 内联后成功 `launch()` 系统 Chrome（`BUNDLED_PUPPETEER_OK`）；`dsh headless` 让 agent 走 `dvc://ast_grep` → `totalMatches 3 / files 2 / searched 189`，同时 `<plugin>/.vendor` 出现 314MB pi-natives，而 **profile 树里无 `@oh-my-pi`**（证明自装生效）；全量单测 **649 passed / 1 skipped**。报告：`docs/50_test-reports/2026-10-03-zero-npm-runtime-deps实测报告.md`。
+- **round 3（2026-10-03）**：① 新传输最后一条未验路径打通：`/tmp/smoke-comm.mts` 走通 host-request comm（内核 `create_comm('dashr.host')` → iopub → Node → **control** 通道 `comm_msg` 回包 → 内核 control-thread handler 解 future），cell 打印 `HOSTREPLY {'pong': True, ...}`。② **4999 第一人称实测**：新 tarball 装进 rig 的 web + headless profile（物理树里 **`zeromq` 已消失**），`dsh headless` 真实 session：`eval` 跑出 `REPL_OK 42`，同一 Python session 内 `await tool.bash({...})` 拿回 `HOST_OK\n`（宿主参数校验失败路径也顺带被触发），启动日志零错误、composed tree 含 `dashr-repl`。③ 新增 `src/vendor.ts`——零依赖自装器（registry packument → sha512/shasum 校验 → 自写 tar+pax 解包 → `createRequire` 解析入口 → 递归依赖闭包 + os/cpu/libc 平台过滤 → staging+rename 原子落盘）。实测：provision `@oh-my-pi/pi-natives-linux-x64@18.0.6`（2×163MB `.node`）并 **dlopen 成功**（exports `astGrep`/`astEdit`/…），二次调用 reuse。④ 注意：`better-dsh-0.2.5*.tgz` 是**入库的** rig 交付物，本轮为实测重新打包覆盖。
+- **round 2（2026-10-03）**：REPL 传输层换成 venv 内 Python bridge。新增 `src/kernel-bridge.py`（stdio JSON lines ↔ pyzmq/jupyter_client；`default=str` 序列化，避免 header 的 `datetime` 打死 pump 线程）与 `src/kernel-transport.ts`（spawn/readline/`waitFor`/`onExit`）；`kernel.ts` 删掉 `import { Dealer, Subscriber } from 'zeromq'`、`DELIM`/`encode`/`decode`/socket 字段/iopub pump，改由 `handleTransportMessage` 路由。`scripts/copy-kernel-bridge.mjs` 把 .py 拷进 `lib/`（`files: [lib]` 覆盖），`build` 链尾追加。验证：`tsc --noEmit` 0 错；全量产物零 `zeromq`；真实 ipykernel 冒烟通过（kernel_info ✅ / `print("SMOKE",6*7)` → `"SMOKE 42\n"` ✅ / 到 idle ✅ / **KERNEL_BOOTSTRAP 单元执行无错** ✅ / interrupt ✅ / dispose ✅）。⚠ 尚未经新传输验证的路径：host-request comm（内核侧 `dashr.host` → Node `serveHostRequest` → control 通道 comm_msg 回包），留给 4999 实测。