dsh-computers 0.0.0-stage → 1.3.0

package/cordis.patch.yml

@@ -0,0 +1,25 @@
+# dsh-computers: one Host row that registers the computer registry, the
+# agent-facing endpoints, the model-facing tools and the settings page.
+#
+# role:
+#   hub      - this instance only controls machines (the server); no local runtime card
+#   runtime  - this instance only exposes itself to a hub (a desktop Mac); no computer list
+#   both     - default: both cards; the machine can be controlled AND control others
+#
+# The default work layout is one server with role: hub and every other machine
+# left on the default, connecting out to the server. Topology is hub-and-spoke
+# only - a runtime never accepts inbound connections.
+- insert:
+    - id: dsh-computers
+      name: dsh-computers
+      config:
+        role: both
+        publicUrl: ''
+        stateDir: ''
+        keyTtlMinutes: 15
+        heartbeatMs: 20000
+        execTimeoutMs: 120000
+        execEnabled: true
+        promoteOnTimeout: true
+        minAgentVersion: ''
+        maxOutputBytes: 1048576

package/docs/deploy.md

@@ -0,0 +1,103 @@
+# 部署与重启
+
+插件更新后，**Host 端（插件主进程）必须重启**才会加载新代码；浏览器端只需刷新页面（Client 代码会随刷新重新拉取）。
+
+重启会断开所有已连接电脑的 SSE 长连接，但它们会自动重连（1s→30s 退避），**不需要重新 enroll**；会话与电脑注册表都是持久化的。
+
+日常最省事的做法是把 `dsh web` 交给进程管理器，之后重启只需一条命令。
+
+## Linux：systemd（推荐）
+
+```ini
+# /etc/systemd/system/dsh-web.service
+[Unit]
+Description=DSH Web
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=YOUR_USER
+WorkingDirectory=/home/YOUR_USER
+# 监听对外地址；反向代理场景可用 127.0.0.1:8080，只让代理连进来
+ExecStart=/usr/local/bin/dsh web --host 127.0.0.1 --port 8080
+Restart=always
+RestartSec=3
+# 让 Host 端能读到代理传来的 X-Forwarded-*（本插件据此生成对外地址）
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now dsh-web
+sudo systemctl restart dsh-web     # ← 以后更新插件后只需要这一条
+journalctl -u dsh-web -f           # 看日志
+```
+
+> 只给当前用户装可以用 `systemctl --user`，配 `loginctl enable-linger YOUR_USER` 让它开机自启。
+
+## macOS：launchd
+
+```xml
+<!-- ~/Library/LaunchAgents/com.dsh.web.plist -->
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.dsh.web</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/dsh</string><string>web</string>
+    <string>--host</string><string>127.0.0.1</string>
+    <string>--port</string><string>8080</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>/tmp/dsh-web.log</string>
+  <key>StandardErrorPath</key><string>/tmp/dsh-web.log</string>
+</dict></plist>
+```
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.dsh.web.plist
+launchctl kickstart -k gui/$(id -u)/com.dsh.web     # ← 重启
+```
+
+## Docker
+
+```bash
+docker compose restart dsh-web
+```
+
+## 前台 / tmux（不装管理器）
+
+```bash
+# Ctrl-C 后重跑同一行；或用 tmux 保留会话
+tmux new -s dsh 'dsh web --host 127.0.0.1 --port 8080'
+tmux attach -t dsh        # 之后 Ctrl-C、↑、Enter 即可重启
+```
+
+## 关于「插件市场」里的重启入口
+
+插件市场在检测到「需重启后生效」时会提供重启入口，但它**只在自己不是被监督进程时**才自行重启；检测到 systemd 时会把重启交给 systemd（它不能杀掉自己的 cgroup）。所以：
+
+- 前台 / tmux 跑 → 用市场的重启入口，或 Ctrl-C 重跑；
+- systemd / launchd / Docker / pm2 托管 → 用上面的 `restart` 命令。
+
+## 更新插件的正确姿势
+
+profile 里的 git 依赖会被钉到 spec + commit，所以**用同样的 spec 再装一次不会更新**（返回 `already-installed`）：
+
+```bash
+# 换 spec = 真正更新（不用先卸载）
+dsh plugin install github:9Ashwin/dsh-computers#v1.0.2
+
+# 或者装分支，让插件市场的「检查更新」能发现新提交
+dsh plugin install github:9Ashwin/dsh-computers
+```
+
+装 tag 的实例永远不会被市场判为"有更新"（tag 本身不动），要升级只能显式换 tag。装分支则可以在市场里一键检查更新。
+
+更新完 → 重启 Host（本节上面的命令）→ 刷新浏览器。

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Computers">
+  <rect x="4" y="10" width="40" height="27" rx="4" fill="none" stroke="#247bbf" stroke-width="3.5"/>
+  <path d="M4 30h40" stroke="#247bbf" stroke-width="3.5" stroke-linecap="round"/>
+  <path d="M17 37v5h14v-5" fill="none" stroke="#247bbf" stroke-width="3.5" stroke-linejoin="round"/>
+  <rect x="12" y="42" width="24" height="3.5" rx="1.75" fill="#247bbf"/>
+  <rect x="50" y="26" width="10" height="26" rx="2.5" fill="none" stroke="#247bbf" stroke-width="3.5"/>
+  <circle cx="55" cy="46.5" r="1.6" fill="#247bbf"/>
+</svg>

package/index.js

@@ -0,0 +1,241 @@
+/**
+ * dsh-computers — connect the user's own Macs (and other machines) to a
+ * DSH Web deployment so the agent can run shell commands on them.
+ *
+ * This is the Host half: a persisted registry, the SSE hub the machine agents
+ * connect to, the browser settings API, and the two model-facing tools. The
+ * wire contract lives in PROTOCOL.md; the machine agent is served from
+ * `agent/dsh-computers-agent.mjs` and the settings page from `client.js`.
+ *
+ * Plain ESM, Node builtins only — no `@deepseek-ai/*` imports, so the bundle
+ * loads in any profile.
+ */
+
+import { createAccessControl, createAccessStore } from './lib/access.js'
+import { createHub } from './lib/hub.js'
+import { createRoutes, createRuntimeRoutes, createRuntimeStatusRoutes } from './lib/routes.js'
+import { createRuntimeManager } from './lib/runtime.js'
+import { createFsOps } from './lib/fs-ops.js'
+import { createSelectionStore } from './lib/selection.js'
+import { majorMinor } from './lib/version.js'
+import { resolveStateDir, createStore } from './lib/state.js'
+import { createTools } from './lib/tools.js'
+
+/** Cordis plugin name. */
+export const name = 'dsh-computers'
+
+/** Required host capabilities; `systemPrompt` and `connection` are optional. */
+export const inject = ['tools', 'webServer']
+
+/** Version reported by `/api/dsh-computers/health` (and asserted by the smoke harness). */
+export const PLUGIN_VERSION = '1.3.0'
+
+/** The machine agent bundle, served at request time (never imported). */
+const AGENT_URL = new URL('./agent/dsh-computers-agent.mjs', import.meta.url)
+
+/** Protocol defaults (PROTOCOL §8); `''` means "use the default". */
+const ROLES = Object.freeze(['hub', 'runtime', 'both'])
+
+const DEFAULTS = Object.freeze({
+  role: 'both',
+  publicUrl: '',
+  promoteOnTimeout: true,
+  minAgentVersion: '',
+  stateDir: '',
+  keyTtlMinutes: 15,
+  heartbeatMs: 20_000,
+  execTimeoutMs: 120_000,
+  execEnabled: true,
+  maxOutputBytes: 1_048_576,
+})
+
+/** Bounds that keep a hand-edited config from producing an unusable host. */
+const LIMITS = Object.freeze({
+  keyTtlMinutes: [1, 10_080], // 1 minute .. 7 days
+  heartbeatMs: [100, 3_600_000], // 100 ms .. 1 hour
+  execTimeoutMs: [100, 86_400_000], // 100 ms .. 24 hours
+  maxOutputBytes: [64, 64 * 1024 * 1024], // 64 B .. 64 MiB
+})
+
+/** Throw a clear TypeError instead of letting a bad value surface as a 500 later. */
+function configError(message) {
+  return new TypeError(`dsh-computers: ${message}`)
+}
+
+/** Validate one bounded integer option. */
+function boundedInteger(raw, key, fallback) {
+  if (raw === undefined || raw === null || raw === '') return fallback
+  const value = typeof raw === 'number' ? raw : Number(raw)
+  const [min, max] = LIMITS[key]
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw configError(`${key} must be an integer between ${min} and ${max} (received ${JSON.stringify(raw)})`)
+  }
+  return value
+}
+
+/**
+ * Validate the plugin config by hand (schemastery is available only to some
+ * host compositions, so this file must not depend on it).
+ * @param {unknown} raw - config passed by cordis.patch.yml.
+ * @returns {object} resolved config with defaults applied.
+ */
+export function resolveConfig(raw) {
+  if (raw === undefined || raw === null) raw = {}
+  if (typeof raw !== 'object' || Array.isArray(raw)) throw configError('config must be an object')
+
+  let publicUrl = DEFAULTS.publicUrl
+  if (raw.publicUrl !== undefined && raw.publicUrl !== null && raw.publicUrl !== '') {
+    if (typeof raw.publicUrl !== 'string') throw configError('publicUrl must be a string')
+    const trimmed = raw.publicUrl.trim().replace(/\/+$/, '')
+    let parsed
+    try {
+      parsed = new URL(trimmed)
+    } catch {
+      throw configError(`publicUrl must be an absolute http(s) URL (received ${JSON.stringify(raw.publicUrl)})`)
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw configError('publicUrl must use http or https')
+    }
+    publicUrl = trimmed
+  }
+
+  let stateDir = DEFAULTS.stateDir
+  if (raw.stateDir !== undefined && raw.stateDir !== null && raw.stateDir !== '') {
+    if (typeof raw.stateDir !== 'string') throw configError('stateDir must be a string')
+    stateDir = raw.stateDir.trim()
+  }
+
+  let role = DEFAULTS.role
+  if (raw.role !== undefined && raw.role !== null) {
+    if (typeof raw.role !== 'string' || !ROLES.includes(raw.role)) {
+      throw configError(`role must be one of ${ROLES.join(', ')} (received ${JSON.stringify(raw.role)})`)
+    }
+    role = raw.role
+  }
+
+  let promoteOnTimeout = DEFAULTS.promoteOnTimeout
+  if (raw.promoteOnTimeout !== undefined && raw.promoteOnTimeout !== null) {
+    if (typeof raw.promoteOnTimeout !== 'boolean') throw configError('promoteOnTimeout must be a boolean')
+    promoteOnTimeout = raw.promoteOnTimeout
+  }
+
+  let minAgentVersion = DEFAULTS.minAgentVersion
+  if (raw.minAgentVersion !== undefined && raw.minAgentVersion !== null && raw.minAgentVersion !== '') {
+    if (typeof raw.minAgentVersion !== 'string') throw configError('minAgentVersion must be a string')
+    const trimmed = raw.minAgentVersion.trim()
+    if (!/^v?\d+(\.\d+){0,2}$/.test(trimmed)) {
+      throw configError(`minAgentVersion must look like 1.2 or 1.2.3 (received ${JSON.stringify(raw.minAgentVersion)})`)
+    }
+    minAgentVersion = trimmed
+  }
+  // Default gate: the plugin's own major.minor (§11.6.5).
+  if (minAgentVersion === '') minAgentVersion = majorMinor(PLUGIN_VERSION)
+
+  let execEnabled = DEFAULTS.execEnabled
+  if (raw.execEnabled !== undefined && raw.execEnabled !== null) {
+    if (typeof raw.execEnabled !== 'boolean') throw configError('execEnabled must be a boolean')
+    execEnabled = raw.execEnabled
+  }
+
+  return Object.freeze({
+    role,
+    publicUrl,
+    promoteOnTimeout,
+    minAgentVersion,
+    stateDir,
+    keyTtlMinutes: boundedInteger(raw.keyTtlMinutes, 'keyTtlMinutes', DEFAULTS.keyTtlMinutes),
+    heartbeatMs: boundedInteger(raw.heartbeatMs, 'heartbeatMs', DEFAULTS.heartbeatMs),
+    execTimeoutMs: boundedInteger(raw.execTimeoutMs, 'execTimeoutMs', DEFAULTS.execTimeoutMs),
+    execEnabled,
+    maxOutputBytes: boundedInteger(raw.maxOutputBytes, 'maxOutputBytes', DEFAULTS.maxOutputBytes),
+  })
+}
+
+/**
+ * Mount the plugin.
+ * @param {object} ctx - Cordis context with `tools` and `webServer`.
+ * @param {unknown} [config] - plugin config (PROTOCOL §8).
+ */
+export function apply(ctx, config) {
+  const resolved = resolveConfig(config)
+  const onWarn = (message) => {
+    try {
+      // The host's logger is not part of the injected contract; a warning on
+      // stderr is enough and never fatal.
+      console.warn(message)
+    } catch {
+      // A host with a broken console must not lose the plugin.
+    }
+  }
+
+  const stateDir = resolveStateDir(resolved.stateDir)
+
+  // ---- hub half (PROTOCOL §1-§5, §8) ------------------------------------
+  // role 'runtime' is the controlled machine only: it must not serve the hub
+  // API, register computer_* tools or contribute a prompt section.
+  if (resolved.role !== 'runtime') {
+    const store = createStore({ stateDir, onWarn })
+    const selections = createSelectionStore({ stateDir, onWarn })
+    const access = createAccessControl({ ctx, store: createAccessStore({ stateDir, onWarn }) })
+    const hub = createHub({
+      store,
+      heartbeatMs: resolved.heartbeatMs,
+      maxOutputBytes: resolved.maxOutputBytes,
+      onWarn,
+    })
+    const fsOps = createFsOps({ hub, onWarn })
+
+    // Routes first (the browser page and the agents can arrive immediately),
+    // then the tools and the prompt section.
+    createRoutes({
+      ctx,
+      config: resolved,
+      store,
+      hub,
+      selections,
+      access,
+      fsOps,
+      role: resolved.role,
+      version: PLUGIN_VERSION,
+      agentUrl: AGENT_URL,
+      onWarn,
+    })
+    createTools({ ctx, config: resolved, store, hub, selections, access, fsOps, version: PLUGIN_VERSION, onWarn })
+
+    // Every registered route is its own effect; this one owns the timers and
+    // the in-flight exec promises so a plugin reload cannot leak either.
+    ctx.effect(() => () => {
+      fsOps.dispose()
+      hub.dispose()
+    }, 'dsh-computers: dispose hub and pending executions')
+  } else {
+    // role 'runtime': the settings client still learns its role from /state
+    // and can probe /health; the hub API itself stays unregistered.
+    createRuntimeStatusRoutes({
+      ctx,
+      config: resolved,
+      role: resolved.role,
+      version: PLUGIN_VERSION,
+      onWarn,
+    })
+  }
+
+  // ---- runtime half (PROTOCOL §10) --------------------------------------
+  // role 'hub' is a controller only: it must never dial out as a computer.
+  if (resolved.role !== 'hub') {
+    const runtime = createRuntimeManager({
+      config: resolved,
+      stateDir,
+      version: PLUGIN_VERSION,
+      agentModuleUrl: AGENT_URL,
+      onWarn,
+    })
+    createRuntimeRoutes({ ctx, config: resolved, runtime, role: resolved.role, onWarn })
+
+    // Starting DSH starts the runtime: the switch survives restarts, so an
+    // enabled runtime.json reconnects on load without any user action.
+    void runtime.autoStart()
+
+    ctx.effect(() => () => runtime.dispose(), 'dsh-computers: dispose embedded runtime')
+  }
+}