dsh-computers 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# dsh-computers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把你自己电脑（Mac / Windows / Linux）接到一个 **DSH Web** 部署上，让部署里的智能体在这些电脑上执行 shell 命令。
+
+形态是「**一台服务器作为唯一主控，其余电脑作为被控端接进来**」：被控端只向外发起一条长连接，主控端负责注册表、在线状态和命令派发。
+
+- **每台电脑都装同一个插件**，所以不需要在终端里粘命令：桌面端 DSH 打开 设置 → 电脑 → **本机运行时**，填服务器地址 + 加入密钥，点「连接」即可。
+- 服务器那一侧是 **电脑** 列表：在线状态、重命名、删除，以及 `+ 连接电脑` 生成的兜底命令（给不装 DSH 的机器，比如跑 launchd/systemd 的 Mac mini、Linux 服务器）。
+- 对话里智能体用 `computer_exec` 把命令派到指定电脑上跑，用 `computer_list` 看有哪些机器。
+
+**没有内网穿透、没有开放端口**：被控端只向外发起一条 SSE 长连接，所以两台 Mac 在 NAT/家用网络后面也能连上。拓扑明确是 hub-and-spoke，**不支持**电脑之间互相控制，也不做 P2P。
+
+```
+┌──────────── 服务器（dsh web，role: hub）────────────┐
+│ dsh-computers 插件                                  │
+│  · 电脑注册表 + SSE hub + 命令派发                  │ ◀──SSE──── ┌─ 这台 Mac（桌面端 DSH + 插件）─┐
+│  · computer_list / computer_exec 工具               │ ──命令──▶ │  设置 → 电脑 → 本机运行时      │
+│  · 设置 → 电脑 列表 + 连接电脑                      │ ◀─结果─── │  连接后即成为被控端            │
+└─────────────────────────────────────────────────────┘           └───────────────────────────────┘
+        ▲ 浏览器（手机/笔记本都能控制全部电脑）          ◀──SSE──── ┌─ 另一台 Mac / Linux ──────────┐
+        │                                                          │  同样装插件，或跑 agent 兜底   │
+        └─────────────────────────────────────────────────────────┴───────────────────────────────┘
+```
+
+## 1. 服务器：装插件（主控）
+
+插件是纯 JavaScript，无构建、无第三方依赖，直接从 GitHub 装：
+
+```bash
+# 方式 A：CLI（推荐用分支，不用 tag，见下面「更新」）
+dsh plugin install github:9Ashwin/dsh-computers
+
+# 方式 B：DSH 设置 → 插件市场 → 安装，粘贴
+#   https://github.com/9Ashwin/dsh-computers
+```
+
+### 更新
+
+GitHub 安装的插件在 profile 里是**按 spec 固定**的（`github:user/repo` 或 `github:user/repo#v1.0.2`，lockfile 会钉到具体 commit），所以：
+
+- **装 tag（`#v1.0.2`）= 冻在那个版本**，插件市场的「检查更新」永远发现不了新版本。
+- **装分支（不带 `#`）= 可更新**：插件市场 → 已安装 → 「检查更新」会重新解析分支 HEAD 并自动重装，不需要手动卸载。
+- 手动更新时**必须换 spec 才会生效**：用同样的 spec 再装一次只会得到 `already-installed`（这就是"再安装没法更新"的原因）。要升级到某个新版本，直接装新 tag：
+  ```bash
+  dsh plugin install github:9Ashwin/dsh-computers#v1.0.2
+  ```
+  或者先移除再装；种 spec 变了才会真正重新拉取。
+
+装好后重启 `dsh web`，设置里会出现 **电脑** 页。
+
+服务端建议把 `role` 固定成 `hub`（只当主控）。**对外地址会自动识别**：你从哪个域名打开设置页（含反向代理的 `X-Forwarded-Proto/Host`、`Forwarded` 头），生成的命令就用哪个地址，通常不用配。需要强制指定时才写 `publicUrl`：
+
+```yaml
+# ~/.dsh/profiles/<profile>/cordis.patch.yml
+- id: dsh-computers
+  name: dsh-computers
+  config:
+    role: hub
+    # 留空 = 按浏览器请求自动推导（含反代的 X-Forwarded-* / Forwarded）；
+    # 只有不想信任代理时才显式写死，例如 https://dsh.example.com
+    publicUrl: ''
+    execEnabled: true          # false 时拒绝所有远程执行
+    execTimeoutMs: 120000      # 单条命令默认超时
+    keyTtlMinutes: 15          # 加入密钥有效期
+```
+
+> **安全前提**：请开启 DSH 的浏览器登录/可信来源（`dsh web` 默认就有），不要把裸端口暴露给公网。插件给"能使用这个 DSH 的智能体"的权限，等于能在这台电脑上执行任意命令。
+
+## 2. 每台电脑：装同一个插件（被控）
+
+1. 按上一节的方式在**这台电脑**的 DSH 里装上 `dsh-computers`（桌面端 / 命令行装法相同）。
+2. 打开 DSH → 设置 → 电脑，在 **本机运行时** 卡片里填：
+   - **服务器地址**：你服务器的对外地址，如 `https://dsh.example.com`
+   - **加入密钥**：在服务器的 设置 → 电脑 → `+ 连接电脑` 里复制的 `dshc_…`
+3. 点 **连接**，卡片变成「运行中」，服务器列表里随即出现这台电脑（在线）。
+
+被控端默认 `role: both`，所以这台电脑自己也能当主控；只想当被控端就设 `role: runtime`。
+
+运行时的开关是持久的：**DSH 一启动就自动连回服务器**，不用每次手动点。关掉 DSH 就离线。
+
+### 兜底：不装 DSH 的机器
+
+Mac mini 常驻、Linux 服务器这类不跑桌面的机器，用服务器生成的命令（launchd / systemd 常驻）：
+
+```bash
+curl -fsSL 'https://<你的服务器>/api/dsh-computers/join.sh?key=dshc_xxx' | sh
+```
+
+它会下载 agent 到 `~/.dsh-computers/`、注册系统服务并启动。手动管理：
+
+```bash
+node ~/.dsh-computers/agent.mjs status
+node ~/.dsh-computers/agent.mjs service restart
+node ~/.dsh-computers/agent.mjs service uninstall
+tail -f ~/.dsh-computers/agent.log
+```
+
+## 3. 对话里怎么用
+
+智能体会看到两个工具：
+
+- `computer_list` —— 列出已连接电脑（名字、平台、在线状态）
+- `computer_exec` —— 在指定电脑上执行命令：`{"computer": "my-mac-mini.local", "command": "sysctl -n hw.memsize"}`
+
+系统提示里会自动附上当前电脑清单，所以直接说「看看两台 mac 的内存」它就会分别调用。
+
+## 4. 端点一览
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/dsh-computers/agent/enroll` | 加入密钥换取电脑 token（runtime 卡片也走这里） |
+| GET | `/api/dsh-computers/agent/events` | 被控端的 SSE 长连接（Bearer token） |
+| POST | `/api/dsh-computers/agent/results` | 命令执行结果回传 |
+| POST | `/api/dsh-computers/agent/heartbeat` | 心跳 |
+| GET | `/api/dsh-computers/state` | 设置页数据（角色、电脑列表，需要浏览器会话） |
+| POST | `/api/dsh-computers/keys` | 生成一次性加入密钥 |
+| GET | `/api/dsh-computers/key-status` | 弹窗轮询用 |
+| POST | `/api/dsh-computers/delete` / `rename` | 删除 / 重命名电脑 |
+| GET | `/api/dsh-computers/runtime` | 本机运行时状态 |
+| POST | `/api/dsh-computers/runtime/connect` / `enable` / `disconnect` | 连接 / 启用开关 / 断开本机运行时 |
+| GET | `/api/dsh-computers/join.sh` | 兜底安装脚本 |
+| GET | `/api/dsh-computers/agent.mjs` | agent 本体（兜底脚本下载） |
+| GET | `/api/dsh-computers/health` | 健康检查 |
+
+浏览器端点都先过 DSH 的请求闸门（`connection.requestRejection`），未登录/不可信来源直接拒绝；被控端端点用 Bearer token 认证（服务端只存 `sha256(token)`）。
+
+## 5. 开发与验证
+
+```bash
+node scripts/host-smoke.mjs     # Host 半：真实 HTTP 监听 + 假 agent/hub，覆盖注册/SSE/exec/超时/runtime
+node --test agent/test/         # agent 半：enroll / SSE / exec / 超时 / 截断 / 内嵌运行时
+node --check client.js          # 浏览器半
+```
+
+协议细节（所有路由、SSE 事件、状态文件、工具 schema、runtime 契约）见 [PROTOCOL.md](./PROTOCOL.md)。
+
+## 6. 已知限制
+
+- 一次执行返回一次性结果（不流式），长命令靠 `timeoutMs`；输出单流上限 1 MiB。
+- 一台电脑同一时刻只保留一条连接（新的会顶掉旧的）。
+- 在线判定只看 SSE 是否存活：杀掉进程立刻离线；网络静默（无 FIN）最多差一个心跳周期。
+- Windows 被控端目前可用 `node agent.mjs run` 手动运行，服务安装只覆盖 macOS/Linux。
+- 电脑与 Bot 的绑定还没有（列表里的 `1/1 Bot` 是占位徽标）；v1 里所有电脑对智能体都可选。
+- 不做 P2P / 电脑互控；要隔离环境请用 VPN，或把某台桌面端当 hub、另一台连过去（仍是单向）。
+
+## License
+
+MIT

package/agent/README.md

@@ -0,0 +1,276 @@
+# dsh-computers-agent
+
+The machine-side half of **dsh-computers**: a single, dependency-free Node.js
+script that runs on your own Mac/Linux box, dials **out** to a DSH Web server,
+and executes shell commands the server's agent asks for. It is the "cloud
+computer" client — no inbound port, no NAT/firewall change, no daemon port.
+
+```
+dsh web  ──SSE (outbound from the Mac)──▶  dsh-computers-agent  ──▶  /bin/sh -lc
+                                            │
+                                            ├─ ~/.dsh-computers/config.json  (0600, token)
+                                            ├─ ~/.dsh-computers/agent.log    (5 MiB rotate)
+                                            └─ launchd / systemd user service
+```
+
+The same file is used two ways, with one implementation:
+
+- **CLI / service** (headless, always-on): `enroll` + `run` + `launchd`/`systemd`
+  from the installer one-liner.
+- **Embedded runtime** (desktop DSH app): the plugin's Settings → 电脑 →
+  *本机运行时* card calls the module's exported `startRuntime()` in-process, so
+  the user never opens a terminal (PROTOCOL §10.4).
+
+The file is served verbatim by the host plugin at
+`/api/dsh-computers/agent.mjs`, so what you run is exactly what the repository
+contains. It imports only Node built-ins, never opens a listening socket, and
+never prints the token.
+
+The wire contract lives in [`../PROTOCOL.md`](../PROTOCOL.md) (§3 and §6).
+
+## Requirements
+
+- Node.js **22 or newer** (`node -v`)
+- macOS (launchd), Linux (systemd `--user`) or Windows (manual, v1)
+- Outbound HTTP(S) to the dsh-web server
+
+## Install
+
+### Recommended: the one-liner from Settings → 电脑
+
+The server's **Connect computer** dialog generates a command like:
+
+```sh
+curl -fsSL 'http://<server>/api/dsh-computers/join.sh?key=dshc_…' | sh
+```
+
+It downloads this script to `~/.dsh-computers/agent.mjs`, enrolls with the
+one-time key, installs the login service, and starts it.
+
+### Manual
+
+```sh
+mkdir -p ~/.dsh-computers
+curl -fsSL 'http://<server>/api/dsh-computers/agent.mjs' -o ~/.dsh-computers/agent.mjs
+node ~/.dsh-computers/agent.mjs enroll --server http://<server> --key dshc_…
+node ~/.dsh-computers/agent.mjs service install
+node ~/.dsh-computers/agent.mjs service start
+```
+
+Enrollment keys are single use and expire (15 minutes by default). When the
+server says the machine is already connected, re-run with `--replace`:
+
+```sh
+node ~/.dsh-computers/agent.mjs enroll --server http://<server> --key dshc_… --replace
+```
+
+> A successful `enroll` prints `✓ 已连接 <server>，这台电脑现在是 <name>`.
+> If the stream probe fails, the credentials are still saved and `run` retries.
+
+## Commands
+
+```
+dsh-computers-agent enroll --server <url> --key <key> [--name <name>] [--replace]
+dsh-computers-agent run
+dsh-computers-agent service install|uninstall|start|stop|restart|status
+dsh-computers-agent status
+dsh-computers-agent --version | --help
+```
+
+| Command | What it does |
+| --- | --- |
+| `enroll` | POSTs the join key to `/api/dsh-computers/agent/enroll`, saves `{serverUrl, computerId, token, name, enrolledAt}` to `config.json` (atomic, `0600`), then opens the SSE stream for ~5 s to prove the round trip. Exits non-zero with the server's message on failure. |
+| `run` | Foreground worker: one SSE stream to `/api/dsh-computers/agent/events`; executes `exec` events, kills the process group on `cancel`, POSTs results, sends heartbeats, reconnects with jittered 1 s → 30 s backoff. |
+| `status` | Prints server, computer id/name, redacted token (last 6 chars only), config/log paths and service state. Exit `0` when enrolled, `1` when not. |
+| `service` | Login/auto-restart service. See below. |
+
+Ctrl-C / `SIGTERM` makes `run` exit cleanly (in-flight commands are killed).
+
+## The service
+
+**macOS (launchd).** `service install` writes
+`~/Library/LaunchAgents/com.dsh.computers.agent.plist` with
+`ProgramArguments = [node, <absolute agent path>, run]`, `RunAtLoad`,
+`KeepAlive`, and `StandardOutPath`/`StandardErrorPath` pointing at
+`~/.dsh-computers/agent.log`. `service start` runs
+`launchctl bootstrap gui/$(id -u) <plist>` and falls back to `launchctl load -w`.
+`stop` uses `launchctl bootout` (fallback `unload -w`). `stop` and `uninstall`
+are idempotent: when nothing is loaded they still exit `0`.
+
+**Linux (systemd `--user`).** `service install` writes
+`~/.config/systemd/user/dsh-computers-agent.service`, runs
+`systemctl --user daemon-reload`; `start` runs
+`systemctl --user enable --now ...`; `stop` runs `disable --now`. Without a
+usable `systemctl --user`, `start`/`stop` fall back to `nohup … run &` with a
+pid file (`~/.dsh-computers/agent.pid`).
+
+**Windows.** v1 prints the manual command and the Task Scheduler setup and exits
+`0` (no service automation yet).
+
+## Embedded runtime mode (`startRuntime`)
+
+When the plugin runs inside the user's **desktop** DSH, `lib/runtime.js` imports
+this same file and starts an in-process runtime — no CLI, no service, no
+`~/.dsh-computers` config:
+
+```js
+import { startRuntime } from '../agent/dsh-computers-agent.mjs'
+
+const runtime = startRuntime({
+  serverUrl: 'https://dsh.example.com',
+  token: 'dshc_…',            // from the hub's enroll response
+  computerId: 'cmp_…',
+  name: 'Desk Mac mini',      // optional display name
+  heartbeatMs: 20000,         // optional; `hello` overrides it
+  log: (level, message) => {}, // 'info' | 'warn' | 'error'
+  onState: (state) => {},      // connect/disconnect/error/stop transitions
+})
+
+runtime.status() // synchronous snapshot (see below)
+await runtime.stop() // idempotent: aborts SSE, SIGKILLs children, awaits the loop
+```
+
+`status()` returns
+`{ running, connected, serverUrl, computerId, name, heartbeatMs, since, lastConnectedAt, lastError, attempts, exitCode }`
+(`since`/`lastConnectedAt` are ISO strings; `lastError` is `null` when healthy).
+`onState` receives the same shape and is de-duplicated to real transitions.
+
+Semantics guaranteed to the host:
+
+- `startRuntime()` returns immediately; the SSE loop/backoff runs in the
+  background. The module is **import-safe**: importing it never runs CLI code,
+  touches the filesystem, prints, or starts child processes (the CLI main only
+  runs when this file is the process entry point, via `process.argv[1]` +
+  `pathToFileURL`, handling relative and symlinked paths).
+- `stop()` aborts the SSE fetch, retains no timers, sends `SIGKILL` to every
+  in-flight command's process group and **waits** for those children to be
+  reaped before resolving. It is safe to call twice (and from inside `onState`).
+- A fatal `{"error":"invalid-token"}` 401 never throws: the loop ends,
+  `status()` reports `lastError: 'invalid-token'` and `exitCode: 1`, and
+  `onState` fires so the host can surface it. Any other 401/403/404/5xx is
+  treated as a transient server condition and retried with backoff.
+- The embedded runtime never writes `~/.dsh-computers`; the host persists its
+  own `runtime.json` (PROTOCOL §10.2) and the CLI remains the only writer of
+  `config.json`.
+
+`AGENT_VERSION` is exported too (the host can put it in the §3.1 enroll body).
+
+## Files and environment
+
+| Path | Purpose |
+| --- | --- |
+| `${DSH_COMPUTERS_HOME:-$HOME/.dsh-computers}/config.json` | Credentials, mode `0600`, atomic tmp+rename |
+| `${DSH_COMPUTERS_HOME}/agent.log` | Append-only log, rotates at 5 MiB (keeps one `agent.log.1`) |
+| `~/Library/LaunchAgents/com.dsh.computers.agent.plist` | macOS service unit |
+| `~/.config/systemd/user/dsh-computers-agent.service` | Linux service unit |
+| `~/.dsh-computers/agent.pid` | Only used by the `nohup` fallback |
+
+Environment variables:
+
+- `DSH_COMPUTERS_HOME` — relocate config + log (useful for tests and for
+  multiple installs). Also written into the service unit so the service reads
+  the same credentials.
+- `DSH_COMPUTERS_SERVICE_LABEL` — override the launchd/systemd label
+  (advanced/tests; default `com.dsh.computers.agent`).
+
+## Security notes
+
+- **Token**: generated by the server, stored only on this machine in a `0600`
+  file, sent as `authorization: Bearer …` on every request. It is never printed,
+  never logged, and `status` shows only its last 6 characters.
+- **Outbound only**: enroll, SSE stream, result POSTs, heartbeats. No listener.
+- **Execution identity**: commands run as your user through
+  `/bin/sh -lc '<command>'` (Windows: `cmd.exe /d /s /c`), inheriting your
+  environment — the same power as your own terminal. Only connect your server
+  to machines and networks you trust.
+- **Process control**: each command is spawned `detached`, so on timeout/cancel
+  the whole process group is killed with `SIGKILL` (`process.kill(-pid)`),
+  including pipelines and grandchildren. Output is capped at 1 MiB per stream
+  with `\n[output truncated]` appended and `truncated: true` in the result.
+- **Log**: rotates at 5 MiB; also captures launchd's stdout/stderr. Contains
+  command text and exit codes, never the token.
+
+## Uninstall
+
+```sh
+node ~/.dsh-computers/agent.mjs service uninstall   # idempotent
+rm -rf ~/.dsh-computers                             # credentials + logs
+```
+
+On the server side, delete the computer entry in Settings → 电脑 (its token is
+hashed at rest there and every stored token stops working once the record is
+removed).
+
+## Troubleshooting
+
+| Symptom | Meaning / fix |
+| --- | --- |
+| `run` exits with `✗ 服务器拒绝了已保存的凭据（HTTP 401 invalid-token）` | The server explicitly answered JSON `{"error":"invalid-token"}`: the token was revoked or the server state was reset. Generate a new key and `enroll` again. This is the one error the agent does **not** retry. |
+| A bare `401` / `403` / `404` / `503` while connecting | That is **not** a token rejection (plugin reloading, generic `/api` gateway fence, proxy). The agent logs a throttled `⚠ 服务器暂时不可用…` at most once a minute and keeps retrying — machines survive plugin disable/enable and upgrades. |
+| `status` says 未注册, exit 1 | No `config.json`; enroll first. |
+| `注册失败（invalid-key / key-expired / key-used）` | The one-time key is wrong, older than 15 min, or already used — create a new one in Settings → 连接电脑. |
+| Service not running (`service status`) | `service start`, then check `~/.dsh-computers/agent.log`. `KeepAlive` restarts it after crashes with a 10 s throttle. |
+| `launchctl bootstrap` fails (`5: Input/output error` / domain unsupported) | The `gui/<uid>` domain is unavailable — usually an SSH session without a GUI login. The agent falls back to `launchctl load -w`; if both fail, run `service start` once from a logged-in desktop terminal. |
+| `✗ 需要 Node.js >= 22` | Upgrade Node; the script relies on global `fetch` and modern ESM. |
+| Computer shows offline in the UI | Check `agent.log` for reconnect lines; the stream reconnects with 1 s → 30 s backoff. |
+
+## Protocol notes (intentional choices)
+
+- **Only our own `invalid-token` 401 is fatal.** A rejected **token** cannot
+  heal by retrying, so `run` logs `✗ … HTTP 401 invalid-token` and exits
+  non-zero. The classification is deliberately narrow: HTTP 401 **and** a JSON
+  body with `error === 'invalid-token'` (the host plugin's rejection shape).
+  Any other 401 (bare text, another JSON error, empty body) — and 403/404/5xx —
+  is a transient server-side condition (plugin reload, gateway fence, proxy)
+  and is retried with the normal 1 s → 30 s backoff, warning at most once per
+  60 s. Without this, disabling/enabling or upgrading the hub plugin would
+  knock every connected machine offline until the user re-ran the installer.
+- **Heartbeats** call `POST /api/dsh-computers/agent/heartbeat` every
+  `heartbeatMs` (from `hello`). This is belt-and-braces next to the open
+  stream and also picks up renames echoed by the server.
+- **`enroll --replace`** sends `"replace": true` in the enroll body (the host
+  also keys replacement off the pending key). It does not change local
+  behaviour otherwise.
+- **`DSH_COMPUTERS_SERVICE_LABEL`** exists only so tests can install/remove a
+  throw-away launchd job instead of touching a real one.
+
+## Development
+
+`agent/test/mock-server.mjs` is an in-memory implementation of PROTOCOL
+§3.1–§3.4 (enroll, SSE events, results, heartbeat) on an ephemeral port; the
+tests drive the real CLI against it.
+
+```sh
+node --check agent/dsh-computers-agent.mjs
+
+# The documented gate. Node 24 no longer expands a directory positional, so
+# agent/test/package.json only carries a "main" shim that keeps this exact
+# command working. The explicit glob form works on its own too:
+node --test agent/test/
+node --test "agent/test/**/*.test.mjs"
+```
+
+To poke at the agent by hand:
+
+```sh
+node agent/test/mock-server.mjs --port 0 --verbose
+# prints a ready-to-paste enroll command and the mock URL
+```
+
+Covered by the suite: enroll happy path / invalid / expired / used key,
+`--replace` re-enroll, token redaction, `0600` + atomic config, SSE connect →
+exec → result, exit codes + stdout/stderr, default and explicit `cwd`,
+environment inheritance, timeout process-group kill, truncation at 1 MiB,
+cancel process-group kill, reconnect after a dropped stream, heartbeats,
+server-driven rename, log rotation, idempotent launchd
+install/status/stop/uninstall, plus the runtime-mode and 401-classification
+paths:
+
+- import is side-effect free and exports `startRuntime` + `AGENT_VERSION`;
+- embedded `startRuntime()` connects to the mock, executes a command,
+  `status()` reports `connected`/`since`, `stop()` closes the stream, reaps the
+  `sleep` child (process group), posts no result after shutdown, and returns
+  `running: false, connected: false, exitCode: 0`;
+- a foreign bare/other-JSON 401 is retried and the machine reconnects (throttled
+  single warning), while JSON `invalid-token` exits 1 without retry;
+- 404/503 during connect are retried and the stream recovers.