dsh-computers 1.1.0 → 1.3.0

package/lib/tools.js

@@ -1,30 +1,51 @@
 /**
- * The model-facing half of dsh-computers (PROTOCOL §5): `computer_list`,
- * `computer_exec`, and the short system-prompt section that makes the tools
- * discoverable.
+ * The model-facing half of dsh-computers (PROTOCOL §5, §11.1, §11.2, §11.3).
  *
- * Tool definitions are registered as raw JSON Schema objects (no
- * `@deepseek-ai/*` imports, so the bundle loads in any profile). Argument
- * validation therefore lives here and produces messages the model can act on.
+ * Tools: `computer_list`, `computer_exec` (foreground, background job, or
+ * timeout-promoted job), and the remote file tools `computer_read`,
+ * `computer_write`, `computer_edit`, `computer_glob`, `computer_grep`.
+ *
+ * Every tool resolves the same target: explicit `computer` argument → the
+ * session pin → an actionable error, then applies the same gates in the same
+ * order (activation, agent version, capability, access, presence).
+ *
+ * Tool definitions are raw JSON Schema objects (no `@deepseek-ai/*` imports,
+ * so the bundle loads in any profile), therefore argument validation lives
+ * here and produces messages the model can act on.
  *
  * Node builtins only.
  */
 
 import { HubError } from './hub.js'
 import { normalizeSessionId } from './selection.js'
+import { versionAtLeast, versionsDiffer } from './version.js'
 
-/** Hard cap for one rendered tool result (PROTOCOL §5.2: ~20 000 chars). */
+/** Hard cap for one rendered tool result (~20 000 chars, PROTOCOL §5.2). */
 const MAX_RENDER_CHARS = 20_000
 
 /** Smallest accepted per-call timeout; below this the shell cannot start. */
 const MIN_TIMEOUT_MS = 100
 
-/** Largest accepted per-call timeout (30 minutes). */
+/** Largest accepted per-call foreground timeout (30 minutes). */
 const MAX_TIMEOUT_MS = 30 * 60 * 1000
 
+/**
+ * Timeout sent to the agent for every v2 execution. The HOST owns the
+ * foreground timeout (§11.6.3 promotes instead of killing), so the agent must
+ * not self-kill at the foreground deadline; 24 h is the agent's own cap.
+ */
+const AGENT_MAX_TIMEOUT_MS = 24 * 60 * 60 * 1000
+
 /** Cap on prompt lines / list rows so the context stays small. */
 const MAX_LISTED_COMPUTERS = 12
 
+const COMPUTER_REF_SCHEMA = {
+  type: 'object',
+  properties: { id: { type: 'string' }, name: { type: 'string' } },
+  required: ['id', 'name'],
+  additionalProperties: false,
+}
+
 const COMPUTER_ITEM_SCHEMA = {
   type: 'object',
   properties: {
@@ -42,21 +63,38 @@ const COMPUTER_ITEM_SCHEMA = {
       oneOf: [{ type: 'string' }, { type: 'null' }],
       description: 'Version of the agent running on that machine (null when unknown).',
     },
+    capabilities: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Agent capabilities: exec, fs, pty.',
+    },
+    drift: {
+      type: 'boolean',
+      description: 'True when the agent version differs from this host plugin version.',
+    },
+    updateRequired: {
+      type: 'boolean',
+      description: 'True when the agent is older than the configured minimum and must be upgraded.',
+    },
   },
-  required: ['id', 'name', 'online', 'platformLabel', 'os', 'hostname', 'lastSeenAt', 'agentVersion'],
+  required: ['id', 'name', 'online', 'platformLabel', 'os', 'hostname', 'lastSeenAt', 'agentVersion', 'capabilities', 'drift', 'updateRequired'],
   additionalProperties: false,
 }
 
 const LIST_OUTPUT_SCHEMA = {
   type: 'object',
   properties: {
-    computers: { type: 'array', items: COMPUTER_ITEM_SCHEMA, description: 'Every enrolled computer, online or not.' },
+    computers: { type: 'array', items: COMPUTER_ITEM_SCHEMA, description: 'Every activated computer this conversation may use.' },
     selectedComputerId: {
       oneOf: [{ type: 'string' }, { type: 'null' }],
       description: 'Computer pinned for this session (composer target picker), or null.',
     },
+    hiddenComputerCount: {
+      type: 'number',
+      description: 'Connected computers this conversation may not use (access-controlled), omitted from the list.',
+    },
   },
-  required: ['computers', 'selectedComputerId'],
+  required: ['computers', 'selectedComputerId', 'hiddenComputerCount'],
   additionalProperties: false,
 }
 
@@ -68,10 +106,14 @@ const EXEC_PARAMETERS_SCHEMA = {
       description: 'Optional target: a computer id or name from computer_list (an unambiguous name prefix is accepted). Omit it to use the computer the user pinned in the composer for this session.',
     },
     command: { type: 'string', description: 'Shell command to run on that computer.' },
-    cwd: { type: 'string', description: 'Working directory for the command; defaults to the home directory.' },
+    cwd: { type: 'string', description: 'Working directory; defaults to the computer\'s reported workspace base (usually the home directory).' },
     timeoutMs: {
       type: 'number',
-      description: 'Timeout in milliseconds (defaults to the host exec timeout). The command is cancelled when it expires.',
+      description: 'Foreground timeout in milliseconds (defaults to the host exec timeout). When it expires the host promotes the command to a background job instead of killing it.',
+    },
+    run_in_background: {
+      type: 'boolean',
+      description: 'Return a job id immediately and keep the command running; read it with job_output and stop it with job_kill.',
     },
   },
   required: ['command'],
