@hope_phenom/dsh-plugin-remote-use 0.0.0-stage → 0.2.24

package/lib/core/self-acp-spec.js

@@ -0,0 +1,117 @@
+/**
+ * How to launch THIS machine's own ACP agent.
+ *
+ * WHY AN ARGV ARRAY AND NOT A COMMAND LINE: two quoting hazards sit on this path, and both have
+ * already cost time in this project.
+ *
+ *   * The install directory contains a space (`...\Programs\DeepSeek Harness`). Building a
+ *     command line and handing it to `Start-Process -ArgumentList` split it, and node reported
+ *     `Cannot find module 'C:\Users\<user>\AppData\Local\Programs\DeepSeek'` -- an error that points
+ *     at the module system while the actual fault is a missing quote.
+ *   * `dsh.cmd` is a shim, and Node refuses to spawn a `.cmd` without a shell (EINVAL); asking
+ *     `cmd /c` to run it loses quotes through the PowerShell -> node hand-off.
+ *
+ * So the shim is replicated exactly, as an array, and `dsh.cmd` is never launched.
+ *
+ * WHY cli.js IS NOT CHECKED FOR EXISTENCE: it lives INSIDE `app.asar`, which Electron can read
+ * and the filesystem API cannot. An existence test would report false and reject a perfectly
+ * good install. Only the executable is tested; the argv path is constructed.
+ */
+
+import { existsSync } from 'node:fs'
+import { isAbsolute } from 'node:path'
+
+/**
+ * Every file-effect sandbox mode DSH understands.
+ *
+ * Mirrors `SANDBOX_MODES` in `@deepseek-ai/dsh-sandbox-policy`. It is duplicated rather than
+ * imported because this module runs on a worker that may have no DSH package tree of its own.
+ */
+export const SESSION_MODES = ['read-only', 'workspace-write', 'danger-full-access']
+
+/** Where DSH installs by default on Windows, best candidate first. */
+export function installCandidates(env = process.env) {
+  return [
+    env.DSH_INSTALL_DIR,
+    env.LOCALAPPDATA === undefined ? undefined : `${env.LOCALAPPDATA}\\Programs\\DeepSeek Harness`,
+    'C:\\Program Files\\DeepSeek Harness',
+    'C:\\Program Files (x86)\\DeepSeek Harness',
+  ].filter((p) => typeof p === 'string' && p !== '')
+}
+
+/**
+ * The argv and environment for one ACP agent process.
+ *
+ * @param {object} opts
+ * @param {string} opts.installDir
+ * @param {string} [opts.profile]  the DSH profile the worker runs under
+ * @param {string} [opts.permissionMode]  overrides the sandbox/approval preset for the child
+ * @param {string[]} [opts.patchFiles]  extra patch overlays, applied AFTER the profile layer
+ * @returns {{ command: string, args: string[], env: Record<string, string> }}
+ */
+export function acpLaunchSpec(opts) {
+  const installDir = String(opts.installDir ?? '').replace(/[\\/]+$/u, '')
+  if (installDir === '') throw new Error('acpLaunchSpec: no install directory')
+  const profile = String(opts.profile ?? 'acp')
+  if (!/^[\w.-]+$/u.test(profile)) throw new Error(`acpLaunchSpec: profile "${profile}" is not a plain profile name`)
+  // Overlays are the plugin's only way to configure the ACP child without editing the operator's
+  // profile (the worker-model setting uses this). They must be absolute: the child's working
+  // directory is the relay's, not this process's, so a relative path would resolve elsewhere.
+  const patchFiles = Array.isArray(opts.patchFiles) ? opts.patchFiles : []
+  for (const file of patchFiles) {
+    if (typeof file !== 'string' || file === '' || !isAbsolute(file)) {
+      throw new Error(`acpLaunchSpec: patch file is not an absolute path: ${String(file)}`)
+    }
+  }
+  // REFUSE an unknown mode instead of passing it through. `dsh-base` validates the value at load
+  // and rejects the whole `sandbox-policy` row, so a typo would start a worker whose session has no
+  // resolved policy at all -- a failure that is far harder to notice than a failed arming.
+  const permissionMode = opts.permissionMode
+  const wantsMode = typeof permissionMode === 'string' && permissionMode !== ''
+  if (wantsMode && !SESSION_MODES.includes(permissionMode)) {
+    throw new Error(`acpLaunchSpec: "${permissionMode}" is not a sandbox mode DSH understands; expected one of ${SESSION_MODES.join(', ')}`)
+  }
+  return {
+    command: `${installDir}\\DeepSeek Harness.exe`,
+    args: [
+      '--expose-internals',
+      `${installDir}\\resources\\app.asar\\dsh\\node_modules\\@deepseek-ai\\dsh-desktop-host\\lib\\cli.js`,
+      '--profile',
+      profile,
+      ...patchFiles.flatMap((file) => ['--patch', file]),
+    ],
+    env: {
+      ELECTRON_RUN_AS_NODE: '1',
+      ...(wantsMode ? { DSH_PERMISSION_MODE: permissionMode } : {}),
+    },
+  }
+}
+
+/**
+ * Resolve the spec against a real machine.
+ *
+ * @param {object} [deps]
+ * @param {(path: string) => boolean} [deps.exists]
+ * @param {Record<string, string | undefined>} [deps.env]
+ * @param {string} [deps.installDir] explicit override, tried first
+ * @returns {{ ok: true, spec: object, installDir: string } | { ok: false, error: string, tried: string[] }}
+ */
+export function resolveAcpLaunchSpec(deps = {}) {
+  const exists = deps.exists ?? existsSync
+  const env = deps.env ?? process.env
+  const candidates = [deps.installDir, ...installCandidates(env)].filter((p) => typeof p === 'string' && p !== '')
+  for (const candidate of candidates) {
+    if (!exists(`${candidate}\\DeepSeek Harness.exe`)) continue
+    try {
+      const spec = acpLaunchSpec({ installDir: candidate, profile: deps.profile, permissionMode: deps.permissionMode, patchFiles: deps.patchFiles })
+      return { ok: true, spec, installDir: candidate }
+    } catch (error) {
+      return { ok: false, error: error.message, tried: candidates }
+    }
+  }
+  return {
+    ok: false,
+    error: 'could not find "DeepSeek Harness.exe"; pass the install directory explicitly',
+    tried: candidates,
+  }
+}

