dsh-computers 1.1.0 → 1.3.0

package/cordis.patch.yml

@@ -20,4 +20,6 @@
         heartbeatMs: 20000
         execTimeoutMs: 120000
         execEnabled: true
+        promoteOnTimeout: true
+        minAgentVersion: ''
         maxOutputBytes: 1048576

package/index.js

@@ -11,10 +11,13 @@
  * 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'
 
@@ -25,7 +28,7 @@ export const name = 'dsh-computers'
 export const inject = ['tools', 'webServer']
 
 /** Version reported by `/api/dsh-computers/health` (and asserted by the smoke harness). */
-export const PLUGIN_VERSION = '1.1.0'
+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)
@@ -36,6 +39,8 @@ const ROLES = Object.freeze(['hub', 'runtime', 'both'])
 const DEFAULTS = Object.freeze({
   role: 'both',
   publicUrl: '',
+  promoteOnTimeout: true,
+  minAgentVersion: '',
   stateDir: '',
   keyTtlMinutes: 15,
   heartbeatMs: 20_000,
@@ -108,6 +113,24 @@ export function resolveConfig(raw) {
     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')
@@ -117,6 +140,8 @@ export function resolveConfig(raw) {
   return Object.freeze({
     role,
     publicUrl,
+    promoteOnTimeout,
+    minAgentVersion,
     stateDir,
     keyTtlMinutes: boundedInteger(raw.keyTtlMinutes, 'keyTtlMinutes', DEFAULTS.keyTtlMinutes),
     heartbeatMs: boundedInteger(raw.heartbeatMs, 'heartbeatMs', DEFAULTS.heartbeatMs),
@@ -151,12 +176,14 @@ export function apply(ctx, config) {
   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.
@@ -166,16 +193,19 @@ export function apply(ctx, config) {
       store,
       hub,
       selections,
+      access,
+      fsOps,
       role: resolved.role,
       version: PLUGIN_VERSION,
       agentUrl: AGENT_URL,
       onWarn,
     })
-    createTools({ ctx, config: resolved, store, hub, selections, 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 {

package/lib/access.js

@@ -0,0 +1,397 @@
+/**
+ * Per-session and per-computer access control (the two access dialogs).
+ *
+ * Two independent rules that AND together:
+ * - `sessions[sessionId].allow` — which computers one conversation may use
+ *   (absent = every computer);
+ * - `computers[computerId].presets` — which Agent presets ("Bots") may use one
+ *   computer (absent = every preset).
+ *
+ * Persisted at `${stateDir}/access.json` (atomic, mode 0600, corrupt tolerant).
+ * The store below is pure persistence; `createAccessControl` adds the DSH
+ * preset/agent lookups and the effective-allow helper every enforcement point
+ * shares, so the routes and the tools can never disagree.
+ *
+ * Node builtins only.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { normalizeSessionId } from './selection.js'
+
+/** On-disk schema version. */
+export const ACCESS_STATE_VERSION = 1
+
+/** File name inside the plugin state directory. */
+export const ACCESS_FILE_NAME = 'access.json'
+
+/** Session entries kept (most recently updated win), same budget as selections. */
+export const MAX_ACCESS_SESSIONS = 200
+
+/** Preset id used for a session whose Agent has no (or an unknown) preset. */
+export const DEFAULT_PRESET_ID = 'default'
+
+/** Roster used when the host has no `agentPresets` service. */
+export const FALLBACK_PRESETS = Object.freeze([{ id: DEFAULT_PRESET_ID, name: 'Default' }])
+
+/** A fresh, empty access document. */
+export function emptyAccessState() {
+  return { version: ACCESS_STATE_VERSION, sessions: {}, computers: {} }
+}
+
+/** Normalize a list of ids: trimmed, non-empty, deduplicated, order kept. */
+export function normalizeIdList(value) {
+  if (!Array.isArray(value)) return []
+  const seen = new Set()
+  const out = []
+  for (const entry of value) {
+    if (typeof entry !== 'string') continue
+    const trimmed = entry.trim()
+    if (trimmed === '' || seen.has(trimmed)) continue
+    seen.add(trimmed)
+    out.push(trimmed)
+  }
+  return out
+}
+
+/**
+ * Coerce an arbitrary parsed value into a usable access document.
+ * @param {unknown} raw - parsed JSON (or undefined when the file was missing).
+ * @returns {object} a valid document.
+ */
+export function normalizeAccessState(raw) {
+  const doc = emptyAccessState()
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return doc
+  const sessions = raw.sessions !== null && typeof raw.sessions === 'object' && !Array.isArray(raw.sessions) ? raw.sessions : {}
+  for (const [rawSessionId, entry] of Object.entries(sessions)) {
+    const sessionId = normalizeSessionId(rawSessionId)
+    if (sessionId === null || entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue
+    doc.sessions[sessionId] = {
+      allow: normalizeIdList(entry.allow),
+      updatedAt: typeof entry.updatedAt === 'string' && Number.isFinite(Date.parse(entry.updatedAt))
+        ? new Date(Date.parse(entry.updatedAt)).toISOString()
+        : null,
+    }
+  }
+  const computers = raw.computers !== null && typeof raw.computers === 'object' && !Array.isArray(raw.computers) ? raw.computers : {}
+  for (const [computerId, entry] of Object.entries(computers)) {
+    if (computerId.trim() === '' || entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue
+    doc.computers[computerId.trim()] = {
+      presets: normalizeIdList(entry.presets),
+      updatedAt: typeof entry.updatedAt === 'string' && Number.isFinite(Date.parse(entry.updatedAt))
+        ? new Date(Date.parse(entry.updatedAt)).toISOString()
+        : null,
+    }
+  }
+  return doc
+}
+
+/**
+ * Keep only the `max` most recently updated session rules (missing timestamps
+ * sort last). Mutates in place.
+ * @param {object} doc - access document.
+ * @param {number} [max] - entry budget.
+ * @returns {number} how many entries were dropped.
+ */
+export function pruneAccessSessions(doc, max = MAX_ACCESS_SESSIONS) {
+  const entries = Object.entries(doc.sessions)
+  if (entries.length <= max) return 0
+  const age = ([, entry]) => {
+    const parsed = typeof entry?.updatedAt === 'string' ? Date.parse(entry.updatedAt) : Number.NaN
+    return Number.isFinite(parsed) ? parsed : 0
+  }
+  entries.sort((left, right) => age(right) - age(left))
+  const keep = new Set(entries.slice(0, max).map(([sessionId]) => sessionId))
+  let dropped = 0
+  for (const sessionId of Object.keys(doc.sessions)) {
+    if (keep.has(sessionId)) continue
+    delete doc.sessions[sessionId]
+    dropped += 1
+  }
+  return dropped
+}
+
+/**
+ * Create the access store for one plugin mount.
+ * @param {object} options - store options.
+ * @param {string} options.stateDir - directory holding access.json.
+ * @param {() => number} [options.now] - epoch-millisecond clock (testable).
+ * @param {(message: string) => void} [options.onWarn] - warning sink.
+ * @returns {object} the store.
+ */
+export function createAccessStore({ stateDir, now = Date.now, onWarn = () => {} }) {
+  const file = join(stateDir, ACCESS_FILE_NAME)
+  let doc = emptyAccessState()
+
+  /** Read the document; a corrupt file is set aside, never fatal. */
+  const load = () => {
+    let raw
+    try {
+      raw = readFileSync(file, 'utf8')
+    } catch (error) {
+      if (error && error.code !== 'ENOENT') onWarn(`dsh-computers: cannot read ${file}: ${error.message}`)
+      return emptyAccessState()
+    }
+    try {
+      return normalizeAccessState(JSON.parse(raw))
+    } catch {
+      const aside = `${file}.corrupt-${now()}`
+      try {
+        renameSync(file, aside)
+        onWarn(`dsh-computers: ${file} was not valid JSON; moved to ${aside}`)
+      } catch {
+        onWarn(`dsh-computers: ${file} was not valid JSON`)
+      }
+      return emptyAccessState()
+    }
+  }
+
+  /** Write the document atomically (tmp file in the same directory, then rename). */
+  const persist = () => {
+    try {
+      mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+      const tmp = join(stateDir, `.access.json.${process.pid}.${randomBytes(4).toString('hex')}.tmp`)
+      writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+      try {
+        chmodSync(tmp, 0o600)
+      } catch {
+        // Platforms without POSIX modes (Windows) skip this.
+      }
+      renameSync(tmp, file)
+    } catch (error) {
+      onWarn(`dsh-computers: cannot write ${file}: ${error && error.message ? error.message : error}`)
+    }
+  }
+
+  doc = load()
+  pruneAccessSessions(doc)
+  if (Object.keys(doc.sessions).length > 0 || Object.keys(doc.computers).length > 0) persist()
+
+  /** Store (or reset with null) one session's allow-list. */
+  const setSessionAllow = (sessionId, ids) => {
+    const key = normalizeSessionId(sessionId)
+    if (key === null) throw new TypeError('dsh-computers access: sessionId must be a non-empty string')
+    if (ids === null) {
+      delete doc.sessions[key]
+    } else {
+      doc.sessions[key] = { allow: normalizeIdList(ids), updatedAt: new Date(now()).toISOString() }
+    }
+    pruneAccessSessions(doc)
+    persist()
+  }
+
+  /** Drop one session's rule outright (used by tests/tooling). */
+  const clearSession = (sessionId) => {
+    const key = normalizeSessionId(sessionId)
+    if (key === null) return
+    if (doc.sessions[key] === undefined) return
+    delete doc.sessions[key]
+    persist()
+  }
+
+  return {
+    /** Absolute access.json path (diagnostics + smoke assertions). */
+    file,
+    /**
+     * The session's allow-list, or null when the session may use every
+     * computer (no rule). An empty array means "none".
+     * @param {string} sessionId - session identity.
+     * @returns {string[] | null} raw ids.
+     */
+    sessionAllow(sessionId) {
+      const key = normalizeSessionId(sessionId)
+      if (key === null) return null
+      const entry = doc.sessions[key]
+      return entry === undefined ? null : [...entry.allow]
+    },
+    /** Store the session allow-list (`null` removes the rule = all allowed). */
+    setSessionAllow,
+    /** Remove one session's rule. */
+    clearSession,
+    /**
+     * The computer's allowed preset ids, or null when every preset may use it.
+     * @param {string} computerId - computer id.
+     * @returns {string[] | null} raw ids.
+     */
+    computerPresets(computerId) {
+      if (typeof computerId !== 'string' || computerId.trim() === '') return null
+      const entry = doc.computers[computerId.trim()]
+      return entry === undefined ? null : [...entry.presets]
+    },
+    /** Store the computer's allowed presets (`null` removes the rule = all). */
+    setComputerPresets(computerId, ids) {
+      if (typeof computerId !== 'string' || computerId.trim() === '') {
+        throw new TypeError('dsh-computers access: computerId must be a non-empty string')
+      }
+      const key = computerId.trim()
+      if (ids === null) {
+        delete doc.computers[key]
+      } else {
+        doc.computers[key] = { presets: normalizeIdList(ids), updatedAt: new Date(now()).toISOString() }
+      }
+      persist()
+    },
+    /** Drop every rule attached to one computer (called when it is deleted). */
+    forgetComputer(computerId) {
+      if (typeof computerId !== 'string' || computerId.trim() === '') return
+      const key = computerId.trim()
+      if (doc.computers[key] === undefined) return
+      delete doc.computers[key]
+      persist()
+    },
+    /** Copy of the whole document (diagnostics). */
+    all() {
+      return JSON.parse(JSON.stringify(doc))
+    },
+  }
+}
+
+/* ------------------------------------------------------------------------- */
+/* Preset / agent identity resolution (ctx-bound, not persisted)              */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * The live `agentPresets` service, if this host has one.
+ * @param {object} ctx - Cordis context.
+ * @returns {object | undefined} the service.
+ */
+function agentPresetsOf(ctx) {
+  try {
+    const service = ctx.get('agentPresets')
+    return service === undefined || service === null ? undefined : service
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The preset id bound to an Agent. An unset/unknown preset counts as the
+ * literal `default` (the dialog's roster has that id even without a service).
+ * @param {object} ctx - Cordis context.
+ * @param {object | undefined} agent - live Agent (from `exec.agent`).
+ * @returns {string} preset id.
+ */
+export function presetIdForAgent(ctx, agent) {
+  try {
+    const service = agentPresetsOf(ctx)
+    if (service !== undefined && typeof service.presetForSession === 'function') {
+      const fromAgent = agent?.session
+      if (fromAgent !== undefined && fromAgent !== null) {
+        const preset = service.presetForSession(fromAgent)
+        if (typeof preset === 'string' && preset !== '') return preset
+        return DEFAULT_PRESET_ID
+      }
+    }
+  } catch {
+    // A broken preset service must not change authorization: default it.
+  }
+  return DEFAULT_PRESET_ID
+}
+
+/**
+ * The preset id bound to a session *id* (browser routes have no Agent object).
+ * Looks the live Agent up in the `agents` registry; a non-live session counts
+ * as `default`.
+ * @param {object} ctx - Cordis context.
+ * @param {string} sessionId - session identity.
+ * @returns {string} preset id.
+ */
+export function presetIdForSession(ctx, sessionId) {
+  try {
+    const agents = ctx.get('agents')
+    const agent = agents !== undefined && agents !== null && typeof agents.get === 'function'
+      ? agents.get(sessionId)
+      : undefined
+    if (agent !== undefined && agent !== null) return presetIdForAgent(ctx, agent)
+  } catch {
+    // Unknown session or broken registry: fall back to the default preset.
+  }
+  return DEFAULT_PRESET_ID
+}
+
+/**
+ * The deployment's Agent-preset roster, or the single `default` fallback when
+ * the host has no `agentPresets` service.
+ * @param {object} ctx - Cordis context.
+ * @returns {Promise<Array<{ id: string, name: string }>>} ordered roster.
+ */
+export async function listPresets(ctx) {
+  try {
+    const service = agentPresetsOf(ctx)
+    if (service !== undefined && typeof service.list === 'function') {
+      const rows = await service.list()
+      if (Array.isArray(rows)) {
+        const presets = []
+        const seen = new Set()
+        for (const row of rows) {
+          if (row === null || typeof row !== 'object') continue
+          const id = typeof row.id === 'string' ? row.id.trim() : ''
+          if (id === '' || seen.has(id)) continue
+          seen.add(id)
+          presets.push({ id, name: typeof row.name === 'string' && row.name.trim() !== '' ? row.name.trim() : id })
+        }
+        if (presets.length > 0) return presets
+      }
+    }
+  } catch {
+    // Fall through to the single-preset roster.
+  }
+  return FALLBACK_PRESETS.map((preset) => ({ ...preset }))
+}
+
+/**
+ * The authorization helpers shared by the routes and the tools.
+ * @param {object} options - wiring.
+ * @param {object} options.ctx - Cordis context (agentPresets/agents lookups).
+ * @param {object} options.store - access store.
+ * @returns {object} the access control.
+ */
+export function createAccessControl({ ctx, store }) {
+  /** Whether the session's allow-list permits one computer (absent rule = all). */
+  const sessionAllows = (sessionId, computerId) => {
+    if (sessionId === null || sessionId === undefined) return true
+    const allow = store.sessionAllow(sessionId)
+    if (allow === null) return true
+    return allow.includes(computerId)
+  }
+
+  /** Whether the computer's preset rule permits one preset (absent rule = all). */
+  const presetAllows = (computerId, presetId) => {
+    const presets = store.computerPresets(computerId)
+    if (presets === null) return true
+    return presets.includes(presetId)
+  }
+
+  /** The effective answer: both rules must permit the pair. */
+  const isAllowed = ({ sessionId, presetId, computerId }) => {
+    if (typeof computerId !== 'string' || computerId === '') return false
+    return presetAllows(computerId, presetId) && sessionAllows(sessionId, computerId)
+  }
+
+  /** Only the computers this caller may use, order preserved. */
+  const filterComputers = (computers, { sessionId, presetId }) =>
+    computers.filter((computer) => isAllowed({ sessionId, presetId, computerId: computer.id }))
+
+  /** Actionable denial text the model can relay to the user. */
+  const denialMessage = (computer, presetId) => {
+    const name = computer !== null && typeof computer === 'object' && typeof computer.name === 'string'
+      ? computer.name
+      : 'that computer'
+    return `computer '${name}' is not accessible to this conversation (Agent preset '${presetId}'). `
+      + 'Ask the user to grant access in 管理访问权 (Access management) for this conversation and this computer, then retry.'
+  }
+
+  return {
+    store,
+    presetIdForAgent: (agent) => presetIdForAgent(ctx, agent),
+    presetIdForSession: (sessionId) => presetIdForSession(ctx, sessionId),
+    presets: () => listPresets(ctx),
+    sessionAllows,
+    presetAllows,
+    isAllowed,
+    filterComputers,
+    denialMessage,
+  }
+}

package/lib/fs-ops.js

@@ -0,0 +1,162 @@
+/**
+ * Remote file-operation plumbing over the existing SSE stream (PROTOCOL §11.3).
+ *
+ * Host → agent: one `fs` event `{ requestId, op, path, ... }`.
+ * Agent → host: `POST /api/dsh-computers/agent/fs/result` with the same
+ * `requestId`. No new inbound port, no new connection.
+ *
+ * Every request settles exactly once: an agent answer, the 15 s timeout, the
+ * caller's abort signal, the stream closing, or plugin disposal.
+ *
+ * Node builtins only.
+ */
+
+import { randomBytes } from 'node:crypto'
+
+import { HubError } from './hub.js'
+
+/** Per-request timeout from the protocol. */
+export const FS_REQUEST_TIMEOUT_MS = 15_000
+
+/** Supported operations (the agent-side vocabulary). */
+export const FS_OPS = Object.freeze(['read', 'write', 'list', 'stat', 'mkdir', 'rename', 'delete', 'glob', 'grep'])
+
+/** Mint one file request id: `fsr_` plus 24 hex characters. */
+export function newFsRequestId() {
+  return `fsr_${randomBytes(12).toString('hex')}`
+}
+
+/**
+ * Create the file-operation dispatcher for one plugin mount.
+ * @param {object} options - wiring.
+ * @param {object} options.hub - SSE hub (`send` + `isLive`).
+ * @param {(message: string) => void} [options.onWarn] - warning sink.
+ * @returns {object} the dispatcher (`request`, `settle`, `pendingCount`, `dispose`).
+ */
+export function createFsOps({ hub, onWarn = () => {} }) {
+  /** @type {Map<string, object>} */
+  const pending = new Map()
+  let disposed = false
+
+  /** Detach one request's timers/listeners (idempotent). */
+  const detach = (entry) => {
+    if (entry.timer !== null) {
+      clearTimeout(entry.timer)
+      entry.timer = null
+    }
+    if (entry.signal !== undefined && entry.onAbort !== null) {
+      entry.signal.removeEventListener('abort', entry.onAbort)
+      entry.onAbort = null
+    }
+  }
+
+  /** Settle one request exactly once. */
+  const finish = (entry, error, value) => {
+    if (entry.settled) return false
+    entry.settled = true
+    detach(entry)
+    pending.delete(entry.requestId)
+    if (error !== undefined) entry.reject(error)
+    else entry.resolve(value)
+    return true
+  }
+
+  return {
+    /**
+     * Execute one remote file operation.
+     * @param {object} request - operation inputs.
+     * @param {string} request.computerId - target computer.
+     * @param {string} request.name - display name for error messages.
+     * @param {string} request.op - one of {@link FS_OPS}.
+     * @param {object} request.payload - op-specific fields (`path`, `content`, …).
+     * @param {AbortSignal} [request.signal] - caller cancellation.
+     * @param {number} [request.timeoutMs] - override timeout.
+     * @returns {Promise<object>} the agent's response payload (`ok:true`).
+     */
+    async request({ computerId, name, op, payload = {}, signal, timeoutMs = FS_REQUEST_TIMEOUT_MS }) {
+      if (disposed) throw new HubError('disposed', 'the dsh-computers host plugin is shutting down')
+      if (!FS_OPS.includes(op)) throw new HubError('invalid', `unsupported file operation ${JSON.stringify(op)}`)
+      if (!hub.isLive(computerId)) {
+        throw new HubError('offline', `computer '${name}' is offline; run computer_list to see what is connected`)
+      }
+      const requestId = newFsRequestId()
+      return await new Promise((resolve, reject) => {
+        const entry = {
+          requestId,
+          computerId,
+          op,
+          signal,
+          onAbort: null,
+          timer: null,
+          settled: false,
+          resolve,
+          reject,
+        }
+        pending.set(requestId, entry)
+        const done = (error, value) => finish(entry, error, value)
+
+        entry.timer = setTimeout(() => {
+          hub.send(computerId, 'cancel', { requestId })
+          done(new HubError('timeout', `computer '${name}' did not answer the ${op} request within ${timeoutMs}ms`))
+        }, timeoutMs)
+        if (typeof entry.timer.unref === 'function') entry.timer.unref()
+
+        if (signal !== undefined) {
+          const abort = () => {
+            hub.send(computerId, 'cancel', { requestId })
+            done(new HubError('aborted', `the ${op} request on '${name}' was aborted`))
+          }
+          if (signal.aborted) {
+            abort()
+            return
+          }
+          entry.onAbort = abort
+          signal.addEventListener('abort', abort, { once: true })
+        }
+
+        const sent = hub.send(computerId, 'fs', { requestId, op, ...payload })
+        if (!sent) done(new HubError('offline', `computer '${name}' is offline; run computer_list to see what is connected`))
+      })
+    },
+
+    /**
+     * Settle one request from the agent's `fs/result` POST.
+     * @param {string} computerId - authenticated computer.
+     * @param {unknown} body - response payload.
+     * @returns {boolean} false when the id is unknown/settled or owned elsewhere.
+     */
+    settle(computerId, body) {
+      const requestId = body !== null && typeof body === 'object' ? body.requestId : undefined
+      if (typeof requestId !== 'string') return false
+      const entry = pending.get(requestId)
+      if (entry === undefined || entry.computerId !== computerId) return false
+      if (body.ok !== true) {
+        const message = typeof body.error === 'string' && body.error !== '' ? body.error : 'remote file operation failed'
+        finish(entry, new Error(`${message} (${entry.op} on '${entry.computerId}')`))
+        return true
+      }
+      finish(entry, undefined, body)
+      return true
+    },
+
+    /** Pending request count (diagnostics). */
+    pendingCount: (computerId) => [...pending.values()].filter((entry) => computerId === undefined || entry.computerId === computerId).length,
+
+    /** Fail every pending request for one computer (stream gone). */
+    failComputer(computerId, reason = 'the connection to the computer was lost') {
+      for (const entry of [...pending.values()]) {
+        if (entry.computerId !== computerId) continue
+        onWarn(`dsh-computers: fs request abandoned: ${reason}`)
+        finish(entry, new HubError('offline', reason))
+      }
+    },
+
+    /** Reject every pending request (plugin disposal). */
+    dispose() {
+      disposed = true
+      for (const entry of [...pending.values()]) {
+        finish(entry, new HubError('disposed', 'the dsh-computers host plugin shut down'))
+      }
+    },
+  }
+}