@@ -79,24 +121,174 @@ const EXEC_PARAMETERS_SCHEMA = {
 }
 
 const EXEC_OUTPUT_SCHEMA = {
-  type: 'object',
-  properties: {
-    computer: {
+  oneOf: [
+    {
       type: 'object',
-      properties: { id: { type: 'string' }, name: { type: 'string' } },
-      required: ['id', 'name'],
+      properties: {
+        computer: COMPUTER_REF_SCHEMA,
+        command: { type: 'string' },
+        exitCode: { oneOf: [{ type: 'number' }, { type: 'null' }], description: 'Exit code, or null when the process died by signal.' },
+        stdout: { type: 'string' },
+        stderr: { type: 'string' },
+        durationMs: { type: 'number' },
+        ok: { type: 'boolean' },
+        timedOut: { type: 'boolean' },
+        truncated: { type: 'boolean' },
+      },
+      required: ['computer', 'command', 'exitCode', 'stdout', 'stderr', 'durationMs', 'ok', 'timedOut', 'truncated'],
       additionalProperties: false,
     },
-    command: { type: 'string' },
-    exitCode: { oneOf: [{ type: 'number' }, { type: 'null' }], description: 'Exit code, or null when the process died by signal.' },
-    stdout: { type: 'string' },
-    stderr: { type: 'string' },
-    durationMs: { type: 'number' },
-    ok: { type: 'boolean' },
-    timedOut: { type: 'boolean' },
+    {
+      type: 'object',
+      properties: {
+        computer: COMPUTER_REF_SCHEMA,
+        command: { type: 'string' },
+        jobId: { type: 'string', description: 'DSH job id: read it with job_output, stop it with job_kill.' },
+        promoted: { type: 'boolean', description: 'True when a foreground timeout was adopted as a background job.' },
+        started: { type: 'boolean', description: 'True when the command was started explicitly in the background.' },
+      },
+      required: ['computer', 'command', 'jobId'],
+      additionalProperties: false,
+    },
+  ],
+}
+
+/** Shared parameter fragment: optional computer target. */
+const OPTIONAL_COMPUTER_ARG = {
+  type: 'string',
+  description: 'Optional target: a computer id or name from computer_list. Omit it to use the computer pinned in the composer.',
+}
+
+const FS_OUTPUT_COMPUTER = COMPUTER_REF_SCHEMA
+
+const READ_PARAMETERS_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: OPTIONAL_COMPUTER_ARG,
+    path: { type: 'string', description: 'Absolute path of the file to read on that computer.' },
+    offset: { type: 'number', description: '0-based line offset to start from (default 0).' },
+    limit: { type: 'number', description: 'Maximum number of lines to return (default 2000, max 20000).' },
+  },
+  required: ['path'],
+  additionalProperties: false,
+}
+
+const READ_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: FS_OUTPUT_COMPUTER,
+    path: { type: 'string' },
+    text: { type: 'string' },
+    lines: { type: 'number' },
+    bytes: { type: 'number' },
     truncated: { type: 'boolean' },
   },
-  required: ['computer', 'command', 'exitCode', 'stdout', 'stderr', 'durationMs', 'ok', 'timedOut', 'truncated'],
+  required: ['computer', 'path', 'text', 'lines', 'bytes', 'truncated'],
+  additionalProperties: false,
+}
+
+const WRITE_PARAMETERS_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: OPTIONAL_COMPUTER_ARG,
+    path: { type: 'string', description: 'Absolute path of the file to write on that computer.' },
+    content: { type: 'string', description: 'Full UTF-8 file content.' },
+    createDirs: { type: 'boolean', description: 'Create parent directories when missing.' },
+  },
+  required: ['path', 'content'],
+  additionalProperties: false,
+}
+
+const WRITE_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: FS_OUTPUT_COMPUTER,
+    path: { type: 'string' },
+    bytes: { type: 'number' },
+    created: { type: 'boolean' },
+  },
+  required: ['computer', 'path', 'bytes', 'created'],
+  additionalProperties: false,
+}
+
+const EDIT_PARAMETERS_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: OPTIONAL_COMPUTER_ARG,
+    path: { type: 'string', description: 'Absolute path of the file to edit on that computer.' },
+    old: { type: 'string', description: 'Exact text to replace; must be unique unless replaceAll is true.' },
+    new: { type: 'string', description: 'Replacement text.' },
+    replaceAll: { type: 'boolean', description: 'Replace every occurrence of `old`.' },
+  },
+  required: ['path', 'old', 'new'],
+  additionalProperties: false,
+}
+
+const EDIT_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: FS_OUTPUT_COMPUTER,
+    path: { type: 'string' },
+    replacements: { type: 'number' },
+    bytes: { type: 'number' },
+  },
+  required: ['computer', 'path', 'replacements', 'bytes'],
+  additionalProperties: false,
+}
+
+const GLOB_PARAMETERS_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: OPTIONAL_COMPUTER_ARG,
+    pattern: { type: 'string', description: 'Glob pattern, for example "**/*.ts".' },
+    cwd: { type: 'string', description: 'Base directory; defaults to the computer\'s workspace base.' },
+  },
+  required: ['pattern'],
+  additionalProperties: false,
+}
+
+const GLOB_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: FS_OUTPUT_COMPUTER,
+    paths: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['computer', 'paths'],
+  additionalProperties: false,
+}
+
+const GREP_PARAMETERS_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: OPTIONAL_COMPUTER_ARG,
+    pattern: { type: 'string', description: 'Regular expression to search for.' },
+    path: { type: 'string', description: 'File or directory to search; defaults to the workspace base.' },
+    include: { type: 'string', description: 'Only search files whose relative path matches this glob.' },
+    maxMatches: { type: 'number', description: 'Maximum number of matches to return (default 500).' },
+  },
+  required: ['pattern'],
+  additionalProperties: false,
+}
+
+const GREP_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    computer: FS_OUTPUT_COMPUTER,
+    matches: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          line: { type: 'number' },
+          text: { type: 'string' },
+        },
+        required: ['path', 'line', 'text'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['computer', 'matches'],
   additionalProperties: false,
 }
 
