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

package/lib/core/desktop-notify.js

@@ -0,0 +1,173 @@
+/**
+ * Best-effort desktop notification: "an approval is waiting for you".
+ *
+ * WHY THIS EXISTS: the approval queue holds a worker still until a person answers, and measured
+ * on 2026-10-14 the operator had never seen a single prompt -- six requests expired unanswered
+ * while the only sign of them was a row on a settings page nobody had open. The page now polls,
+ * and the model is told in its runtime context, but both of those need the operator to be LOOKING
+ * at the harness. A notification is what reaches someone who is not.
+ *
+ * WHY IT REUSES @hope_phenom/dsh-plugin-notify RATHER THAN ROLLING ITS OWN: that plugin already
+ * carries the platform plumbing (Shell_NotifyIcon balloon, WinRT toast fallback, python/custom
+ * channels) and its own settings. Importing its CODE would couple us to its internals and its
+ * version; invoking its bundled script is a file-level contract that survives it being updated,
+ * and disappears cleanly when the plugin is not installed.
+ *
+ * WHY IT CANNOT BREAK ANYTHING: every failure path returns false. A missing plugin, a missing
+ * interpreter, a policy that blocks PowerShell -- none of them may turn into a failed approval,
+ * because this runs on the approval path. Failures are logged once per kind, not per request.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+/** The sibling plugin whose bundled notifier we borrow. */
+export const NOTIFY_PACKAGE = '@hope_phenom/dsh-plugin-notify'
+
+/** Interpreters tried in order. `pwsh` first, because the bundled script prefers it. */
+const DEFAULT_INTERPRETERS = ['pwsh', 'powershell']
+
+/** How long a notification child may live before we stop caring about it. */
+const DEFAULT_TIMEOUT_MS = 8_000
+
+/**
+ * Absolute path of the sibling plugin's bundled notifier, or '' when it is not installed.
+ *
+ * Resolution walks up from THIS module, so it finds the copy installed beside us in the same
+ * profile's `node_modules`. A bare `import` of the package would instead require a declared
+ * dependency, which would make an optional integration mandatory.
+ *
+ * @param {object} [opts]
+ * @param {(id: string) => string} [opts.resolve] module resolver, injectable for tests
+ * @param {(path: string) => boolean} [opts.exists] existence check, injectable for tests
+ * @returns {string}
+ */
+export function resolveNotifyScript(opts = {}) {
+  const exists = opts.exists ?? existsSync
+  let resolve = opts.resolve
+  if (resolve === undefined) {
+    try {
+      const require = createRequire(import.meta.url)
+      resolve = (id) => require.resolve(id)
+    } catch {
+      return ''
+    }
+  }
+  try {
+    const manifest = resolve(`${NOTIFY_PACKAGE}/package.json`)
+    const script = join(dirname(manifest), 'scripts', 'notify.ps1')
+    return exists(script) ? script : ''
+  } catch {
+    // Not installed, or its exports map hides the manifest: a silent no-op by design.
+    return ''
+  }
+}
+
+/**
+ * Fire one notification and forget about it.
+ *
+ * Never throws and never awaits the child: the caller is holding an approval request open, and a
+ * notification must not add latency to it. Success means "handed to an interpreter", not
+ * "displayed" -- the bundled script reports display failures on its own stderr, which we discard.
+ *
+ * @param {object} opts
+ * @param {string} opts.title
+ * @param {string} opts.message
+ * @param {string} [opts.script] notifier path; resolved on demand when omitted
+ * @param {string[]} [opts.interpreters]
+ * @param {(level: string, message: string) => void} [opts.log]
+ * @param {typeof spawn} [opts.spawnFn] injectable so tests never launch a process
+ * @returns {boolean} whether an interpreter was started
+ */
+export function notifyDesktop(opts) {
+  // The plugin's logger is an OBJECT with `.info`/`.warn` (see `index.js`), so this module accepts
+  // the same shape rather than inventing a second convention. A missing logger is a no-op.
+  const { info, warn } = methods(opts?.log)
+  const spawnFn = opts?.spawnFn ?? spawn
+  const script = typeof opts?.script === 'string' && opts.script !== '' ? opts.script : resolveNotifyScript(opts)
+  if (script === '') return false
+
+  const interpreters = Array.isArray(opts?.interpreters) && opts.interpreters.length > 0
+    ? opts.interpreters
+    : DEFAULT_INTERPRETERS
+  const timeoutMs = Number.isFinite(opts?.timeoutMs) ? Number(opts.timeoutMs) : DEFAULT_TIMEOUT_MS
+  const argv = [
+    '-NoProfile',
+    '-ExecutionPolicy', 'Bypass',
+    '-File', script,
+    '-Title', String(opts?.title ?? 'DSH'),
+    '-Message', String(opts?.message ?? ''),
+    // `Kind`/`Event` are the sibling plugin's own vocabulary; `approval-waiting` is not one of
+    // its turn-end events, so its message templates fall through to the literal text we pass.
+    '-Kind', 'approval',
+    '-Event', 'approval-waiting',
+    '-DurationMs', '10000',
+  ]
+
+  /**
+   * A missing interpreter reports ENOENT through the `error` EVENT, not through `spawn`, so the
+   * fallback cannot be a `for` loop with a flag: by the time the event fires the loop is long
+   * gone. Each attempt hands the next interpreter to the event handler instead.
+   */
+  const attempt = (index) => {
+    if (index >= interpreters.length) return false
+    const interpreter = interpreters[index]
+    let child
+    try {
+      child = spawnFn(interpreter, argv, { stdio: 'ignore', windowsHide: true })
+    } catch (error) {
+      warn(`desktop notification via ${interpreter} could not start: ${describe(error)}`)
+      return attempt(index + 1)
+    }
+
+    let settled = false
+    const timer = timeoutMs > 0
+      ? setTimeout(() => { settled = true; kill(child) }, timeoutMs)
+      : undefined
+    if (typeof timer?.unref === 'function') timer.unref()
+    const finish = () => { settled = true; if (timer !== undefined) clearTimeout(timer) }
+
+    if (typeof child?.once === 'function') {
+      child.once('error', (error) => {
+        if (settled) return
+        finish()
+        warn(`desktop notification via ${interpreter} failed: ${describe(error)}`)
+        attempt(index + 1)
+      })
+      child.once('exit', finish)
+    }
+    if (typeof child?.unref === 'function') child.unref()
+
+    info(`approval notification handed to ${interpreter} (${script})`)
+    return true
+  }
+
+  return attempt(0)
+}
+
+/** @param {unknown} child */
+function kill(child) {
+  try {
+    child?.kill()
+  } catch { /* already gone */ }
+}
+
+/** @param {unknown} error */
+function describe(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Pull `info`/`warn` off a logger object, tolerating a missing or partial one.
+ * @param {unknown} log
+ */
+function methods(log) {
+  const source = log !== null && typeof log === 'object' ? log : {}
+  return {
+    info: typeof source.info === 'function' ? source.info.bind(source) : () => {},
+    warn: typeof source.warn === 'function' ? source.warn.bind(source) : () => {},
+  }
+}
+
+export { DEFAULT_INTERPRETERS, DEFAULT_TIMEOUT_MS, methods as loggerMethods }

package/lib/core/environment-prompt.js

@@ -0,0 +1,76 @@
+/**
+ * Build the "fix this worker's environment" prompt the operator can hand to the worker's own DSH
+ * session.
+ *
+ * WHY IT IS GENERATED HERE AND NOT SHIPPED AS A STATIC BLOCK: the useful parts are FACTS of this
+ * machine -- the selfcheck script's path, DSH_HOME, the armed task directory, and the last report.
+ * A prompt with a placeholder path is the documentation that already failed (same rule as the
+ * sandbox-mediator prescription).
+ *
+ * The long-form instructions live in `lib/tools/selfcheck-fix-prompt.md` (shipped), so the wording
+ * can be edited without touching code; this module only prepends what is machine-specific.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** @returns {string} absolute path of the shipped prompt body */
+export function promptTemplatePath() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'tools', 'selfcheck-fix-prompt.md')
+}
+
+/**
+ * One line per non-passing check, with its own `fix` text -- that is what makes the prompt
+ * actionable instead of a generic checklist.
+ *
+ * @param {object | null} report
+ * @param {string} [reason] why there is no report
+ * @returns {string[]}
+ */
+export function formatReportSummary(report, reason = '') {
+  if (report === null || report === undefined) {
+    return [`- 自检没有产生报告：${reason === '' ? '未知原因' : reason}`]
+  }
+  const checks = Array.isArray(report.checks) ? report.checks : []
+  const lines = [
+    `- verdict: ${String(report.verdict ?? 'unknown')} | blocking=${Number(report.blockingFailures ?? 0)} warn=${Number(report.warnings ?? 0)} unchecked=${Number(report.unchecked ?? 0)}`,
+  ]
+  for (const check of checks) {
+    if (String(check.status ?? '') === 'pass') continue
+    const actual = String(check.actual ?? '').slice(0, 200)
+    const fix = String(check.fix ?? '').slice(0, 200)
+    lines.push(`- ${String(check.id ?? '?')} ${String(check.status ?? '?')}: ${actual}${fix === '' ? '' : ` (fix: ${fix})`}`)
+  }
+  return lines
+}
+
+/**
+ * @param {object} opts
+ * @param {object | null} [opts.report]
+ * @param {string} [opts.reason]
+ * @param {{ scriptPath?: string, home?: string, taskCwd?: string, pluginDir?: string }} [opts.facts]
+ * @returns {{ text: string, scriptPath: string }}
+ */
+export function buildEnvironmentPrompt(opts = {}) {
+  const facts = opts.facts ?? {}
+  let body = ''
+  try {
+    body = readFileSync(promptTemplatePath(), 'utf8')
+  } catch { /* the facts + report are still useful without the long form */ }
+  const factsBlock = [
+    '# 本机事实（插件自动填写，直接照做即可）',
+    '',
+    `- 插件目录：${String(facts.pluginDir ?? '')}`,
+    `- 自检脚本：${String(facts.scriptPath ?? '')}`,
+    `- DSH home：${String(facts.home ?? '')}`,
+    `- 任务目录：${String(facts.taskCwd ?? '') === '' ? '(未设置)' : String(facts.taskCwd)}`,
+    '',
+    '## 最近一次自检',
+    ...formatReportSummary(opts.report ?? null, String(opts.reason ?? '')),
+    '',
+    '---',
+    '',
+    body === '' ? '(提示词正文缺失：按上面报告的 fix 字段逐项处理，然后复跑 selfcheck.ps1。)' : body,
+  ]
+  return { text: factsBlock.join('\n'), scriptPath: String(facts.scriptPath ?? '') }
+}

