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

package/lib/core/shot-gc.js

@@ -0,0 +1,334 @@
+/**
+ * Screenshot housekeeping.
+ *
+ * WHY THIS EXISTS: every capture leaves a file behind, and a worker screenshot is a
+ * full-resolution PNG -- measured at ~9.5 MB each on the reference worker. A session that
+ * uses screenshots to drive GUI verification produces them steadily, and nothing ever removed
+ * them: the worker's shot directory had reached 56.9 MB across six captures before this was
+ * written, and the host's download directory grows the same way.
+ *
+ * TWO RULES SHAPE THE DESIGN:
+ *
+ *  1. NEVER THROW. Pruning runs as part of taking a screenshot. A full disk or a locked file
+ *     must not turn a successful capture into a failed one, so every failure is reported in
+ *     the result and the caller carries on. The failure mode this avoids -- "I cannot show you
+ *     the screen because I could not delete an old file" -- is strictly worse than the disk
+ *     usage it prevents.
+ *
+ *  2. ONLY TOUCH WHAT THIS PLUGIN WROTE. The host's screenshot directory sits in the system
+ *     temp directory, which is shared with everything else on the machine. Deleting "some old
+ *     files" there would be destructive, so a file is only a candidate when its name matches
+ *     the pattern this plugin generates for that worker.
+ *
+ * WHY THERE IS ALSO A BYTE BUDGET: a COUNT budget does not bound disk usage, it only bounds the
+ * number of files. That is a real distinction and it bit this plugin: the count was 20, so the
+ * budget was believed to be "20 captures", while the directory had reached 218 MB -- and on a
+ * machine whose captures are larger, or whose operator raised the count, the count says nothing
+ * about whether the disk is filling. Byte usage is what the operator actually cares about, so it
+ * is both reported (see `scanShotUsage`) and enforced (see `pruneShots`'s `maxBytes`).
+ */
+import { readdirSync, statSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Default number of screenshots kept per worker. */
+export const DEFAULT_KEEP_SHOTS = 20
+
+/**
+ * Default byte ceiling for one worker's screenshots on the HOST, when the setting is absent.
+ *
+ * 0 means "no byte budget", which is the shipped default on purpose: the count budget already
+ * bounds ordinary use, and an install that upgrades into a byte budget would start deleting
+ * captures the operator never agreed to lose. An operator who wants a hard ceiling sets one.
+ */
+export const DEFAULT_SHOT_CACHE_BYTES = 0
+
+/**
+ * One megabyte, for parsing and rendering the operator-facing budget strings.
+ *
+ * Binary, not decimal: operators compare this number against what Explorer shows, and Explorer
+ * reports MiB while calling it MB. Using 1e6 here would make the page disagree with the folder
+ * it is describing by ~5%, which reads as a bug in the accounting.
+ */
+export const BYTES_PER_MB = 1024 * 1024
+
+/**
+ * Render a byte count the way the settings page shows it.
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes) {
+  const n = Number(bytes)
+  if (!Number.isFinite(n) || n <= 0) return '0 B'
+  if (n < 1024) return `${Math.round(n)} B`
+  if (n < BYTES_PER_MB) return `${(n / 1024).toFixed(1)} KB`
+  if (n < BYTES_PER_MB * 1024) return `${(n / BYTES_PER_MB).toFixed(1)} MB`
+  return `${(n / (BYTES_PER_MB * 1024)).toFixed(2)} GB`
+}
+
+/**
+ * Parse an operator-entered budget. Accepts a bare number of BYTES, or a number with a unit
+ * suffix (`512MB`, `1.5 GB`, `0`).
+ *
+ * WHY A PARSER AND NOT JUST A NUMBER FIELD: the unit an operator thinks in is MB, and a field
+ * that silently wants bytes invites an off-by-a-million typo that then either deletes nothing or
+ * deletes everything. Returns undefined for anything unparseable, so the caller can refuse the
+ * save rather than apply a guess.
+ *
+ * @param {unknown} raw
+ * @returns {number | undefined} bytes, or undefined when unusable
+ */
+export function parseBytes(raw) {
+  if (typeof raw === 'number') return Number.isFinite(raw) ? Math.floor(raw) : undefined
+  if (typeof raw !== 'string') return undefined
+  const text = raw.trim()
+  if (text === '') return undefined
+  // A signed value is meaningful (negative disables), so the sign is captured rather than rejected.
+  const m = /^(-?\d+(?:\.\d+)?)\s*(b|kb|mb|gb|kib|mib|gib)?$/iu.exec(text)
+  if (m === null) return undefined
+  const value = Number(m[1])
+  if (!Number.isFinite(value)) return undefined
+  const unit = (m[2] ?? '').toLowerCase()
+  const scale = unit === '' || unit === 'b'
+    ? 1
+    : unit === 'kb' || unit === 'kib'
+      ? 1024
+      : unit === 'mb' || unit === 'mib'
+        ? BYTES_PER_MB
+        : BYTES_PER_MB * 1024
+  return Math.floor(value * scale)
+}
+
+/**
+ * Files this plugin writes look like `<peerId>-<ISO stamp with : and . replaced>.png`.
+ * The trailing hyphen matters: without it a worker named `w1` would also match `w12`'s files.
+ * @param {string} peerId
+ * @returns {RegExp}
+ */
+export function shotPattern(peerId) {
+  const escaped = String(peerId).replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')
+  return new RegExp(`^${escaped}-\\d{4}-\\d{2}-\\d{2}T[\\d-]+Z\\.png$`, 'u')
+}
+
+/**
+ * List this worker's screenshots in `dir`, newest first.
+ *
+ * Shared by pruning, reporting and clearing so the three can never disagree about which files
+ * count as "ours" -- the definition of that set is the whole safety property here, and two
+ * copies of it would drift.
+ *
+ * @param {string} dir
+ * @param {string} peerId
+ * @returns {{ files: Array<{path: string, name: string, mtimeMs: number, size: number}>, error: string }}
+ */
+function listShots(dir, peerId) {
+  let names
+  try {
+    names = readdirSync(dir)
+  } catch (error) {
+    // A directory that does not exist yet is the normal first-run case, not a failure.
+    if (error?.code === 'ENOENT') return { files: [], error: '' }
+    return { files: [], error: `cannot list ${dir}: ${error.message}` }
+  }
+
+  const pattern = shotPattern(peerId)
+  const files = []
+  for (const name of names) {
+    if (!pattern.test(name)) continue
+    const path = join(dir, name)
+    try {
+      const stat = statSync(path)
+      if (stat.isFile()) files.push({ path, name, mtimeMs: stat.mtimeMs, size: stat.size })
+    } catch { /* vanished between listing and stat; nothing to do */ }
+  }
+
+  // Newest first. The name breaks ties: the stamp is ISO, so it sorts correctly, and a
+  // filesystem with coarse timestamps can hand out identical mtimes.
+  files.sort((a, b) => (b.mtimeMs - a.mtimeMs) || b.name.localeCompare(a.name))
+  return { files, error: '' }
+}
+
+/**
+ * What one worker's screenshots occupy on disk.
+ *
+ * WHY THIS EXISTS: the count budget was the only thing that was bounded, and it was invisible.
+ * An operator whose temp directory had reached 218 MB had no way to see that from the page, and
+ * "a limit nobody can see is indistinguishable from no limit" applies doubly to usage.
+ *
+ * Never throws: this is called on a page load and on a liveness probe, neither of which may fail
+ * because a directory was locked.
+ *
+ * @param {string} dir
+ * @param {string} peerId
+ * @returns {{ files: number, bytes: number, newestAt: number, oldestAt: number, error: string }}
+ */
+export function scanShotUsage(dir, peerId) {
+  const empty = { files: 0, bytes: 0, newestAt: 0, oldestAt: 0, error: '' }
+  if (typeof dir !== 'string' || dir === '' || peerId === undefined || peerId === null || String(peerId) === '') {
+    return empty
+  }
+  const { files, error } = listShots(dir, String(peerId))
+  if (error !== '') return { ...empty, error }
+  let bytes = 0
+  // `listShots` sorts newest first, so the extremes are the ends of the list rather than a scan.
+  for (const file of files) bytes += file.size
+  return {
+    files: files.length,
+    bytes,
+    newestAt: files.length === 0 ? 0 : files[0].mtimeMs,
+    oldestAt: files.length === 0 ? 0 : files[files.length - 1].mtimeMs,
+    error: '',
+  }
+}
+
+/**
+ * Delete all but the newest `keep` screenshots belonging to one worker, then, if `opts.maxBytes`
+ * is a positive budget, delete oldest-first until the survivors fit inside it.
+ *
+ * @param {string} dir
+ * @param {string} peerId
+ * @param {number} keep how many to retain; a non-finite or negative value disables pruning
+ * @param {{ maxBytes?: number, keepNewest?: boolean }} [opts]
+ *   `maxBytes`: byte ceiling for the survivors; non-finite, negative or 0 means no byte budget.
+ *   `keepNewest` (default true): never delete the newest capture in the byte pass even if it
+ *   alone exceeds the budget -- see the note in the body.
+ * @returns {{ ok: boolean, removed: number, kept: number, freedBytes: number,
+ *             overBudgetBytes: number, bytes: number, error: string }}
+ */
+export function pruneShots(dir, peerId, keep, opts = {}) {
+  const nothing = { ok: true, removed: 0, kept: 0, freedBytes: 0, overBudgetBytes: 0, bytes: 0, error: '' }
+  if (typeof dir !== 'string' || dir === '') {
+    return { ...nothing, ok: false, error: 'pruneShots: no directory given' }
+  }
+  const hasCountBudget = Number.isFinite(keep) && keep >= 0
+  const maxBytes = Number(opts?.maxBytes)
+  // Same rule as the count budget, for the same reason: a missing or zero budget means "do not
+  // prune", never "delete everything". The dangerous reading of an absent setting is 0.
+  const hasByteBudget = Number.isFinite(maxBytes) && maxBytes > 0
+  // "No budget at all" is a no-op, but it is NOT an empty cache. Reporting `kept: 0` here would
+  // tell the page that a directory holding forty captures contains none -- two different facts
+  // (nothing was pruned / nothing is there) collapsed into one number, and the wrong one. The
+  // directory is listed so the count is real; a listing failure still reports zeroes.
+  if (!hasCountBudget && !hasByteBudget) {
+    const idle = listShots(dir, peerId)
+    if (idle.error !== '') return nothing
+    let idleBytes = 0
+    for (const file of idle.files) idleBytes += file.size
+    return { ...nothing, kept: idle.files.length, bytes: idleBytes }
+  }
+
+  const { files, error } = listShots(dir, peerId)
+  if (error !== '') return { ...nothing, ok: false, error: `pruneShots: ${error}` }
+
+  // The count pass first: it is a whole-file decision the operator stated explicitly, and it is
+  // cheaper to reason about than a running total.
+  const survivors = hasCountBudget ? files.slice(0, Math.max(0, Math.floor(keep))) : [...files]
+  const doomed = hasCountBudget ? files.slice(Math.max(0, Math.floor(keep))) : []
+
+  // The byte pass. `keepNewest` exists because the newest capture is the one the host is usually
+  // about to read: deleting it to satisfy a byte ceiling would break the download that produced
+  // it, and the master would be left with a screenshot tool that reports success and has no file.
+  // So the byte pass may leave the directory over budget by exactly one capture, and it SAYS SO
+  // through `overBudgetBytes` rather than silently overshooting.
+  //
+  // ⚠️ THE `hasByteBudget` TEST IS LOAD-BEARING AND WAS ONCE MISSING. The loop originally read
+  // `running > maxBytes` alone. With no byte budget, `maxBytes` is 0, and EVERY non-empty
+  // directory is "over" 0 -- so asking for "no ceiling" deleted everything except the newest
+  // capture, which is the exact opposite of what a 0 budget means. It survived the unit tests
+  // because those passed `keep: Infinity`, which returns at the no-budget guard above and never
+  // reaches this loop; the end-to-end probe caught it. A budget of 0 must mean "do not run this
+  // pass at all", so the flag is checked here as well as at the guard.
+  const keepNewest = opts?.keepNewest !== false
+  let running = 0
+  for (const file of survivors) running += file.size
+  for (let i = survivors.length - 1; hasByteBudget && i >= 0 && running > maxBytes; i -= 1) {
+    if (keepNewest && i === 0) break
+    doomed.push(survivors[i])
+    running -= survivors[i].size
+    survivors.splice(i, 1)
+  }
+
+  let removed = 0
+  let freedBytes = 0
+  let firstError = ''
+  for (const file of doomed) {
+    try {
+      unlinkSync(file.path)
+      removed += 1
+      freedBytes += file.size
+    } catch (error) {
+      if (firstError === '') firstError = `cannot delete ${file.name}: ${error.message}`
+    }
+  }
+
+  // Bytes are re-derived from the survivors rather than from the running total: a file whose
+  // unlink failed is still on disk, and reporting it as freed would be a lie the page repeats.
+  let bytes = 0
+  for (const file of survivors) bytes += file.size
+
+  return {
+    ok: firstError === '',
+    removed,
+    kept: survivors.length,
+    freedBytes,
+    overBudgetBytes: hasByteBudget ? Math.max(0, bytes - maxBytes) : 0,
+    bytes,
+    error: firstError,
+  }
+}
+
+/**
+ * Delete every screenshot belonging to one worker, or every screenshot for every worker when
+ * `peerId` is empty.
+ *
+ * WHY THIS IS SEPARATE FROM `pruneShots`: "keep the newest N" and "clear this cache" are
+ * different operator intentions, and expressing the second as `keep: 0` would silently change
+ * meaning the moment someone redefines 0 as "unset". The page has an explicit Clear button, so
+ * the code gets an explicit function for it.
+ *
+ * @param {string} dir
+ * @param {string} [peerId] worker to clear; empty/undefined clears every worker's captures
+ * @returns {{ ok: boolean, removed: number, freedBytes: number, bytes: number, error: string }}
+ */
+export function clearShots(dir, peerId = '') {
+  const nothing = { ok: true, removed: 0, freedBytes: 0, bytes: 0, error: '' }
+  if (typeof dir !== 'string' || dir === '') {
+    return { ...nothing, ok: false, error: 'clearShots: no directory given' }
+  }
+  let names
+  try {
+    names = readdirSync(dir)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return nothing
+    return { ...nothing, ok: false, error: `clearShots: cannot list ${dir}: ${error.message}` }
+  }
+
+  // An empty peer id means "every worker", which is how the page offers one button per directory
+  // rather than one deletion path per worker. The pattern still gates what may be removed: with
+  // no peer id the accepted shape is any `<peerId>-<stamp>.png`, and a foreign file still fails it.
+  const pattern = String(peerId ?? '') === ''
+    ? /^[^-]+(?:-[^-]+)*-\d{4}-\d{2}-\d{2}T[\d-]+Z\.png$/u
+    : shotPattern(String(peerId))
+
+  let removed = 0
+  let freedBytes = 0
+  let bytes = 0
+  let firstError = ''
+  for (const name of names) {
+    const path = join(dir, name)
+    let stat
+    try {
+      stat = statSync(path)
+    } catch { continue }
+    if (!stat.isFile()) continue
+    if (!pattern.test(name)) continue
+    bytes += stat.size
+    try {
+      unlinkSync(path)
+      removed += 1
+      freedBytes += stat.size
+    } catch (error) {
+      if (firstError === '') firstError = `cannot delete ${name}: ${error.message}`
+    }
+  }
+  return { ok: firstError === '', removed, freedBytes, bytes: bytes - freedBytes, error: firstError }
+}

package/lib/core/task-cwd.js

@@ -0,0 +1,50 @@
+/**
+ * The one rule about a task's working directory, shared by both ends of a pairing.
+ *
+ * WHY IT IS SHARED: the directory is a WORKER-side absolute path. The master stores it and sends
+ * it as the ACP session's `cwd`; the worker advertises what it should be inside its pairing
+ * string. Both ends must agree on what "usable" means -- two copies of the rule would drift, and
+ * the drift would look like a worker advertising a path the master then refuses.
+ *
+ * WHY IT MATTERS MORE THAN IT LOOKS (DESIGN §6.4): this is where the task runs AND the scope the
+ * sandbox allows writes to. A relative or empty value does not fail where it is set -- DSH's ACP
+ * server rejects a non-absolute `cwd` with an opaque -32602, and an empty one binds the task to
+ * the relay process's launch directory, so the task writes somewhere nobody chose.
+ *
+ * Two messages, one rule: `assertUsableCwd` is worded for the MASTER configuring a worker (it
+ * names the field to fix), while `isAbsoluteTaskPath` is the bare predicate the WORKER's own
+ * settings page uses to word its own refusal.
+ */
+
+/**
+ * Is this a path a task may be given: absolute, non-empty?
+ *
+ * Windows drive-absolute (`C:\x`, `C:/x`) and POSIX-absolute (`/x`) only. A UNC path is
+ * deliberately not accepted: nothing has been validated against a share, and a task whose scope
+ * is a network path is a different security question than this plugin answers.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isAbsoluteTaskPath(value) {
+  if (typeof value !== 'string') return false
+  const path = value.trim()
+  if (path === '') return false
+  return /^[a-zA-Z]:[\\/]/u.test(path) || path.startsWith('/')
+}
+
+/**
+ * Report why a worker cwd is unusable, or '' when it is fine.
+ *
+ * @param {string} cwd
+ * @returns {string} a human-readable problem, or '' when usable
+ */
+export function assertUsableCwd(cwd) {
+  if (typeof cwd !== 'string' || cwd.trim() === '') {
+    return 'worker cwd is empty -- set `cwd` to an absolute path that exists on the worker'
+  }
+  if (!isAbsoluteTaskPath(cwd)) {
+    return `worker cwd must be an absolute path, got "${cwd}" (a relative path would bind tasks to the relay's launch directory)`
+  }
+  return ''
+}

package/lib/core/task-memory.js

@@ -0,0 +1,163 @@
+/**
+ * 任务内审批记忆（INTERFACES.md 【A】；DESIGN §8.3）。
+ *
+ * 纯内存、无依赖、无 I/O。
+ *
+ * **范围严格限定在单任务内**：跨任务记忆会让「上周批准过写这个目录」静默变成永久授权
+ * （DESIGN §8.3「为什么默认单任务内」）。任务结束必须 `dispose()`；`dispose()` 之后
+ * `lookup()` 恒为 `'unknown'`，且 `noteApprove()` / `noteReject()` 变成 no-op——
+ * 已销毁的记忆绝不能复活授权。
+ *
+ * 三种状态互不覆盖，查询时**拒绝优先**（fail closed）：
+ *   - `noteReject(key)`  → `lookup` = `'rejected'`（即使同一 key 也有批准）
+ *   - `noteApprove(key, { scope: 'task' })` → `'allowed'`，任务内持续有效
+ *   - `noteApprove(key, { scope: 'once' })` → `'allowed'`，由 `consumeOnce()` 用掉一次
+ */
+
+/**
+ * 单任务审批记忆。
+ */
+export class TaskMemory {
+  /** @type {string} */
+  #taskId
+
+  /** @type {Set<string>} */
+  #approvals
+
+  /** @type {Set<string>} */
+  #rejections
+
+  /** @type {Set<string>} */
+  #once
+
+  /** @type {boolean} */
+  #disposed
+
+  /**
+   * @param {string} taskId 任务标识（非字符串按 `''` 处理，不抛错）
+   */
+  constructor(taskId) {
+    this.#taskId = typeof taskId === 'string' ? taskId : ''
+    this.#approvals = new Set()
+    this.#rejections = new Set()
+    this.#once = new Set()
+    this.#disposed = false
+  }
+
+  /**
+   * 是否已 `dispose()`（只读，便于审计/测试）。
+   * @returns {boolean}
+   */
+  get disposed() {
+    return this.#disposed
+  }
+
+  /**
+   * 记下本次批准。
+   *
+   * `scope: 'task'`（默认）＝ 本任务内该类永久有效；`scope: 'once'` ＝ 只放行一次，
+   * 由 `consumeOnce()` 消耗。**未识别的 scope 按 `'once'` 处理**（fail closed：宁可
+   * 只放行一次，也不让一个拼错的 scope 静默放大成任务级授权）。
+   *
+   * 已是任务级批准的 key 再记 `'once'` 不生效（任务级已覆盖，无需降级）。
+   *
+   * @param {string} key 非空字符串（来自 `review-engine.memoryKey`），否则抛 `TypeError`
+   * @param {{ scope?: 'task' | 'once' }} [opts]
+   * @returns {void}
+   */
+  noteApprove(key, { scope = 'task' } = {}) {
+    const k = requireKey(key, 'noteApprove')
+    if (this.#disposed) return
+    if (scope === 'task') {
+      this.#approvals.add(k)
+      this.#once.delete(k)
+      return
+    }
+    if (!this.#approvals.has(k)) this.#once.add(k)
+  }
+
+  /**
+   * 记下本次拒绝。同一 key 在本任务内不再询问（规则引擎会直接拒绝）。
+   * 拒绝会作废该 key 待用的一次性批准；已记录的任务级批准保留在快照里，
+   * 但查询时被拒绝覆盖（`lookup` 恒返回 `'rejected'`）。
+   *
+   * @param {string} key 非空字符串，否则抛 `TypeError`
+   * @returns {void}
+   */
+  noteReject(key) {
+    const k = requireKey(key, 'noteReject')
+    if (this.#disposed) return
+    this.#rejections.add(k)
+    this.#once.delete(k)
+  }
+
+  /**
+   * 查询 key 的记忆状态。查询路径**永不抛错**（决策路径不能因为坏输入挂住审批）。
+   *
+   * @param {unknown} key
+   * @returns {'allowed' | 'rejected' | 'unknown'} 已 `dispose()` 或 key 非法时恒为 `'unknown'`
+   */
+  lookup(key) {
+    if (this.#disposed) return 'unknown'
+    if (typeof key !== 'string' || key === '') return 'unknown'
+    if (this.#rejections.has(key)) return 'rejected'
+    if (this.#approvals.has(key)) return 'allowed'
+    if (this.#once.has(key)) return 'allowed'
+    return 'unknown'
+  }
+
+  /**
+   * 消耗一次 `'once'` 批准；返回 `true` 表示这次放行已用掉。
+   *
+   * `'task'` 作用域的批准不会被消耗（返回 `false`，`lookup` 仍为 `'allowed'`）。
+   * 若该 key 同时被拒绝，批准作废且返回 `false`（拒绝优先）。
+   *
+   * @param {unknown} key
+   * @returns {boolean} key 非法、已 `dispose()`、无 `'once'` 批准、或被拒绝时为 `false`
+   */
+  consumeOnce(key) {
+    if (this.#disposed) return false
+    if (typeof key !== 'string' || key === '') return false
+    if (!this.#once.has(key)) return false
+    this.#once.delete(key)
+    return !this.#rejections.has(key)
+  }
+
+  /**
+   * 快照（每次返回新对象与新数组，调用方改动不影响内部状态）。
+   * @returns {{ taskId: string, approvals: string[], rejections: string[], once: string[] }}
+   */
+  snapshot() {
+    return {
+      taskId: this.#taskId,
+      approvals: [...this.#approvals],
+      rejections: [...this.#rejections],
+      once: [...this.#once],
+    }
+  }
+
+  /**
+   * 清空并标记失效。之后 `lookup()` 恒 `'unknown'`，`noteApprove` / `noteReject` 为 no-op，
+   * `consumeOnce()` 恒 `false`。幂等。
+   * @returns {void}
+   */
+  dispose() {
+    this.#approvals.clear()
+    this.#rejections.clear()
+    this.#once.clear()
+    this.#disposed = true
+  }
+}
+
+/**
+ * 校验记忆键（只用于**写入**路径；查询路径不抛错）。
+ * @param {unknown} key
+ * @param {string} method
+ * @returns {string}
+ */
+function requireKey(key, method) {
+  if (typeof key !== 'string' || key === '') {
+    throw new TypeError(`TaskMemory.${method}(): key must be a non-empty string`)
+  }
+  return key
+}