package/lib/core/selfcheck-runner.js

@@ -0,0 +1,150 @@
+/**
+ * Run the WORKER's own readiness self-check (`slave/selfcheck.ps1`) from the plugin host.
+ *
+ * WHY THE WORKER RUNS IT, RATHER THAN THE MASTER: the checks are about THIS machine's session,
+ * display and input (S1-S12). The master can only see the report the worker sends; running the
+ * script here means the "先检查" result reflects the same interactive session the relay will use,
+ * and the worker can hand back a fix prompt without a round trip.
+ *
+ * WHY NOT ON EVERY PAGE LOAD, AND WHY NOT AS AN ARMING GATE: `S8` moves the mouse for real, and
+ * the session checks depend on somebody being logged in and unlocked -- an OPERATIONAL state that
+ * can legitimately change after arming. So this runs on an explicit check and is ADVISORY; the
+ * master's dispatch gate stays the hard gate.
+ */
+import { spawn as spawnChild } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/**
+ * The PowerShell to run the helper scripts with.
+ *
+ * `pwsh` (7) is preferred because Windows PowerShell 5.1 is blocked by a PATH-based rule on some
+ * volumes (see the relay's note). The FALLBACK MUST BE `powershell.exe`: returning `'pwsh'` when it
+ * was not found is the F46 defect -- the process failed to spawn and the missing report was then
+ * reported as a JSON parse error.
+ *
+ * @param {object} [deps] injectable for tests
+ * @returns {string}
+ */
+export function resolvePowerShell(deps = {}) {
+  const platform = deps.platform ?? process.platform
+  if (platform !== 'win32') return 'pwsh'
+  const stat = deps.stat ?? statSync
+  const programFiles = deps.programFiles ?? process.env.ProgramFiles ?? 'C:\\Program Files'
+  const localAppData = deps.localAppData ?? process.env.LOCALAPPDATA ?? ''
+  const candidates = [
+    join(programFiles, 'PowerShell', '7', 'pwsh.exe'),
+    localAppData === '' ? '' : join(localAppData, 'Microsoft', 'WindowsApps', 'pwsh.exe'),
+  ].filter((candidate) => candidate !== '')
+  for (const candidate of candidates) {
+    try {
+      const info = stat(candidate)
+      // A Store execution alias is a 0-byte reparse point; spawning it opens the Store.
+      if (info.isFile() && info.size > 0) return candidate
+    } catch { /* not there */ }
+  }
+  return 'powershell.exe'
+}
+
+/**
+ * The subset of a report the page needs: the verdict, the counts, and the checks that are not OK.
+ *
+ * @param {object} report parsed `selfcheck.json`
+ * @returns {{ verdict: string, blockingFailures: number, warnings: number, unchecked: number,
+ *             generatedAt: string, checks: object[] }}
+ */
+export function summarizeReport(report) {
+  const checks = Array.isArray(report?.checks) ? report.checks : []
+  return {
+    verdict: String(report?.verdict ?? 'unknown'),
+    blockingFailures: Number(report?.blockingFailures ?? 0),
+    warnings: Number(report?.warnings ?? 0),
+    unchecked: Number(report?.unchecked ?? 0),
+    generatedAt: String(report?.generatedAt ?? ''),
+    // Everything, not only the failures: the page can then explain "S7 unchecked" as its own
+    // state instead of leaving it out and looking like it passed.
+    checks,
+  }
+}
+
+/**
+ * Run the script and parse the JSON it writes next to itself.
+ *
+ * The script writes `selfcheck.json` in its own directory (the relay reads it the same way), so
+ * stdout -- which also carries the human-readable twin -- is not the source of truth.
+ *
+ * @param {object} opts
+ * @param {string} opts.scriptPath
+ * @param {string} [opts.workspace]  task directory handed to `-Workspace`
+ * @param {number} [opts.timeoutMs]
+ * @param {string} [opts.powershell]
+ * @param {Function} [opts.spawn] injected for tests
+ * @returns {Promise<{ ok: boolean, reason: string, report: object | null }>}
+ */
+export async function runSelfcheck(opts = {}) {
+  const scriptPath = String(opts.scriptPath ?? '')
+  if (scriptPath === '' || !existsSync(scriptPath)) {
+    return { ok: false, reason: `selfcheck script not found at ${scriptPath || '(empty path)'}`, report: null }
+  }
+  const powershell = opts.powershell ?? resolvePowerShell()
+  const workspace = String(opts.workspace ?? '').trim()
+  const args = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', scriptPath]
+  if (workspace !== '') args.push('-Workspace', workspace)
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? Number(opts.timeoutMs) : 60_000
+  const spawn = opts.spawn ?? spawnChild
+
+  const run = await new Promise((resolve) => {
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    let timer
+    const finish = (result) => {
+      if (settled) return
+      settled = true
+      if (timer !== undefined) clearTimeout(timer)
+      resolve(result)
+    }
+    let child
+    try {
+      child = spawn(powershell, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch (error) {
+      finish({ error: error instanceof Error ? error.message : String(error), stdout, stderr })
+      return
+    }
+    child.stdout?.on('data', (chunk) => { stdout += String(chunk) })
+    child.stderr?.on('data', (chunk) => { stderr += String(chunk) })
+    child.on('error', (error) => finish({ error: error instanceof Error ? error.message : String(error), stdout, stderr }))
+    child.on('close', (code) => finish({ code, stdout, stderr }))
+    timer = setTimeout(() => {
+      try { child.kill() } catch { /* already gone */ }
+      finish({ error: `timed out after ${timeoutMs}ms`, stdout, stderr })
+    }, timeoutMs)
+  })
+
+  if (run.error !== undefined) {
+    return { ok: false, reason: `could not run ${powershell}: ${run.error}`, report: null }
+  }
+
+  const jsonPath = join(dirname(scriptPath), 'selfcheck.json')
+  let text = ''
+  try {
+    text = readFileSync(jsonPath, 'utf8').replace(/^\uFEFF/u, '')
+  } catch (error) {
+    const tail = String(run.stderr ?? '').trim().split(/\r?\n/u).slice(-2).join(' / ')
+    return {
+      ok: false,
+      reason: `the self-check produced no report at ${jsonPath} (exit ${run.code ?? '?'})${tail === '' ? '' : `: ${tail}`}`,
+      report: null,
+    }
+  }
+  try {
+    return { ok: true, reason: '', report: JSON.parse(text) }
+  } catch (error) {
+    const tail = String(run.stderr ?? '').trim().split(/\r?\n/u).slice(-2).join(' / ')
+    return {
+      ok: false,
+      reason: `the self-check report is not valid JSON (exit ${run.code ?? '?'}): ${error instanceof Error ? error.message : String(error)}${tail === '' ? '' : ` -- ${tail}`}`,
+      report: null,
+    }
+  }
+}

package/lib/core/settings-store.js

@@ -0,0 +1,226 @@
+/**
+ * Settings storage for dsh-plugin-remote-use.
+ *
+ * WHY A SECOND CONFIG SOURCE: the worker list otherwise lives only in the profile patch
+ * (`cordis.patch.yml`), which means every pairing change is a hand edit of YAML plus a
+ * restart. The page needs to write somewhere, and the profile patch is the wrong target:
+ * it is user-maintained prose with comments and hand formatting that a programmatic write
+ * would destroy. A settings file beside the plugin's other state is the same shape the
+ * sibling notification plugin uses.
+ *
+ * PRECEDENCE -- deliberate and stated, because "I changed it and nothing happened" is the
+ * failure this kind of split always produces:
+ *
+ *   defaults  <  profile patch  <  settings file
+ *
+ * The settings file wins, and only for the keys it actually contains. It is absent until
+ * the operator saves something, so an install that never opens the page behaves exactly as
+ * before. `mergeSettings` reports which source won per key so the page can say so.
+ *
+ * TOKENS: never handed to the browser. The page receives `tokenSet` and a masked hint and
+ * can only WRITE a token. A worker token is a bearer credential for remote execution;
+ * sending it to a web page -- where it lands in devtools, memory, and any screenshot of the
+ * screen -- is a cost with no benefit, since the page never needs to display it.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+
+/** Keys the settings page owns and may write. Anything else in the file is ignored. */
+export const MANAGED_KEYS = [
+  'workers',
+  'approvalTimeoutMs',
+  'requiredTier',
+  'heartbeatMs',
+  // Added along with the page controls for them. A key the page can SAVE but that is not
+  // managed here would be dropped on the next read -- the quiet way a setting seems to work
+  // once and then reverts.
+  'keepShots',
+  // The byte ceiling that sits beside `keepShots`. Added here in the same change that added the
+  // control, because the note below records what happens when it is not: the key round-trips
+  // through disk and then reverts on the next read.
+  'shotCacheBytes',
+  // Added with the audit-retention controls. These were LEFT OUT here when they shipped, so both
+  // silently reverted: saved to disk, dropped by the merge, and shown as the default again on the
+  // next read. Found 2026-10-15 while adding the third of them, by a guard that now checks the whole
+  // exposed set at once instead of relying on one round-trip test per key.
+  'auditMaxBytes',
+  'auditKeepFiles',
+  // The sandbox mode this machine arms its own remote sessions with.
+  'workerSessionMode',
+  // The model those sessions run with, as `provider/model`. Empty means "whatever the acp profile
+  // configures". It is a deployment value like the mode above: the ACP child's image capability is
+  // decided at startup from the configured route, so it cannot be changed per call.
+  'workerModel',
+  'delegationPolicy',
+  // The worker role: whether this machine accepts remote execution, on which interface, and
+  // the credential a paired master presents. It holds a secret, so anything that renders it
+  // for the page must go through the mask (see core/worker-arming.js).
+  'workerRole',
+]
+
+/** Fields of one worker the page may write. */
+export const WORKER_KEYS = ['id', 'name', 'url', 'token', 'cwd', 'enabled', 'serialQueue']
+
+/**
+ * Root of this installation's state.
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function resolveDshHome(env = process.env) {
+  const fromEnv = typeof env.DSH_HOME === 'string' && env.DSH_HOME.trim() !== '' ? env.DSH_HOME.trim() : ''
+  return fromEnv !== '' ? fromEnv : join(homedir(), '.dsh')
+}
+
+/** @param {Record<string, string | undefined>} [env] */
+export function settingsPath(env = process.env) {
+  return join(resolveDshHome(env), 'storages', 'dsh-plugin-remote-use', 'settings.json')
+}
+
+/** Keep the last few characters so an operator can tell two tokens apart without seeing either. */
+export function maskToken(token) {
+  if (typeof token !== 'string' || token === '') return ''
+  if (token.length <= 4) return '\u2022'.repeat(token.length)
+  return `${'\u2022'.repeat(Math.min(12, token.length - 4))}${token.slice(-4)}`
+}
+
+/** A worker as the PAGE sees it: no token, only whether one is set and a masked hint. */
+export function publicWorker(worker) {
+  const token = typeof worker?.token === 'string' ? worker.token : ''
+  return {
+    id: String(worker?.id ?? ''),
+    name: String(worker?.name ?? ''),
+    url: String(worker?.url ?? ''),
+    cwd: String(worker?.cwd ?? ''),
+    enabled: worker?.enabled !== false,
+    serialQueue: Number.isFinite(worker?.serialQueue) ? Number(worker.serialQueue) : 1,
+    tokenSet: token !== '',
+    tokenHint: maskToken(token),
+  }
+}
+
+/** One worker, normalized. Returns undefined when it lacks the fields a connection needs. */
+export function normalizeWorker(raw) {
+  if (raw === null || typeof raw !== 'object') return undefined
+  const id = typeof raw.id === 'string' ? raw.id.trim() : ''
+  const url = typeof raw.url === 'string' ? raw.url.trim() : ''
+  if (id === '' || url === '') return undefined
+  const worker = {
+    id,
+    name: typeof raw.name === 'string' && raw.name.trim() !== '' ? raw.name.trim() : id,
+    url,
+    cwd: typeof raw.cwd === 'string' ? raw.cwd.trim() : '',
+    enabled: raw.enabled !== false,
+    serialQueue: Number.isFinite(raw.serialQueue) && Number(raw.serialQueue) >= 1 ? Math.floor(Number(raw.serialQueue)) : 1,
+  }
+  // A token may legitimately be absent (an unauthenticated relay), so only carry it when
+  // it is a non-empty string. `undefined` means "leave whatever the profile had".
+  if (typeof raw.token === 'string' && raw.token !== '') worker.token = raw.token
+  return worker
+}
+
+/**
+ * Read the settings file.
+ * @returns {{ settings: object | null, file: string, error: string }}
+ *   `settings: null` means the file does not exist, which is NOT an error: it is the state
+ *   every install starts in, and the caller falls back to the profile patch.
+ */
+export function readSettings(env = process.env) {
+  const file = settingsPath(env)
+  if (!existsSync(file)) return { settings: null, file, error: '' }
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'))
+    if (parsed === null || typeof parsed !== 'object') {
+      return { settings: null, file, error: 'settings file is not a JSON object' }
+    }
+    const settings = {}
+    for (const key of MANAGED_KEYS) {
+      if (parsed[key] !== undefined) settings[key] = parsed[key]
+    }
+    if (Array.isArray(settings.workers)) {
+      settings.workers = settings.workers.map(normalizeWorker).filter((w) => w !== undefined)
+    }
+    return { settings, file, error: '' }
+  } catch (error) {
+    // A corrupt file must not stop the plugin from loading. Report it and fall back.
+    return { settings: null, file, error: `settings file is unreadable: ${error instanceof Error ? error.message : String(error)}` }
+  }
+}
+
+/**
+ * Write the settings file atomically (temp file + rename) so a crash mid-write cannot leave
+ * a half-written file that then fails to parse on the next start.
+ * @returns {{ ok: boolean, file: string, error: string }}
+ */
+export function writeSettings(settings, env = process.env) {
+  const file = settingsPath(env)
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    const payload = {}
+    for (const key of MANAGED_KEYS) {
+      if (settings?.[key] !== undefined) payload[key] = settings[key]
+    }
+    const temp = `${file}.tmp`
+    writeFileSync(temp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+    renameSync(temp, file)
+    return { ok: true, file, error: '' }
+  } catch (error) {
+    return { ok: false, file, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/**
+ * Merge the settings file over the profile configuration.
+ *
+ * @param {object} profileConfig the Cordis config (already normalized)
+ * @param {object | null} settings the settings file contents, or null when absent
+ * @returns {{ config: object, sources: Record<string, 'profile' | 'settings'> }}
+ */
+export function mergeSettings(profileConfig, settings) {
+  const config = { ...profileConfig }
+  const sources = {}
+  for (const key of MANAGED_KEYS) sources[key] = 'profile'
+  if (settings === null || settings === undefined) return { config, sources }
+
+  for (const key of MANAGED_KEYS) {
+    if (settings[key] === undefined) continue
+    // `workers` REPLACES rather than appends. Merging two lists would make a deletion in the
+    // page impossible to express, and a half-applied list is worse than an explicit swap.
+    config[key] = settings[key]
+    sources[key] = 'settings'
+  }
+  return { config, sources }
+}
+
+/**
+ * Apply a page-supplied worker edit onto the current list.
+ *
+ * A blank/omitted token means "keep the existing one": the page never receives the token, so
+ * requiring it on every save would force the operator to re-enter a credential to rename a
+ * worker.
+ *
+ * @param {object[]} workers current list (may contain tokens)
+ * @param {object} edit page-supplied worker
+ * @returns {{ workers: object[], error: string }}
+ */
+export function upsertWorker(workers, edit) {
+  const list = Array.isArray(workers) ? [...workers] : []
+  const candidate = normalizeWorker(edit)
+  if (candidate === undefined) return { workers: list, error: 'a worker needs at least an id and a url' }
+
+  const index = list.findIndex((w) => w?.id === candidate.id)
+  if (edit?.token === undefined || edit?.token === null || edit?.token === '') {
+    if (index >= 0 && typeof list[index].token === 'string') candidate.token = list[index].token
+    else if (index < 0) return { workers: list, error: `worker "${candidate.id}" is new, so it needs a token` }
+  }
+
+  if (index >= 0) list[index] = candidate
+  else list.push(candidate)
+  return { workers: list, error: '' }
+}
+
+/** Remove a worker by id. @returns {{ workers: object[], removed: boolean }} */
+export function removeWorker(workers, id) {
+  const list = Array.isArray(workers) ? [...workers] : []
+  const next = list.filter((w) => w?.id !== id)
+  return { workers: next, removed: next.length !== list.length }
+}