package/lib/core/relay-supervisor.js

@@ -0,0 +1,278 @@
+/**
+ * The worker-role listener, as a supervised child process.
+ *
+ * WHY IT SUPERVISES `slave/relay.mjs` RATHER THAN REIMPLEMENTING IT: the relay already speaks
+ * the worker's whole surface -- the `dsh-remote/*` RPCs, the ACP pump, `/screenshot`, `/healthz`,
+ * screenshot retention, pairing-string generation -- and it is validated end to end against the
+ * reference worker. A second implementation inside the plugin would be a second thing to keep
+ * correct, and the two would drift exactly where it matters (authentication, the permission
+ * bridge, cancellation).
+ *
+ * WHY IT KEEPS NO POLICY: which address, which port, which token, and whether arming is allowed
+ * at all belong to `worker-arming.js`. This class starts what it is told and reports what
+ * happened, so the security decisions have one home.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+import { effectiveSessionMode } from '../../slave/permission-pairing.mjs'
+
+/** How much of the relay's output is kept for diagnosis. Enough to see a crash, not a log file. */
+const OUTPUT_LIMIT = 8 * 1024
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+/** `slave/` ships next to `lib/`, so the relay is addressed relative to this module. */
+export function relayPath() {
+  return join(HERE, '..', '..', 'slave', 'relay.mjs')
+}
+
+export class RelaySupervisor {
+  /**
+   * @param {object} deps
+   * @param {(file: string, args: string[], opts: object) => object} [deps.spawn] injected for tests
+   * @param {() => object} [deps.launchSpec] the ACP agent spec to hand the relay
+   * @param {string} [deps.relay] override the relay path
+   * @param {{ info?: Function, warn?: Function, error?: Function }} [deps.log]
+   * @param {() => number} [deps.now]
+   */
+  constructor(deps = {}) {
+    this.spawn = deps.spawn ?? spawn
+    this.launchSpec = deps.launchSpec ?? (() => ({ ok: false, error: 'no launch spec resolver injected' }))
+    this.relay = deps.relay ?? relayPath()
+    // The ACP spec file goes in the system temp directory: it carries an argv env, not a secret,
+    // and it must not be written next to the operator's plugin install.
+    this.tempDir = deps.tempDir ?? join(tmpdir(), 'dsh-plugin-remote-use')
+    // How many captures the worker keeps. Read at start time rather than captured once, so a
+    // change on the settings page applies to the next arming instead of the next DSH restart.
+    this.keepShots = deps.keepShots ?? (() => 20)
+    /**
+     * The ARMED task directory, i.e. where a relative transfer path must resolve on this machine.
+     *
+     * It has to be passed to the relay rather than inferred from `process.cwd()`. Measured 2026-10-16:
+     * a supervised relay inherits THIS process's working directory -- the DSH profile directory -- so
+     * `remotePath: "note.txt"` reported success while writing into `...\.dsh\profiles\desktop\`, not
+     * into the directory the operator armed.
+     */
+    this.taskDir = deps.taskDir ?? (() => '')
+    // The worker's byte ceiling for its own captures. 0 means no ceiling, which is the shipped
+    // default: the count above already bounds ordinary use, and a byte ceiling that appeared on
+    // upgrade would start deleting captures the operator never agreed to lose.
+    //
+    // This is the worker's DEFAULT, not the whole story: the page can tighten it live over the
+    // `dsh-remote/shotcache` RPC without re-arming. Passing it here anyway matters because the
+    // capture path prunes BEFORE each capture, so without a CLI default a worker whose master is
+    // offline would grow unbounded between the page's visits.
+    this.shotCacheBytes = deps.shotCacheBytes ?? (() => 0)
+    // A per-installation directory under the OS temp root, NOT the package. A capture is a
+    // transient full-resolution PNG that is pruned on a budget, so temp is where it belongs;
+    // what matters is that it is outside the plugin.
+    this.shotDir = deps.shotDir ?? join(tmpdir(), 'dsh-plugin-remote-use', 'shots')
+    this.specFile = ''
+    /**
+     * The session mode the RUNNING relay was started with, captured from the spec at start time.
+     *
+     * The settings page shows `workerSessionMode` (what will be used on the next arming), while this
+     * is what the live listener will actually spawn. Keeping both is the difference between "I set it
+     * to full access" and "it is running at full access"; without it the page can only assert the
+     * first (PITFALLS F38).
+     */
+    this.sessionMode = ''
+    this.sessionModeFrom = 'nothing'
+    const log = deps.log ?? {}
+    this.log = { info: log.info ?? (() => {}), warn: log.warn ?? (() => {}), error: log.error ?? (() => {}) }
+    this.now = deps.now ?? (() => Date.now())
+
+    this.child = undefined
+    this.pid = 0
+    this.startedAt = 0
+    this.bind = ''
+    this.port = 0
+    this.output = ''
+    this.lastError = ''
+    this.exited = undefined
+  }
+
+  /** True while a listener is believed to be running. */
+  get running() {
+    return this.child !== undefined && this.exited === undefined
+  }
+
+  /**
+   * Start the listener. Throws on anything that would leave the caller believing a port is open
+   * when it is not -- `WorkerArming` turns a throw into a refusal to arm.
+   *
+   * `taskCwd` is passed EXPLICITLY rather than read through a closure. Reading it through
+   * `deps.taskDir()` during a restore hits the temporal dead zone: that restore happens while
+   * `WorkerArming` is still being constructed, so the `arming` binding the closure refers to is
+   * not initialized yet. It also read the OLD value during a normal arm, because `WorkerArming`
+   * called `start()` before assigning the newly requested directory. Both are fixed by taking the
+   * value as an argument from the state machine that already owns it.
+   *
+   * @param {string} bindAddress
+   * @param {number} port
+   * @param {string} token
+   * @param {string} [taskCwd] the armed task directory; omitted means "use deps.taskDir()"
+   */
+  start(bindAddress, port, token, taskCwd) {
+    if (this.running) throw new Error(`the listener is already running on ${this.bind}:${this.port}`)
+    if (!existsSync(this.relay)) throw new Error(`the relay is missing at ${this.relay}`)
+
+    // No default-parameter call to `this.taskDir()`: that would still evaluate the closure before
+    // the caller's explicit value is considered. Only ask the fallback when no value was provided.
+    const taskDir = taskCwd === undefined ? String(this.taskDir() ?? '') : String(taskCwd ?? '')
+
+    const spec = this.launchSpec()
+    if (spec?.ok !== true) throw new Error(`cannot launch this machine's ACP agent: ${spec?.error ?? 'unknown'}`)
+
+    // The relay is handed the ACP agent as a SPEC FILE, not as a command line. That is the
+    // relay's own designed path (`--cmd-file`) and it exists for the same reason this module
+    // builds an argv array: the install directory contains a space, and every attempt to pass
+    // it as a string has been split somewhere along the way -- once already, as
+    // `Cannot find module 'C:\Users\<user>\AppData\Local\Programs\DeepSeek'`.
+    const specFile = join(this.tempDir, `acp-spec-${process.pid}-${port}.json`)
+    try {
+      mkdirSync(this.tempDir, { recursive: true })
+      writeFileSync(specFile, JSON.stringify({
+        command: spec.spec.command,
+        args: spec.spec.args,
+        env: spec.spec.env,
+      }), 'utf8')
+    } catch (error) {
+      throw new Error(`could not write the ACP launch spec: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    this.specFile = specFile
+
+    const args = [
+      this.relay,
+      '--host', bindAddress,
+      '--port', String(port),
+      '--token', token,
+      '--advertise-host', bindAddress,
+      '--cmd-file', specFile,
+      // The plugin starts the relay from inside its own directory, so the relay must not write
+      // its pairing file next to itself: an installed plugin would modify its installation, and
+      // on a link: install that is the operator's source checkout. The master gets the pairing
+      // string from the RPC instead. Caught by running the supervised listener and looking at
+      // the repository.
+      '--pairing-file', '',
+      // A capture is a full-resolution PNG (~9.5 MB measured). Without this the worker kept
+      // every one of them, and the page's setting would only govern the HOST side -- the
+      // larger of the two accumulations would be the one the operator could not control.
+      '--keep-shots', String(this.keepShots()),
+      // Where a RELATIVE transfer path resolves. Passed explicitly for the same reason as every other
+      // path here: the relay's own `process.cwd()` is not the operator's task directory when the
+      // PLUGIN starts the relay, and a wrong answer is silent -- the transfer succeeds, into the wrong
+      // directory, and reports the path the caller asked for.
+      ...(taskDir === '' ? [] : ['--task-dir', taskDir]),
+      // The byte ceiling, beside the count. Both are passed because they bound different things:
+      // the count bounds how many captures exist, the byte budget bounds what they occupy, and a
+      // worker left running a long GUI loop needs the second one to stay inside a disk budget.
+      '--keep-shot-bytes', String(this.shotCacheBytes()),
+      // Where the captures go. WITHOUT THIS the relay uses `join(HERE, 'shots')` -- HERE being the
+      // relay script's own directory, i.e. the plugin's INSTALLATION. On a `link:` install that is
+      // the operator's source checkout, and on a real install it is a directory the plugin has no
+      // business growing. Same defect as the `--pairing-file` one above, found the same way -- by
+      // running the supervised listener and looking at the tree -- because the capture path had
+      // never actually been exercised on this machine until it was.
+      '--shot-dir', this.shotDir,
+    ]
+
+    const child = this.spawn(process.execPath, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      env: { ...process.env, ...spec.spec.env },
+    })
+
+    this.child = child
+    this.pid = child.pid ?? 0
+    this.startedAt = this.now()
+    this.bind = bindAddress
+    this.port = port
+    this.output = ''
+    this.lastError = ''
+    this.exited = undefined
+    // Captured from the SAME spec the relay is reading. `env: process.env` mirrors what the relay
+    // spawn does, so an inherited variable is reported as inherited rather than as the spec's.
+    const mode = effectiveSessionMode({ specEnv: spec.spec.env, env: process.env })
+    this.sessionMode = mode.mode
+    this.sessionModeFrom = mode.from
+
+    const collect = (chunk) => {
+      this.output += String(chunk)
+      if (this.output.length > OUTPUT_LIMIT) this.output = this.output.slice(-OUTPUT_LIMIT)
+    }
+    child.stdout?.on('data', collect)
+    child.stderr?.on('data', collect)
+    child.on('exit', (code, signal) => {
+      this.exited = { code, signal, at: this.now() }
+      // Report it: a listener that died is the difference between "armed" and "reachable", and
+      // the page must not keep claiming the first while the second is false.
+      if (code !== 0 && code !== null) this.log.warn(`the worker listener exited with code ${code}`)
+      this.child = undefined
+      // Nothing is running, so there is no effective mode to report. Leaving the last one here
+      // would let the page compare a dead listener's spec against a live setting.
+      this.sessionMode = ''
+      this.sessionModeFrom = 'nothing'
+    })
+
+    this.log.info(`worker listener started on ${bindAddress}:${port} (pid ${this.pid})`)
+    return { pid: this.pid }
+  }
+
+  /** Stop the listener. Idempotent, and never throws. */
+  stop() {
+    const child = this.child
+    this.child = undefined
+    this.sessionMode = ''
+    this.sessionModeFrom = 'nothing'
+    if (child === undefined) {
+      this.#discardSpec()
+      this.pid = 0
+      return { stopped: false }
+    }
+    try {
+      child.kill()
+    } catch (error) {
+      this.lastError = `could not stop the listener: ${error instanceof Error ? error.message : String(error)}`
+      this.log.warn(this.lastError)
+    }
+    this.#discardSpec()
+    this.pid = 0
+    return { stopped: true }
+  }
+
+  /** What the page shows. */
+  status() {
+    return {
+      running: this.running,
+      pid: this.pid,
+      bindAddress: this.bind,
+      port: this.port,
+      startedAt: this.startedAt,
+      uptimeMs: this.running && this.startedAt > 0 ? Math.max(0, this.now() - this.startedAt) : 0,
+      exited: this.exited ?? null,
+      lastError: this.lastError,
+      // What the LIVE listener will actually spawn. Empty while stopped, so the page cannot compare
+      // a dead spec against the configured value and call it a running mismatch.
+      sessionMode: this.sessionMode,
+      sessionModeFrom: this.sessionModeFrom,
+      specFile: this.specFile,
+      // The tail only: enough to see why it died, not a log relay.
+      output: this.output.slice(-2000),
+    }
+  }
+
+  /** The spec file is transient: leaving it behind would accumulate one per start. */
+  #discardSpec() {
+    if (this.specFile === '') return
+    const file = this.specFile
+    this.specFile = ''
+    try {
+      rmSync(file, { force: true })
+    } catch { /* best effort: a leftover spec file is untidy, not dangerous */ }
+  }
+}