dsh-runnpu 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EM-GeekLab
+
+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.md

@@ -0,0 +1,89 @@
+# dsh-runnpu
+
+Two agent modes for DeepSeek Harness over a RunNPU Ascend NPU cluster.
+
+- **算力管理模式 (`compute`)** — a cluster console beside the conversation: connection
+  status + login form, and a pinned-chart column that keeps each chart's *query* and
+  refreshes it, not a screenshot.
+- **训练模式 (`training`)** — the workspace's training project on the cluster with SwanLab
+  instrumentation: key-metric strip above the composer, a version card from `.train/`,
+  and SwanLab connection settings that follow the run into the container as env vars.
+
+Each mode is an agent preset (`*/preset/`) carrying its own skills; the UI and the HTTP
+surface ship as one plugin bundle mounted on the host plane.
+
+## Install
+
+Published on npm as [`dsh-runnpu`](https://www.npmjs.com/package/dsh-runnpu). In the dsh
+profile you run (usually `~/.dsh/profiles/web`):
+
+```bash
+cd ~/.dsh/profiles/web
+pnpm add dsh-runnpu
+npx dsh-runnpu install all --profile web --with-cli   # or: compute | training
+pnpm install
+```
+
+`--with-cli` installs the host CLIs the mode drives — `runnpu` (the pinned release of
+[EM-GeekLab/run-npu-skill](https://github.com/EM-GeekLab/run-npu-skill), sha256-checked, or
+`--from <archive>` offline) and, for training, `swanlab` (via `uv tool` / `pipx` / `pip`). `npx dsh-runnpu doctor` checks them any time; the `runnpu`
+build must match the vendored skill (`package.json` → `cliDeps`), because the skill
+documents that binary's parameters.
+
+then restart dsh and pick the mode in the New Session picker. `dsh-runnpu install`
+copies the preset(s) into `~/.dsh/.agent-presets/{compute,training}` (they must be
+real directories — npm cannot put them there) and `--profile` adds `"dsh-runnpu"` to
+the profile's `dsh.profile.bundles`. `dsh-runnpu status` / `uninstall` round it out.
+Host prerequisites: the `runnpu` CLI, and `swanlab` ≥ 0.9.0 for training mode.
+Full guide: [`docs/RELEASE-INSTALL.md`](docs/RELEASE-INSTALL.md).
+
+## Develop
+
+```bash
+npm install
+npm run build                      # client/src → lib/client.js
+node scripts/install-presets.mjs   # = dsh-runnpu install all, from this checkout
+```
+
+Development commands — all four run in CI (`.github/workflows/ci.yml`):
+
+```bash
+npm test          # node:test over shared/ and bin/ — one case per bug that actually shipped
+npm run lint      # oxlint
+npm run typecheck # tsc --checkJs over shared/'s JSDoc (jsconfig.json); no TypeScript in the repo
+npm run build     # the bundle, plus the guard that keeps node-only code out of it
+```
+
+To run the checkout instead of the npm release, point the profile at it:
+
+```jsonc
+"dependencies": { "dsh-runnpu": "file:/path/to/this/repo" },
+"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-runnpu"] } }
+```
+
+`pnpm install` in the profile, restart dsh. Releasing: `npm version` + `npm publish`
+(`prepublishOnly` runs build / test / lint / typecheck), see the guide above.
+
+## Skills
+
+`skills/` is the canonical copy of the three skills the modes carry — `runnpu` (vendored
+from run-npu-skill, same release as the pinned CLI), `swanlab-skill` (vendored from
+SwanHubX/SwanLab-Skill) and `training-research` (ours). Each preset holds a byte-identical
+copy that `node scripts/sync-skills.mjs` refreshes and `tests/skills-sync.test.mjs` pins,
+so edit or re-vendor under `skills/` only. The same layout is what `npx skills add` and
+skill hubs discover, for use outside dsh.
+
+## Layout
+
+| Path | Role |
+|---|---|
+| `shared/` | RunNPU REST client, SwanLab CLI wrapper, config/secret resolution, route helpers |
+| `compute-mode/` | compute preset + node half (`/runnpu-api`) |
+| `training-mode/` | training preset + node half (`/training-api`) |
+| `client/src/` | the single browser bundle; both modes branch on the session's `agentPreset` |
+| `skills/` | canonical skills; presets carry pinned copies (`scripts/sync-skills.mjs`) |
+| `bin/` | the `dsh-runnpu` installer: presets, profile mounting, host CLIs |
+| `cordis.patch.yml` | host-plane rows: connectors, the two node halves, the client roster row |
+
+`compute-mode/CLAUDE.md` and `training-mode/CLAUDE.md` are the design contracts — read
+them before changing anything; they record the harness constraints this was built against.

package/bin/cli-deps.mjs

@@ -0,0 +1,384 @@
+/**
+ * The two host CLIs the modes drive — `runnpu` (RunNPU control panel) and
+ * `swanlab` (SwanLab, Python) — are NOT npm packages, so this module is what
+ * `dsh-runnpu doctor` / `dsh-runnpu cli` use to check and install them.
+ *
+ * Pins live in package.json `cliDeps`:
+ *   runnpu.version      a release tag of EM-GeekLab/run-npu-skill (e.g.
+ *                       `v0.1.0-rc.1`). CLI and skill ship together there, so
+ *                       this is also the version of the vendored `runnpu`
+ *                       skill — see skills/runnpu/VENDOR.txt.
+ *   runnpu.releaseBase  `<repo>/releases/download`; under `<version>/` sit
+ *                       `runnpu_<ver>_<os>_<arch>.tar.gz|zip` (the binary at
+ *                       the archive root) and `checksums.txt` (sha256).
+ *   swanlab.min         the SDK/CLI floor the training mode was verified on.
+ *
+ * Everything that touches the network or the PATH takes its inputs as
+ * parameters (`env`, `fetchImpl`, `from`) so tests can drive it with stub
+ * executables and a local archive, never the real machine.
+ *
+ * @module dsh-runnpu/bin/cli-deps
+ */
+
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { access, chmod, copyFile, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { constants } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { delimiter, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** @typedef {{ version: string, releaseBase: string, tag?: string }} RunnpuPin */
+/** @typedef {{ min: string, package: string }} SwanlabPin */
+/** @typedef {{ runnpu: RunnpuPin, swanlab: SwanlabPin }} CliPins */
+
+/** @returns {Promise<CliPins>} */
+export async function readPins(root = packageRoot) {
+  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+  const pins = pkg.cliDeps
+  if (!pins?.runnpu?.version || !pins?.swanlab?.min) throw new Error('package.json cliDeps is missing the runnpu / swanlab pins')
+  return pins
+}
+
+// ── platform ────────────────────────────────────────────────────────────────
+
+/**
+ * Map Node's platform/arch to the release's archive naming (`GOOS`/`GOARCH`
+ * + archive type, exactly what run-npu-skill's install.sh / install.ps1 use).
+ * @param {string} platform process.platform
+ * @param {string} arch process.arch
+ */
+export function platformKey(platform = process.platform, arch = process.arch) {
+  const os = { darwin: 'darwin', linux: 'linux', win32: 'windows' }[platform]
+  const goarch = { arm64: 'arm64', x64: 'amd64' }[arch]
+  if (!os || !goarch) throw new Error(`no runnpu build for ${platform}/${arch} (have darwin/linux/windows × arm64/amd64)`)
+  return { os, arch: goarch, ext: os === 'windows' ? 'zip' : 'tar.gz', exe: os === 'windows' ? '.exe' : '' }
+}
+
+/** `v0.1.0-rc.1` → `0.1.0-rc.1`: the archive names carry the bare version, the tag the `v`. */
+export function bareVersion(version) {
+  return String(version).replace(/^v/, '')
+}
+
+/** @param {string} version @param {ReturnType<typeof platformKey>} plat */
+export function runnpuArchiveName(version, plat) {
+  return `runnpu_${bareVersion(version)}_${plat.os}_${plat.arch}.${plat.ext}`
+}
+
+/** Directory of one release's assets. */
+export function runnpuReleaseDir(pin) {
+  return `${pin.releaseBase.replace(/\/+$/, '')}/${pin.tag ?? pin.version}`
+}
+
+/** @param {RunnpuPin} pin @param {ReturnType<typeof platformKey>} plat */
+export function runnpuDownloadUrl(pin, plat) {
+  return `${runnpuReleaseDir(pin)}/${runnpuArchiveName(pin.version, plat)}`
+}
+
+/** @param {RunnpuPin} pin */
+export function runnpuChecksumsUrl(pin) {
+  return `${runnpuReleaseDir(pin)}/checksums.txt`
+}
+
+/**
+ * Find `<sha256>  <file>` for `file` in a checksums.txt; undefined when absent.
+ * @param {string} text
+ * @param {string} file
+ */
+export function checksumFor(text, file) {
+  for (const line of String(text).split('\n')) {
+    const match = line.trim().match(/^([0-9a-f]{64})\s+\*?(.+)$/i)
+    if (match && match[2].trim() === file) return match[1].toLowerCase()
+  }
+  return undefined
+}
+
+// ── versions ────────────────────────────────────────────────────────────────
+
+/** `runnpu --version` prints `runnpu version <tag or git describe>`; returns that string. */
+export function parseRunnpuVersion(stdout) {
+  const match = String(stdout).match(/runnpu version\s+(\S+)/)
+  return match ? match[1] : undefined
+}
+
+/**
+ * Does an installed build satisfy the pin? The same version with or without
+ * the `v` prefix, optionally carrying a `-dirty` suffix (a local build of the
+ * pinned tag). Anything else — an older tag, a bare commit — is a mismatch,
+ * because the skill documents this exact CLI.
+ */
+export function runnpuVersionMatches(actual, pinned) {
+  if (!actual || !pinned) return false
+  const norm = v => bareVersion(String(v).replace(/-dirty$/, ''))
+  return norm(actual) === norm(pinned)
+}
+
+/** `swanlab --version` prints `SwanLab 0.9.8`. */
+export function parseSwanlabVersion(stdout) {
+  const match = String(stdout).match(/(\d+\.\d+\.\d+)/)
+  return match ? match[1] : undefined
+}
+
+/** Numeric dotted compare; returns <0, 0, >0. */
+export function compareVersions(a, b) {
+  const pa = String(a).split('.').map(Number)
+  const pb = String(b).split('.').map(Number)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (d !== 0) return d
+  }
+  return 0
+}
+
+// ── PATH probing ────────────────────────────────────────────────────────────
+
+/**
+ * Locate an executable on `env.PATH` without shelling out to `which`.
+ * @param {string} name
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {Promise<string | undefined>}
+ */
+export async function which(name, env = process.env) {
+  const exts = process.platform === 'win32' ? (env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';') : ['']
+  for (const dir of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = join(dir, name + ext)
+      try {
+        await access(candidate, constants.X_OK)
+        if ((await stat(candidate)).isFile()) return candidate
+      } catch {
+        /* keep looking */
+      }
+    }
+  }
+  return undefined
+}
+
+/** Run `<cmd> <args>` and capture stdout+stderr; never throws. */
+export async function probe(cmd, args, env = process.env) {
+  try {
+    const { stdout, stderr } = await execFileAsync(cmd, args, { env, timeout: 15_000 })
+    return { ok: true, output: `${stdout}${stderr}` }
+  } catch (error) {
+    const e = /** @type {any} */ (error)
+    return { ok: false, output: `${e.stdout ?? ''}${e.stderr ?? ''}${e.message ?? ''}` }
+  }
+}
+
+// ── doctor ──────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} Finding
+ * @property {'runnpu' | 'swanlab'} name
+ * @property {string | undefined} path
+ * @property {string | undefined} version
+ * @property {string} want
+ * @property {boolean} ok
+ * @property {string} detail
+ */
+
+/**
+ * Check both CLIs against the pins. Pure reporting — installs nothing.
+ * @param {CliPins} pins
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {Promise<Finding[]>}
+ */
+export async function doctor(pins, env = process.env) {
+  /** @type {Finding[]} */
+  const findings = []
+
+  const runnpuPath = await which('runnpu', env)
+  const runnpuVersion = runnpuPath ? parseRunnpuVersion((await probe(runnpuPath, ['--version'], env)).output) : undefined
+  const runnpuOk = runnpuVersionMatches(runnpuVersion, pins.runnpu.version)
+  findings.push({
+    name: 'runnpu',
+    path: runnpuPath,
+    version: runnpuVersion,
+    want: pins.runnpu.version,
+    ok: runnpuOk,
+    detail: !runnpuPath
+      ? 'not on PATH'
+      : !runnpuVersion
+        ? '`runnpu --version` did not answer'
+        : runnpuOk
+          ? 'matches the vendored runnpu skill'
+          : `build ${runnpuVersion} does not match the skill (${pins.runnpu.version}) — parameters may disagree`,
+  })
+
+  const swanlabPath = await which('swanlab', env)
+  const swanlabVersion = swanlabPath ? parseSwanlabVersion((await probe(swanlabPath, ['--version'], env)).output) : undefined
+  const swanlabOk = Boolean(swanlabVersion) && compareVersions(swanlabVersion, pins.swanlab.min) >= 0
+  findings.push({
+    name: 'swanlab',
+    path: swanlabPath,
+    version: swanlabVersion,
+    want: `>=${pins.swanlab.min}`,
+    ok: swanlabOk,
+    detail: !swanlabPath
+      ? 'not on PATH (training mode needs it; compute mode does not)'
+      : !swanlabVersion
+        ? '`swanlab --version` did not answer'
+        : swanlabOk
+          ? 'ok'
+          : `${swanlabVersion} is below ${pins.swanlab.min} — \`swanlab api\` output contract differs`,
+  })
+
+  return findings
+}
+
+// ── runnpu install ──────────────────────────────────────────────────────────
+
+/** Default install dir — same as the control panel's own install.sh. */
+export function defaultBinDir(env = process.env) {
+  return env.RUNNPU_BIN_DIR || join(homedir(), '.local', 'bin')
+}
+
+/**
+ * Fetch `url` as bytes. Sends a GitHub token when one is in the environment
+ * (a private mirror's release assets need it; the public repo ignores it).
+ */
+async function fetchBytes(url, env, fetchImpl) {
+  const headers = { 'user-agent': 'dsh-runnpu' }
+  const token = env.GITHUB_TOKEN || env.GH_TOKEN
+  if (token && /github\.com|githubusercontent\.com/.test(url)) headers.authorization = `Bearer ${token}`
+  const response = await fetchImpl(url, { headers, redirect: 'follow' })
+  if (!response.ok) throw new Error(`download failed: ${response.status} ${response.statusText} — ${url}`)
+  return Buffer.from(await response.arrayBuffer())
+}
+
+/** First `runnpu` / `runnpu.exe` found under `dir` (the archive nests it as `<name>/bin/runnpu`). */
+async function findBinary(dir, exe) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      const found = await findBinary(full, exe)
+      if (found) return found
+    } else if (entry.name === `runnpu${exe}`) return full
+  }
+  return undefined
+}
+
+/**
+ * Install the pinned `runnpu` build into `binDir`.
+ *
+ * Source resolution, in order: `from` (a local archive path, a local
+ * directory holding an extracted package, or a URL), else the pin's release
+ * URL for this platform — and in that default case the archive is checked
+ * against the release's checksums.txt before it is opened. Extraction shells
+ * out to `tar`, which reads both .tar.gz and (bsdtar on macOS / Windows 10+)
+ * .zip; the binary sits at the archive root.
+ *
+ * @param {object} options
+ * @param {RunnpuPin} options.pin
+ * @param {string} [options.from]
+ * @param {string} [options.binDir]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @param {ReturnType<typeof platformKey>} [options.plat]
+ * @returns {Promise<{ path: string, version: string | undefined, source: string }>}
+ */
+export async function installRunnpu({ pin, from, binDir, env = process.env, fetchImpl = fetch, plat = platformKey() }) {
+  const dir = binDir ?? defaultBinDir(env)
+  const work = await mkdtemp(join(tmpdir(), 'dsh-runnpu-cli-'))
+  try {
+    let source = from ?? runnpuDownloadUrl(pin, plat)
+    let archive
+    if (/^https?:\/\//.test(source)) {
+      const name = runnpuArchiveName(pin.version, plat)
+      archive = join(work, name)
+      const bytes = await fetchBytes(source, env, fetchImpl)
+      if (!from) {
+        // Only the pinned release has a checksums.txt we know the shape of; a
+        // user-supplied URL is trusted the way a user-supplied file is.
+        const sums = (await fetchBytes(runnpuChecksumsUrl(pin), env, fetchImpl)).toString('utf8')
+        const want = checksumFor(sums, name)
+        if (!want) throw new Error(`checksums.txt of ${pin.version} has no entry for ${name}`)
+        const got = createHash('sha256').update(bytes).digest('hex')
+        if (got !== want) throw new Error(`sha256 mismatch for ${name}: got ${got}, checksums.txt says ${want}`)
+      }
+      await writeFile(archive, bytes)
+    } else {
+      source = resolve(source)
+      const info = await stat(source)
+      archive = info.isDirectory() ? undefined : source
+    }
+
+    let extracted = source
+    if (archive) {
+      extracted = join(work, 'x')
+      await mkdir(extracted)
+      await execFileAsync('tar', ['-xf', archive, '-C', extracted])
+    }
+
+    const binary = await findBinary(extracted, plat.exe)
+    if (!binary) throw new Error(`no runnpu${plat.exe} binary inside ${source}`)
+
+    await mkdir(dir, { recursive: true })
+    const target = join(dir, `runnpu${plat.exe}`)
+    await copyFile(binary, target)
+    await chmod(target, 0o755)
+
+    const version = parseRunnpuVersion((await probe(target, ['--version'], env)).output)
+    if (version && !runnpuVersionMatches(version, pin.version)) {
+      throw new Error(`installed ${target} reports ${version}, expected ${pin.version} — wrong archive for this skill`)
+    }
+    return { path: target, version, source }
+  } finally {
+    await rm(work, { recursive: true, force: true })
+  }
+}
+
+/** Is `dir` on `env.PATH`? */
+export function onPath(dir, env = process.env) {
+  const want = resolve(dir)
+  return (env.PATH ?? '')
+    .split(delimiter)
+    .filter(Boolean)
+    .some(entry => resolve(entry) === want)
+}
+
+// ── swanlab install ─────────────────────────────────────────────────────────
+
+/**
+ * Pick how to install `swanlab` on this machine: an isolated tool install
+ * when `uv` or `pipx` is present (no PEP 668 fight with the system Python),
+ * else `python -m pip install --user`. `python` forces the interpreter, which
+ * is also how a specific venv or Homebrew python is targeted.
+ *
+ * @param {object} options
+ * @param {SwanlabPin} options.pin
+ * @param {(name: string) => Promise<string | undefined>} options.which
+ * @param {string} [options.python]
+ * @returns {Promise<{ tool: 'python' | 'uv' | 'pipx', argv: string[] }>}
+ */
+export async function planSwanlabInstall({ pin, which: lookup, python }) {
+  const spec = `${pin.package}>=${pin.min}`
+  if (python) return { tool: 'python', argv: [python, '-m', 'pip', 'install', '--upgrade', spec] }
+  const uv = await lookup('uv')
+  if (uv) return { tool: 'uv', argv: [uv, 'tool', 'install', '--upgrade', spec] }
+  const pipx = await lookup('pipx')
+  if (pipx) return { tool: 'pipx', argv: [pipx, 'install', '--force', spec] }
+  const py = (await lookup('python3')) ?? (await lookup('python'))
+  if (!py) throw new Error('no python3 on PATH — install Python ≥ 3.9 (or uv / pipx) first, then re-run')
+  return { tool: 'python', argv: [py, '-m', 'pip', 'install', '--user', '--upgrade', spec] }
+}
+
+/**
+ * Install or upgrade `swanlab`. Returns the plan that ran and its output.
+ * @param {object} options
+ * @param {SwanlabPin} options.pin
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {string} [options.python]
+ * @param {boolean} [options.dryRun]
+ */
+export async function installSwanlab({ pin, env = process.env, python, dryRun = false }) {
+  const plan = await planSwanlabInstall({ pin, which: name => which(name, env), python })
+  if (dryRun) return { plan, ok: true, output: '' }
+  const result = await probe(plan.argv[0], plan.argv.slice(1), env)
+  return { plan, ...result }
+}