@@ -110,14 +302,14 @@ function boundRender(text) {
     : `${text.slice(0, MAX_RENDER_CHARS)}\n… output truncated for display (${text.length - MAX_RENDER_CHARS} more characters)`
 }
 
-/**
- * Markdown table for `computer_list`, with the session's pinned target marked
- * by a leading `*` (and named up front, so the model knows what a bare
- * `computer_exec` will hit).
- */
+/** Markdown table for `computer_list`. */
 function renderComputerList(value) {
   const computers = Array.isArray(value?.computers) ? value.computers : []
   if (computers.length === 0) {
+    if (typeof value?.hiddenComputerCount === 'number' && value.hiddenComputerCount > 0) {
+      return `${value.hiddenComputerCount} computer(s) are connected but this conversation may not use any of them. `
+        + 'Ask the user to grant access in 管理访问权 (Access management) for this conversation.'
+    }
     return 'No computers are connected yet. Ask the user to open Settings → 电脑 and use “连接电脑”.'
   }
   const selectedId = typeof value?.selectedComputerId === 'string' ? value.selectedComputerId : null
@@ -125,24 +317,37 @@ function renderComputerList(value) {
   const rows = computers.slice(0, MAX_LISTED_COMPUTERS).map((computer) => {
     const status = computer.online === true ? 'online' : 'offline'
     const lastSeen = typeof computer.lastSeenAt === 'string' ? computer.lastSeenAt : '—'
-    const name = computer.id === selectedId ? `* ${computer.name}` : computer.name
-    return `| ${name} | ${computer.platformLabel} | ${status} | ${lastSeen} |`
+    const name = `${computer.id === selectedId ? '* ' : ''}${computer.name}`
+    const notes = []
+    if (typeof computer.agentVersion === 'string') notes.push(`agent ${computer.agentVersion}`)
+    if (computer.updateRequired === true) notes.push('UPDATE REQUIRED')
+    else if (computer.drift === true) notes.push('drift')
+    if (Array.isArray(computer.capabilities) && computer.capabilities.length > 0) notes.push(computer.capabilities.join(','))
+    return `| ${name} | ${computer.platformLabel} | ${status} | ${notes.join(' · ')} | ${lastSeen} |`
   })
   const lines = []
   if (selected !== undefined) {
     lines.push(`Pinned target for this session: **${selected.name}** (\`computer_exec\` without \`computer\` runs here).`, '')
   }
-  lines.push('| Name | Platform | Status | Last seen |', '|---|---|---|---|', ...rows)
+  lines.push('| Name | Platform | Status | Agent | Last seen |', '|---|---|---|---|---|', ...rows)
   const hidden = computers.length - Math.min(computers.length, MAX_LISTED_COMPUTERS)
   let table = lines.join('\n')
   if (hidden > 0) table += `\n… and ${hidden} more (only the first ${MAX_LISTED_COMPUTERS} are shown)`
-  if (selected !== undefined) table += `\n\nRows marked * are selected in the composer for this session.`
+  if (selected !== undefined) table += '\n\nRows marked * are selected in the composer for this session.'
   return table
 }
 
 /** The protocol's `$ command` / status / stdout / stderr layout. */
 function renderExec(value) {
   const computer = value?.computer ?? {}
+  if (typeof value?.jobId === 'string') {
+    const how = value.promoted === true ? 'promoted a timed-out foreground command to background job' : 'started background job'
+    return boundRender([
+      `$ ${value?.command ?? ''}`,
+      `${how} ${value.jobId} on ${computer.name ?? computer.id ?? 'unknown computer'}`,
+      'Use job_output to read its output and job_kill to stop it.',
+    ].join('\n'))
+  }
   const status = [
     `exit ${value?.exitCode ?? 'signal'}`,
     `${value?.durationMs ?? 0}ms`,
@@ -158,19 +363,105 @@ function renderExec(value) {
   return boundRender(lines.join('\n'))
 }
 
+/** Numbered file content, in the built-in `read` tool's style. */
+function renderRead(value) {
+  const text = typeof value?.text === 'string' ? value.text : ''
+  const header = `${value?.path ?? ''} (${value?.lines ?? 0} lines, ${value?.bytes ?? 0} bytes${value?.truncated === true ? ', truncated' : ''})`
+  const numbered = text.split('\n').map((line, index) => `${String(index + 1).padStart(6, ' ')}\t${line}`).join('\n')
+  return boundRender(`${header}\n\n${numbered}`)
+}
+
+/** Built-in-style write/edit/glob/grep renders. */
+function renderWrite(value) {
+  return `${value?.created === true ? 'Created' : 'Wrote'} ${value?.bytes ?? 0} bytes to ${value?.path ?? ''} on ${value?.computer?.name ?? 'the computer'}`
+}
+
+function renderEdit(value) {
+  return `Applied ${value?.replacements ?? 0} replacement(s) to ${value?.path ?? ''} (${value?.bytes ?? 0} bytes) on ${value?.computer?.name ?? 'the computer'}`
+}
+
+function renderGlob(value) {
+  const paths = Array.isArray(value?.paths) ? value.paths : []
+  if (paths.length === 0) return 'No matching files.'
+  return boundRender(`Found ${paths.length} path(s) on ${value?.computer?.name ?? 'the computer'}:\n${paths.join('\n')}`)
+}
+
+function renderGrep(value) {
+  const matches = Array.isArray(value?.matches) ? value.matches : []
+  if (matches.length === 0) return 'No matches.'
+  return boundRender(`${matches.length} match(es) on ${value?.computer?.name ?? 'the computer'}:\n`
+    + matches.map((match) => `${match.path}:${match.line}: ${match.text}`).join('\n'))
+}
+
+/** Outcome mapping for a DSH job fed by a remote execution. */
+const jobOutcome = (result) => {
+  if (result.killed === true) return { status: 'killed', detail: 'cancelled' }
+  if (result.ok === true && result.timedOut !== true) {
+    return { status: 'completed', detail: `exit ${result.exitCode ?? 0}${result.truncated === true ? ', output truncated' : ''}` }
+  }
+  return { status: 'failed', detail: result.error ?? `exit ${result.exitCode ?? result.signal ?? '?'}` }
+}
+
+/** Absolute POSIX or Windows path? (the agent requires absolute paths). */
+const isAbsolutePath = (value) => typeof value === 'string' && /^(\/|[A-Za-z]:[\\/]|\\\\)/.test(value.trim())
+
 /**
  * Register the tools and the system-prompt section for one plugin mount.
  * @param {object} options - wiring.
- * @param {object} options.ctx - Cordis context (tools + optional systemPrompt).
+ * @param {object} options.ctx - Cordis context (tools, systemPrompt, jobs).
  * @param {object} options.config - resolved plugin config.
  * @param {object} options.store - registry store.
  * @param {object} options.hub - SSE/exec hub.
+ * @param {object} options.selections - per-session selection store.
+ * @param {object} options.access - access control.
+ * @param {object} options.fsOps - remote file dispatcher.
+ * @param {string} options.version - plugin version (drift baseline).
  * @param {(message: string) => void} [options.onWarn] - warning sink.
  */
-export function createTools({ ctx, config, store, hub, selections = null, onWarn = () => {} }) {
-  /** Resolve `computer` by exact id, exact name, then unique substring. */
+export function createTools({
+  ctx, config, store, hub, selections = null, access = null, fsOps = null, version = '1.0.0', onWarn = () => {},
+}) {
+  /** Live `jobs` service, when the composition has one. */
+  const jobsOf = () => {
+    try {
+      const service = ctx.get('jobs')
+      return service === undefined || service === null ? undefined : service
+    } catch {
+      return undefined
+    }
+  }
+
+  /** §11.6.4: only activated computers exist for tools. */
+  const visibleComputers = () => store.read().computers.filter((computer) => typeof computer.activatedAt === 'string')
+
+  /** Agent capabilities; a v1 agent reports none and is exec-only. */
+  const capabilitiesOf = (computer) => (Array.isArray(computer.capabilities) && computer.capabilities.length > 0
+    ? computer.capabilities
+    : ['exec'])
+
+  /** The computer's reported default working directory. */
+  const workspaceBaseOf = (computer) => (typeof computer.workspaceBase === 'string' && computer.workspaceBase !== ''
+    ? computer.workspaceBase
+    : null)
+
+  /** §11.6.5: reject tool calls against an agent below the configured minimum. */
+  const requireCurrentAgent = (computer) => {
+    if (versionAtLeast(computer.agentVersion, config.minAgentVersion)) return
+    throw new Error(`computer '${computer.name}' runs agent ${computer.agentVersion ?? 'unknown'}, older than the required v${config.minAgentVersion}. `
+      + `Ask the user to upgrade the agent on that machine (re-run the install command / update the desktop plugin) before using it.`)
+  }
+
+  /** §11.1: a tool that needs a capability must say so when the agent lacks it. */
+  const requireCapability = (computer, capability, feature) => {
+    const capabilities = capabilitiesOf(computer)
+    if (capabilities.includes(capability)) return
+    throw new Error(`computer '${computer.name}' does not support ${feature}: its agent reports [${capabilities.join(', ')}] but not '${capability}'. `
+      + 'Ask the user to upgrade the agent on that machine.')
+  }
+
+  /** Resolve `computer` by exact id, exact name, then unique substring (activated only). */
   const resolveComputer = (query) => {
-    const computers = store.read().computers
+    const computers = visibleComputers()
     if (computers.length === 0) {
       throw new Error('no computers are connected to this deployment; ask the user to connect one from Settings → 电脑')
     }
@@ -191,15 +482,7 @@ export function createTools({ ctx, config, store, hub, selections = null, onWarn
     throw new Error(`no computer matches '${query}'; available computers: ${available}. Run computer_list for details.`)
   }
 
-  /**
-   * The caller's session identity.
-   *
-   * `exec.agent.id` IS the session-backed Agent identity (`SessionId`), and the
-   * live runtime face additionally exposes the same value as `agent.session.id`
-   * (see core/agent/src/types.ts: `readonly id: SessionId`, "Session-backed
-   * Agent identity"). Both are read so a future handle shape cannot silently
-   * disable the composer default.
-   */
+  /** The caller's session identity (`exec.agent.id` / `agent.session.id`). */
   const sessionIdOf = (exec) => {
     const agent = exec?.agent
     if (agent === undefined || agent === null) return null
@@ -214,9 +497,16 @@ export function createTools({ ctx, config, store, hub, selections = null, onWarn
     if (sessionId === null || selections === null) return null
     const stored = selections.get(sessionId)
     if (stored === null) return null
-    return store.read().computers.some((computer) => computer.id === stored) ? stored : null
+    return visibleComputers().some((computer) => computer.id === stored) ? stored : null
   }
 
+  /** The Agent preset id that owns this tool call (`default` when unknown). */
+  const presetIdOf = (exec) => (access === null ? 'default' : access.presetIdForAgent(exec?.agent))
+
+  /** True when the caller's preset + session allow-list permit this computer. */
+  const callerAllowed = (exec, computerId) => access === null
+    || access.isAllowed({ sessionId: sessionIdOf(exec), presetId: presetIdOf(exec), computerId })
+
   /** Explicit argument wins; otherwise the computer pinned in the composer. */
   const resolveTargetComputer = (query, exec) => {
     if (query !== undefined) return resolveComputer(query)
@@ -224,13 +514,95 @@ export function createTools({ ctx, config, store, hub, selections = null, onWarn
     if (selectedId === null) {
       throw new Error('no computer selected: pass `computer` (an id or name from computer_list), or pick a target computer in the composer')
     }
-    const selected = store.read().computers.find((computer) => computer.id === selectedId)
+    const selected = visibleComputers().find((computer) => computer.id === selectedId)
     if (selected === undefined) {
       throw new Error('the computer selected in the composer no longer exists; run computer_list and pick another target')
     }
     return selected
   }
 
+  /** Common gates applied after target resolution, in a stable order. */
+  const gateTarget = (computer, exec, { capability = null, feature = null } = {}) => {
+    requireCurrentAgent(computer)
+    if (capability !== null) requireCapability(computer, capability, feature ?? capability)
+    if (access !== null && !callerAllowed(exec, computer.id)) {
+      throw new Error(access.denialMessage(computer, presetIdOf(exec)))
+    }
+    if (!hub.isOnline(computer)) {
+      throw new Error(`computer '${computer.name}' is offline; run computer_list to see which computers are connected, and ask the user to wake or reconnect it`)
+    }
+    return computer
+  }
+
+  /** Map a hub/fs failure onto actionable model-facing text. */
+  const actionable = (error, computer, timeoutMs) => {
+    if (error instanceof HubError) {
+      switch (error.code) {
+        case 'offline':
+          return new Error(`computer '${computer.name}' is offline; run computer_list to see which computers are connected, and ask the user to wake or reconnect it`)
+        case 'timeout':
+          return new Error(`computer '${computer.name}' did not answer within ${timeoutMs}ms; the command was cancelled. Retry with a larger timeoutMs, or run a shorter command`)
+        case 'aborted':
+          return new Error(`the call on '${computer.name}' was aborted by the caller, and the command was cancelled on that machine`)
+        case 'disposed':
+          return new Error('the dsh-computers host plugin is shutting down; try again in a moment')
+        default:
+          return error
+      }
+    }
+    return error instanceof Error ? error : new Error(String(error))
+  }
+
+  /**
+   * Register one DSH job that feeds on a remote execution (§11.2/§11.6.3).
+   * The returned adapter is what the hub appends chunks into and settles.
+   * Returns null when the composition has no jobs registry.
+   */
+  const createExecJob = ({ computer, command, owner, start }) => {
+    const jobs = jobsOf()
+    if (jobs === undefined || typeof jobs.start !== 'function') return null
+    let handle = null
+    let execution = null
+    let resolveDone = () => {}
+    const done = new Promise((resolve) => {
+      resolveDone = resolve
+    })
+    const sink = {
+      jobId: null,
+      append(channel, text) {
+        try {
+          handle?.append(text, { channel })
+        } catch {
+          // Writes after settlement are dropped by the registry.
+        }
+      },
+      settle(result) {
+        resolveDone(jobOutcome(result))
+      },
+      failed(error) {
+        resolveDone({ status: 'failed', detail: error && error.message ? error.message : String(error) })
+      },
+    }
+    const jobId = jobs.start({
+      kind: 'computer-exec',
+      label: `${computer.name}: ${command}`,
+      ...(owner === null ? {} : { owner }),
+      outputLimitBytes: config.maxOutputBytes,
+      run(jobHandle) {
+        handle = jobHandle
+        execution = start(sink)
+        return {
+          cancel() {
+            if (execution !== null) hub.cancelExecution(computer.id, execution.requestId)
+          },
+          done,
+        }
+      },
+    })
+    sink.jobId = jobId
+    return sink
+  }
+
   /** Validate `computer_exec` arguments into a normalized shape. */
   const validateExecArgs = (args) => {
     if (args === null || typeof args !== 'object' || Array.isArray(args)) {
@@ -256,41 +628,51 @@ export function createTools({ ctx, config, store, hub, selections = null, onWarn
       }
       requestedTimeout = Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, Math.trunc(args.timeoutMs)))
     }
-    return { computer, command, cwd, timeoutMs: requestedTimeout ?? config.execTimeoutMs }
+    let runInBackground = false
+    if (args.run_in_background !== undefined && args.run_in_background !== null) {
+      if (typeof args.run_in_background !== 'boolean') throw new Error('computer_exec "run_in_background" must be a boolean')
+      runInBackground = args.run_in_background
+    }
+    return { computer, command, cwd, timeoutMs: requestedTimeout ?? config.execTimeoutMs, runInBackground }
   }
 
-  /** Map a hub failure onto actionable model-facing text (PROTOCOL §5.2). */
-  const actionable = (error, computer, timeoutMs) => {
-    if (error instanceof HubError) {
-      switch (error.code) {
-        case 'offline':
-          return new Error(`computer '${computer.name}' is offline; run computer_list to see which computers are connected, and ask the user to wake or reconnect it`)
-        case 'timeout':
-          return new Error(`computer '${computer.name}' did not finish within ${timeoutMs}ms; the command was cancelled. Retry with a larger timeoutMs, or run a shorter command`)
-        case 'aborted':
-          return new Error(`computer_exec on '${computer.name}' was aborted by the caller, and the command was cancelled on that machine`)
-        case 'disposed':
-          return new Error('the dsh-computers host plugin is shutting down; try again in a moment')
-        default:
-          return error
-      }
+  /** Resolve the target for one remote-file tool call. */
+  const resolveFsComputer = (arg, exec) => {
+    if (fsOps === null) throw new Error('remote file access is unavailable in this deployment')
+    const query = typeof arg === 'string' && arg.trim() !== '' ? arg.trim() : undefined
+    const computer = resolveTargetComputer(query, exec)
+    return gateTarget(computer, exec, { capability: 'fs', feature: 'remote file access' })
+  }
+
+  /** Run one fs op with a clear absolute-path check and error mapping. */
+  const fsCall = async (computer, op, payload, exec) => {
+    try {
+      return await fsOps.request({ computerId: computer.id, name: computer.name, op, payload, signal: exec?.signal })
+    } catch (error) {
+      throw actionable(error, computer, 15_000)
     }
-    return error instanceof Error ? error : new Error(String(error))
   }
 
-  // Each registration is wrapped in its own effect: the tool registry also
-  // owns it, but an explicit effect makes the reload path deterministic.
+  // -------------------------------------------------------------------------
+  // computer_list
+  // -------------------------------------------------------------------------
+
   ctx.effect(() => ctx.tools.register({
     name: 'computer_list',
-    description: 'List the computers connected to this DSH Web deployment (the user\'s own machines), with their platform, online state and last-seen time. Call this before computer_exec to get a valid computer id or name.',
+    description: 'List the activated computers connected to this DSH Web deployment (the user\'s own machines), with platform, online state, agent version/capabilities and the target pinned in the composer. Call this before computer_exec to get a valid computer id or name.',
     parameters: { type: 'object', properties: {}, additionalProperties: false },
     output: {
       schema: LIST_OUTPUT_SCHEMA,
       render: (_args, value) => textBlock(renderComputerList(value)),
     },
     async execute(_args, exec) {
+      const all = visibleComputers()
+      const sessionId = sessionIdOf(exec)
+      const presetId = presetIdOf(exec)
+      const visible = access === null ? all : access.filterComputers(all, { sessionId, presetId })
+      const visibleIds = new Set(visible.map((computer) => computer.id))
       const selectedId = selectedComputerId(exec)
-      const computers = store.read().computers.map((computer) => ({
+      const computers = visible.map((computer) => ({
         id: computer.id,
         name: computer.name,
         online: hub.isOnline(computer),
@@ -299,14 +681,25 @@ export function createTools({ ctx, config, store, hub, selections = null, onWarn
         hostname: computer.hostname ?? '',
         lastSeenAt: typeof computer.lastSeenAt === 'string' ? computer.lastSeenAt : null,
         agentVersion: typeof computer.agentVersion === 'string' ? computer.agentVersion : null,
+        capabilities: capabilitiesOf(computer),
+        drift: versionsDiffer(computer.agentVersion, version),
+        updateRequired: !versionAtLeast(computer.agentVersion, config.minAgentVersion),
       }))
-      return { computers, selectedComputerId: selectedId }
+      return {
+        computers,
+        selectedComputerId: selectedId !== null && visibleIds.has(selectedId) ? selectedId : null,
+        hiddenComputerCount: all.length - visible.length,
+      }
     },
   }), 'dsh-computers: computer_list tool')
 
+  // -------------------------------------------------------------------------
+  // computer_exec
+  // -------------------------------------------------------------------------
+
   ctx.effect(() => ctx.tools.register({
     name: 'computer_exec',
-    description: 'Run one shell command on one of the user\'s connected computers and return its exit code, stdout and stderr. The command runs in that machine\'s own shell (POSIX `sh -lc` on macOS/Linux, `cmd.exe` on Windows); there is no streaming, and the output is capped by the host. The machine must be online — call computer_list first.',
+    description: 'Run one shell command on one of the user\'s connected computers and return its exit code, stdout and stderr. The command runs in that machine\'s own shell; output is capped. Use run_in_background for long-running work (job_output/job_kill). A foreground command that exceeds its timeout is promoted to a background job instead of being killed. The machine must be online — call computer_list first.',
     parameters: EXEC_PARAMETERS_SCHEMA,
     output: {
       schema: EXEC_OUTPUT_SCHEMA,
@@ -318,24 +711,78 @@ export function createTools({ ctx, config, store, hub, selections = null, onWarn
       }
       const input = validateExecArgs(args)
       const computer = resolveTargetComputer(input.computer, exec)
-      if (!hub.isOnline(computer)) {
-        throw new Error(`computer '${computer.name}' is offline; run computer_list to see which computers are connected, and ask the user to wake or reconnect it`)
+      gateTarget(computer, exec)
+      const owner = sessionIdOf(exec)
+      const cwd = input.cwd ?? workspaceBaseOf(computer)
+      const ref = { id: computer.id, name: computer.name }
+
+      if (input.runInBackground === true) {
+        let sink
+        try {
+          sink = createExecJob({
+            computer,
+            command: input.command,
+            owner,
+            start: (jobSink) => hub.startExecution({
+              computerId: computer.id,
+              name: computer.name,
+              command: input.command,
+              cwd,
+              timeoutMs: 0,
+              agentTimeoutMs: AGENT_MAX_TIMEOUT_MS,
+              job: jobSink,
+            }),
+          })
+        } catch (error) {
+          throw actionable(error, computer, input.timeoutMs)
+        }
+        if (sink === null) {
+          throw new Error('background execution is unavailable on this host: the DSH jobs registry is not loaded (load @deepseek-ai/dsh-tool-jobs in the composition)')
+        }
+        return { computer: ref, command: input.command, jobId: sink.jobId, started: true }
       }
+
+      // §11.6.3: a foreground timeout adopts the running command into a job
+      // instead of killing it (unless the operator disabled that).
+      const jobs = jobsOf()
+      const canPromote = config.promoteOnTimeout === true && jobs !== undefined
       let result
       try {
         result = await hub.dispatch({
           computerId: computer.id,
           name: computer.name,
           command: input.command,
-          cwd: input.cwd,
+          cwd,
           timeoutMs: input.timeoutMs,
+          agentTimeoutMs: AGENT_MAX_TIMEOUT_MS,
           signal: exec?.signal,
+          stream: true,
+          onTimeout: canPromote
+            ? (entry) => {
+                try {
+                  // Adopt the existing execution: the job's chunks flow from
+                  // the same pending entry from now on.
+                  return createExecJob({
+                    computer,
+                    command: input.command,
+                    owner,
+                    start: () => ({ requestId: entry.requestId }),
+                  })
+                } catch (error) {
+                  onWarn(`dsh-computers: could not promote timed-out execution: ${error && error.message ? error.message : error}`)
+                  return null
+                }
+              }
+            : null,
         })
       } catch (error) {
         throw actionable(error, computer, input.timeoutMs)
       }
+      if (result !== null && typeof result === 'object' && result.promoted === true) {
+        return { computer: ref, command: input.command, jobId: result.jobId, promoted: true }
+      }
       return {
-        computer: { id: computer.id, name: computer.name },
+        computer: ref,
         command: input.command,
         exitCode: result.exitCode,
         stdout: result.stdout,
@@ -348,16 +795,162 @@ export function createTools({ ctx, config, store, hub, selections = null, onWarn
     },
   }), 'dsh-computers: computer_exec tool')
 
+  // -------------------------------------------------------------------------
+  // Remote file tools (§11.3)
+  // -------------------------------------------------------------------------
+
+  ctx.effect(() => ctx.tools.register({
+    name: 'computer_read',
+    description: 'Read a UTF-8 file from a connected computer. `path` must be absolute. Returns the text, line count, byte count and whether it was truncated. Only works when that machine\'s agent supports file access.',
+    parameters: READ_PARAMETERS_SCHEMA,
+    output: { schema: READ_OUTPUT_SCHEMA, render: (_args, value) => textBlock(renderRead(value)) },
+    async execute(args, exec) {
+      const path = typeof args?.path === 'string' ? args.path : ''
+      if (!isAbsolutePath(path)) throw new Error('computer_read requires an absolute "path"')
+      const computer = resolveFsComputer(args?.computer, exec)
+      const payload = { path: path.trim() }
+      if (typeof args.offset === 'number' && Number.isFinite(args.offset) && args.offset >= 0) payload.offset = Math.trunc(args.offset)
+      if (typeof args.limit === 'number' && Number.isFinite(args.limit) && args.limit > 0) payload.limit = Math.trunc(args.limit)
+      payload.encoding = 'utf8'
+      const response = await fsCall(computer, 'read', payload, exec)
+      const text = typeof response.text === 'string'
+        ? response.text
+        : typeof response.content === 'string'
+          ? Buffer.from(response.content, 'base64').toString('utf8')
+          : ''
+      return {
+        computer: { id: computer.id, name: computer.name },
+        path: typeof response.path === 'string' ? response.path : path,
+        text,
+        lines: typeof response.lines === 'number' ? response.lines : text.split('\n').length,
+        bytes: typeof response.bytes === 'number' ? response.bytes : Buffer.byteLength(text, 'utf8'),
+        truncated: response.truncated === true,
+      }
+    },
+  }), 'dsh-computers: computer_read tool')
+
+  ctx.effect(() => ctx.tools.register({
+    name: 'computer_write',
+    description: 'Write a complete UTF-8 file on a connected computer. `path` must be absolute; set createDirs to create missing parent directories. Overwrites existing content. Only works when that machine\'s agent supports file access.',
+    parameters: WRITE_PARAMETERS_SCHEMA,
+    output: { schema: WRITE_OUTPUT_SCHEMA, render: (_args, value) => textBlock(renderWrite(value)) },
+    async execute(args, exec) {
+      const path = typeof args?.path === 'string' ? args.path : ''
+      if (!isAbsolutePath(path)) throw new Error('computer_write requires an absolute "path"')
+      if (typeof args.content !== 'string') throw new Error('computer_write requires "content"')
+      const computer = resolveFsComputer(args?.computer, exec)
+      const payload = { path: path.trim(), content: args.content, encoding: 'utf8' }
+      if (args.createDirs === true) payload.createDirs = true
+      const response = await fsCall(computer, 'write', payload, exec)
+      return {
+        computer: { id: computer.id, name: computer.name },
+        path: typeof response.path === 'string' ? response.path : path,
+        bytes: typeof response.bytes === 'number' ? response.bytes : Buffer.byteLength(args.content, 'utf8'),
+        created: response.created === true,
+      }
+    },
+  }), 'dsh-computers: computer_write tool')
+
+  ctx.effect(() => ctx.tools.register({
+    name: 'computer_edit',
+    description: 'Replace literal text in one file on a connected computer. `old` must appear exactly once unless replaceAll is true; `new` replaces every match. Read the file first with computer_read. Only works when that machine\'s agent supports file access.',
+    parameters: EDIT_PARAMETERS_SCHEMA,
+    output: { schema: EDIT_OUTPUT_SCHEMA, render: (_args, value) => textBlock(renderEdit(value)) },
+    async execute(args, exec) {
+      const path = typeof args?.path === 'string' ? args.path : ''
+      if (!isAbsolutePath(path)) throw new Error('computer_edit requires an absolute "path"')
+      const oldText = typeof args.old === 'string' ? args.old : ''
+      const newText = typeof args.new === 'string' ? args.new : ''
+      if (oldText === '') throw new Error('computer_edit requires a non-empty "old" string')
+      const replaceAll = args.replaceAll === true
+      const computer = resolveFsComputer(args?.computer, exec)
+      // Read → literal replace → write. Two fs round trips, both with the same
+      // 15 s budget and the caller's signal.
+      const current = await fsCall(computer, 'read', { path: path.trim(), encoding: 'utf8' }, exec)
+      const text = typeof current.text === 'string'
+        ? current.text
+        : typeof current.content === 'string'
+          ? Buffer.from(current.content, 'base64').toString('utf8')
+          : ''
+      const occurrences = text.split(oldText).length - 1
+      if (occurrences === 0) throw new Error(`computer_edit: "old" text was not found in ${path}`)
+      if (occurrences > 1 && !replaceAll) {
+        throw new Error(`computer_edit: "old" text appears ${occurrences} times in ${path}; pass a longer unique snippet or set replaceAll: true`)
+      }
+      const replacements = replaceAll ? occurrences : 1
+      const next = replaceAll ? text.split(oldText).join(newText) : text.replace(oldText, newText)
+      const written = await fsCall(computer, 'write', { path: path.trim(), content: next, encoding: 'utf8' }, exec)
+      return {
+        computer: { id: computer.id, name: computer.name },
+        path: typeof written.path === 'string' ? written.path : path,
+        replacements,
+        bytes: typeof written.bytes === 'number' ? written.bytes : Buffer.byteLength(next, 'utf8'),
+      }
+    },
+  }), 'dsh-computers: computer_edit tool')
+
+  ctx.effect(() => ctx.tools.register({
+    name: 'computer_glob',
+    description: 'Find file paths on a connected computer by glob pattern (for example "**/*.ts"). Relative patterns resolve against the computer\'s workspace base; use cwd to search elsewhere. Only works when that machine\'s agent supports file access.',
+    parameters: GLOB_PARAMETERS_SCHEMA,
+    output: { schema: GLOB_OUTPUT_SCHEMA, render: (_args, value) => textBlock(renderGlob(value)) },
+    async execute(args, exec) {
+      const pattern = typeof args?.pattern === 'string' ? args.pattern.trim() : ''
+      if (pattern === '') throw new Error('computer_glob requires a non-empty "pattern"')
+      const computer = resolveFsComputer(args?.computer, exec)
+      // The agent's `glob` op accepts only {pattern} and anchors relative
+      // patterns at its workspaceBase, so a user-provided cwd is folded in.
+      let effectivePattern = pattern
+      if (typeof args.cwd === 'string' && args.cwd.trim() !== '' && !isAbsolutePath(pattern)) {
+        const base = args.cwd.trim().replace(/[\\/]+$/, '')
+        const separator = base.includes('\\') && !base.includes('/') ? '\\' : '/'
+        effectivePattern = `${base}${separator}${pattern}`
+      }
+      const response = await fsCall(computer, 'glob', { pattern: effectivePattern }, exec)
+      return {
+        computer: { id: computer.id, name: computer.name },
+        paths: Array.isArray(response.paths) ? response.paths.filter((entry) => typeof entry === 'string') : [],
+      }
+    },
+  }), 'dsh-computers: computer_glob tool')
+
+  ctx.effect(() => ctx.tools.register({
+    name: 'computer_grep',
+    description: 'Search file contents on a connected computer with a regular expression. `path` defaults to the computer\'s workspace base; `include` filters by relative glob; results are capped. Only works when that machine\'s agent supports file access.',
+    parameters: GREP_PARAMETERS_SCHEMA,
+    output: { schema: GREP_OUTPUT_SCHEMA, render: (_args, value) => textBlock(renderGrep(value)) },
+    async execute(args, exec) {
+      const pattern = typeof args?.pattern === 'string' ? args.pattern.trim() : ''
+      if (pattern === '') throw new Error('computer_grep requires a non-empty "pattern"')
+      const computer = resolveFsComputer(args?.computer, exec)
+      const payload = { pattern }
+      if (typeof args.path === 'string' && args.path.trim() !== '') payload.path = args.path.trim()
+      if (typeof args.include === 'string' && args.include.trim() !== '') payload.include = args.include.trim()
+      if (typeof args.maxMatches === 'number' && Number.isFinite(args.maxMatches) && args.maxMatches > 0) {
+        payload.maxMatches = Math.trunc(args.maxMatches)
+      }
+      const response = await fsCall(computer, 'grep', payload, exec)
+      const matches = Array.isArray(response.matches)
+        ? response.matches
+            .filter((match) => match !== null && typeof match === 'object')
+            .map((match) => ({
+              path: typeof match.path === 'string' ? match.path : '',
+              line: typeof match.line === 'number' ? Math.trunc(match.line) : 0,
+              text: typeof match.text === 'string' ? match.text : '',
+            }))
+        : []
+      return { computer: { id: computer.id, name: computer.name }, matches }
+    },
+  }), 'dsh-computers: computer_grep tool')
+
   // ---------------------------------------------------------------------------
-  // System prompt section (PROTOCOL §5.3)
+  // System prompt section (PROTOCOL §5.3, §11)
   // ---------------------------------------------------------------------------
   // `systemPrompt` is not in `inject` (it is optional for this plugin), so it
   // is looked up defensively; a host without it keeps working unchanged.
   try {
     const systemPrompt = ctx.get('systemPrompt')
     if (systemPrompt !== undefined && systemPrompt !== null && typeof systemPrompt.section === 'function') {
-      // The nearest centrally allocated slot is COMPUTER_USE; fall back to its
-      // numeric value when the host's table predates that name.
       let order = 3000
       try {
         const resolved = typeof systemPrompt.getSectionOrder === 'function'
@@ -367,19 +960,25 @@ export function createTools({ ctx, config, store, hub, selections = null, onWarn
       } catch {
         // Unknown placement name: keep the numeric fallback.
       }
-      // Wrapped in an effect: a plugin reload must remove the old section, or
-      // the duplicate name 'computers' throws and the section silently vanishes.
       ctx.effect(() => systemPrompt.section({
         name: 'computers',
         order,
-        text: () => {
-          const computers = store.read().computers
+        text: (context) => {
+          const all = visibleComputers()
+          const agent = context !== null && typeof context === 'object' ? context.agent : undefined
+          const presetId = agent === undefined || access === null ? 'default' : access.presetIdForAgent(agent)
+          const computers = access === null
+            ? all
+            : access.filterComputers(all, { sessionId: null, presetId })
           if (computers.length === 0) return ''
           const lines = [
             'You can run shell commands on the user\'s connected computers with `computer_exec`.',
-            'Call `computer_list` to see their ids, names and online state.',
+            'Call `computer_list` to see their ids, names, online state, capabilities and the target pinned in the composer.',
             'The user can pin a target computer in the composer; `computer_exec` without a `computer` argument runs on that pinned computer.',
           ]
+          if (computers.some((computer) => capabilitiesOf(computer).includes('fs'))) {
+            lines.push('Use `computer_read`/`computer_write`/`computer_edit`/`computer_glob`/`computer_grep` for files on machines whose agent supports file access.')
+          }
           for (const computer of computers.slice(0, MAX_LISTED_COMPUTERS)) {
             const state = hub.isOnline(computer) ? 'online' : 'offline'
             lines.push(`- ${computer.name} (${computer.platformLabel ?? 'Unknown'}, ${state})`)