dsh-ssh-workbench 1.6.4 → 1.7.0

package/lib/core/guard.js

@@ -1,25 +1,27 @@
 /**
- * Fallback blacklist for remote bash.
+ * Fallback blacklist for remote commands.
  *
  * Registered through `ctx.tools.guard()`: synchronous, monotonic, and checked
  * after DSH's own pre-execute policy and approval, so no later listener can
- * turn a denial back into a permission. It only inspects commands that will
- * actually run on a managed server (the session has an active target and the
- * tool is a POSIX remote shell: the native `bash` tool on POSIX Hosts, the
- * plugin-owned `remote_bash` tool on Windows Hosts); local bash, file tools and
- * every other tool are untouched.
+ * turn a denial back into a permission.
+ *
+ * There is no session-scoped target state: every remote tool names its own
+ * `server`, so the guard resolves that explicit reference. The native local
+ * `bash`/`pwsh` tools are never inspected — local work is outside this
+ * plugin's remote-command boundary.
  */
 import { classifyCommand } from './gate.js'
 import { classifyPowerShellCommand } from './gate-pwsh.js'
+import { findServerRef } from './server-ref.js'
 
-/** The plugin-owned POSIX shell tool (Windows Hosts have no native bash). */
-export const REMOTE_BASH_TOOL_NAME = 'remote_bash'
+/** The plugin-owned POSIX shell tool. */
+const REMOTE_BASH_TOOL_NAME = 'remote_bash'
 
 /** The plugin-owned PowerShell tool (Windows targets). */
-export const REMOTE_PWSH_TOOL_NAME = 'remote_pwsh'
+const REMOTE_PWSH_TOOL_NAME = 'remote_pwsh'
 
-/** Tools whose command argument runs in a POSIX shell on a managed target. */
-const POSIX_REMOTE_TOOL_NAMES = new Set(['bash', REMOTE_BASH_TOOL_NAME])
+/** Explicit-target batch tool: every task names its own server. */
+const REMOTE_EXEC_TOOL_NAME = 'remote_exec'
 
 export const BLOCK_REASON_PREFIX = 'dsh-ssh-workbench blocked this command: '
 
@@ -31,38 +33,88 @@ export function sessionKeyOf(exec) {
   return typeof id === 'string' && id.length > 0 ? id : undefined
 }
 
+/**
+ * Pick the gate for one explicit server. A record's `platform` is only a hint:
+ * the executor probes the real dialect before running. When facts are not
+ * collected yet, run both blacklists so a stale hint cannot hide a
+ * Windows-only destructive command (and vice versa).
+ */
+function classifyForServer(server, command) {
+  const dialect = server?.facts?.dialect
+  if (dialect === 'windows') return classifyPowerShellCommand(command)
+  if (dialect === 'posix') return classifyCommand(command)
+  const posix = classifyCommand(command)
+  if (posix.decision === 'deny') return posix
+  return classifyPowerShellCommand(command)
+}
+
+function summaryOf(prefix, command) {
+  const text = `${prefix}${command}`.slice(0, 200)
+  return text
+}
+
 /**
  * @param {object} deps
- * @param {object} deps.targets per-session target store
  * @param {(entry: object) => void} [deps.recordActivity]
+ * @param {() => object[]} [deps.loadInventory]
  * @returns {(exec: object) => string|undefined} a `ctx.tools.guard()` handler
  */
-export function createBlacklistGuard({ targets, recordActivity } = {}) {
+export function createBlacklistGuard({ recordActivity, loadInventory } = {}) {
+  function inventory() {
+    if (typeof loadInventory !== 'function') return undefined
+    try {
+      const servers = loadInventory()
+      return Array.isArray(servers) ? servers : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  function guardOne(exec, serverRef, command, label = '') {
+    const ref = typeof serverRef === 'string' ? serverRef.trim() : ''
+    if (!ref || ref.toLowerCase() === 'local') return undefined
+    if (!command.trim()) return undefined
+    const servers = inventory()
+    if (servers === undefined) return undefined
+    const server = findServerRef(servers, ref)
+    if (server === undefined) return undefined
+    const classification = classifyForServer(server, command)
+    if (classification.decision !== 'deny') return undefined
+    try {
+      recordActivity?.({
+        kind: 'exec',
+        server: server.name,
+        sessionId: sessionKeyOf(exec),
+        summary: summaryOf(label, command),
+        outcome: `blocked: ${classification.ruleId}`,
+      })
+    } catch {
+      // Activity recording is best effort and must never change the decision.
+    }
+    return `${BLOCK_REASON_PREFIX}${label}${classification.reason}`
+  }
+
+  /** Check every task independently; one denied task denies the whole batch. */
+  function guardBatch(exec) {
+    const tasks = exec.arguments?.tasks
+    if (!Array.isArray(tasks) || tasks.length === 0) return undefined
+    for (let index = 0; index < tasks.length; index += 1) {
+      const task = tasks[index]
+      if (!task || typeof task !== 'object') continue
+      const command = typeof task.command === 'string' ? task.command : ''
+      const denied = guardOne(exec, task.server, command, `task ${index + 1}: `)
+      if (denied !== undefined) return denied
+    }
+    return undefined
+  }
+
   return function blacklistGuard(exec) {
     try {
       if (!exec) return undefined
-      const isPosix = POSIX_REMOTE_TOOL_NAMES.has(exec.name)
-      const isPowerShell = exec.name === REMOTE_PWSH_TOOL_NAME
-      if (!isPosix && !isPowerShell) return undefined
-      const key = sessionKeyOf(exec)
-      if (key === undefined || !targets) return undefined
-      const binding = targets.get(key)
-      if (!binding || !binding.active) return undefined
+      if (exec.name === REMOTE_EXEC_TOOL_NAME) return guardBatch(exec)
+      if (exec.name !== REMOTE_BASH_TOOL_NAME && exec.name !== REMOTE_PWSH_TOOL_NAME) return undefined
       const command = typeof exec.arguments?.command === 'string' ? exec.arguments.command : ''
-      if (!command.trim()) return undefined
-      const classification = isPowerShell ? classifyPowerShellCommand(command) : classifyCommand(command)
-      if (classification.decision !== 'deny') return undefined
-      try {
-        recordActivity?.({
-          kind: 'exec',
-          server: binding.active,
-          summary: command.slice(0, 200),
-          outcome: `blocked: ${classification.ruleId}`,
-        })
-      } catch {
-        // Activity recording is best effort and must never change the decision.
-      }
-      return `${BLOCK_REASON_PREFIX}${classification.reason}`
+      return guardOne(exec, exec.arguments?.server, command)
     } catch {
       // A guard must never turn its own failure into a denial of unrelated tools.
       return undefined

package/lib/core/live-executions.js

@@ -0,0 +1,101 @@
+/**
+ * In-flight remote executions, for the composer's "current target" indicator.
+ *
+ * This is a display-only projection. It never selects a target, never reaches
+ * a tool, and disappears as soon as the dispatch settles. Every remote tool is
+ * explicit-server, so this map is the only place where the UI can learn what a
+ * running tool is touching.
+ */
+import { sessionKeyOf } from './remote-shell-tool.js'
+import {
+  REMOTE_EDIT_TOOL_NAME,
+  REMOTE_GLOB_TOOL_NAME,
+  REMOTE_GREP_TOOL_NAME,
+  REMOTE_READ_TOOL_NAME,
+  REMOTE_WRITE_TOOL_NAME,
+} from './remote-file-tools.js'
+import { REMOTE_EXEC_TOOL_NAME } from './remote-exec-tool.js'
+
+const SINGLE_SERVER_TOOLS = new Set([
+  'remote_bash',
+  'remote_pwsh',
+  REMOTE_READ_TOOL_NAME,
+  REMOTE_WRITE_TOOL_NAME,
+  REMOTE_EDIT_TOOL_NAME,
+  REMOTE_GLOB_TOOL_NAME,
+  REMOTE_GREP_TOOL_NAME,
+])
+
+/** Extract the explicit server names a remote tool call will touch. */
+export function serversOf(exec) {
+  const name = exec?.name
+  const args = exec?.arguments
+  if (!name || !args || typeof args !== 'object') return []
+  if (name === REMOTE_EXEC_TOOL_NAME) {
+    const tasks = Array.isArray(args.tasks) ? args.tasks : []
+    const names = []
+    for (const task of tasks) {
+      if (task && typeof task.server === 'string' && task.server.length > 0 && !names.includes(task.server)) {
+        names.push(task.server)
+      }
+    }
+    return names
+  }
+  if (!SINGLE_SERVER_TOOLS.has(name)) return []
+  return typeof args.server === 'string' && args.server.length > 0 ? [args.server] : []
+}
+
+/** @param {{ now?: () => number }} [options] */
+export function createLiveExecutions(options = {}) {
+  const now = options.now ?? Date.now
+  let nextToken = 0
+  /** @type {Map<number, { sessionId: string, tool: string, servers: string[], startedAt: number }>} */
+  const active = new Map()
+
+  /** Register one dispatch; returns undefined when this is not a remote call. */
+  function begin(exec) {
+    const servers = serversOf(exec)
+    if (servers.length === 0) return undefined
+    const sessionId = sessionKeyOf(exec)
+    if (!sessionId) return undefined
+    const token = ++nextToken
+    active.set(token, {
+      sessionId,
+      tool: typeof exec.name === 'string' ? exec.name : '',
+      servers,
+      startedAt: now(),
+    })
+    return token
+  }
+
+  function end(token) {
+    if (token !== undefined) active.delete(token)
+  }
+
+  /** @returns {{ count: number, servers: { name: string, count: number, startedAt: number }[] }} */
+  function snapshot(sessionId) {
+    const byName = new Map()
+    let calls = 0
+    for (const entry of active.values()) {
+      if (entry.sessionId !== sessionId) continue
+      calls += 1
+      for (const name of entry.servers) {
+        const previous = byName.get(name)
+        byName.set(name, {
+          name,
+          count: (previous?.count ?? 0) + 1,
+          startedAt: previous ? Math.min(previous.startedAt, entry.startedAt) : entry.startedAt,
+        })
+      }
+    }
+    return { count: calls, servers: [...byName.values()] }
+  }
+
+  function clear(sessionId) {
+    for (const [token, entry] of active) {
+      if (sessionId === undefined || entry.sessionId === sessionId) active.delete(token)
+    }
+  }
+
+  return { begin, end, snapshot, clear, size: () => active.size }
+}

package/lib/core/managed-context.js

@@ -0,0 +1,276 @@
+/**
+ * Per-turn managed-resource context.
+ *
+ * The composer inserts an `@name` chip as plain text. This module treats it as a
+ * hint, not an execution binding: every remote tool call names its own server.
+ * This module injects one compact inventory + tool-rules message per human
+ * turn, so the model never has to read `servers.json` or switch a hidden
+ * session target before acting.
+ *
+ * The message enters the same step (`agent/pre-step` replaces the messages that
+ * enter a step), which `agent.inject()` cannot promise because it splices into
+ * the next step.
+ *
+ * Scope: every agent mode; no preset gating.
+ */
+import { randomUUID } from 'node:crypto'
+
+import { effectiveDialect } from './dialect.js'
+import { loadServers } from './store.js'
+import {
+  TARGET_CONTEXT_KIND,
+  createTargetStore,
+  extractServerMentions,
+  extractUserText,
+  lastHumanMessage,
+} from './mentions.js'
+
+export { TARGET_CONTEXT_KIND }
+
+const DEFAULT_MAX_CONTEXT_SERVERS = 20
+
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function serverLine(server) {
+  const target = `${server.username ?? 'root'}@${server.host}:${server.port ?? 22}`
+  const state = server.enabled === false ? ' · disabled' : ''
+  const dialect = effectiveDialect(server)
+  return `- ${server.name} — ${target} · ${dialect}${state}${factsSummary(server)}`
+}
+
+/** Compact facts summary (hostname only: stable, not a stale capacity snapshot). */
+function factsSummary(server) {
+  const facts = server?.facts
+  if (!facts || typeof facts !== 'object') return ''
+  const hostname = typeof facts.hostname === 'string' ? facts.hostname.trim() : ''
+  return hostname ? ` · ${hostname}` : ''
+}
+
+function localShellName(hostPlatform) {
+  return hostPlatform === 'win32' ? 'pwsh' : 'bash'
+}
+
+/**
+ * Render the model-facing managed-resource context.
+ *
+ * @param {object[]} servers managed inventory
+ * @param {{
+ *   candidates?: string[],
+ *   lastExecuted?: string|null,
+ *   hostPlatform?: 'win32'|'posix',
+ *   maxServers?: number,
+ * }} [hints]
+ */
+export function renderManagedContext(servers, hints = {}) {
+  const inventory = Array.isArray(servers) ? servers.filter(Boolean) : []
+  if (inventory.length === 0) return ''
+  const maxServers = Number.isInteger(hints.maxServers) && hints.maxServers > 0
+    ? hints.maxServers
+    : DEFAULT_MAX_CONTEXT_SERVERS
+  const listed = inventory.slice(0, maxServers)
+  const lines = [`[ssh-workbench] Managed remote resources (${inventory.length}):`]
+  for (const server of listed) lines.push(serverLine(server))
+  if (inventory.length > listed.length) {
+    lines.push(`- … and ${inventory.length - listed.length} more; call remote_exec with a resource name from the workbench UI.`)
+  }
+  lines.push('Remote execution rules:')
+  lines.push(
+    `- The native ${localShellName(hints.hostPlatform)} tool always runs on the local DSH host. Never use it for commands meant for a remote resource.`,
+  )
+  lines.push(
+    '- POSIX resources: remote_bash({ server: "<name>", command: "<command>", workdir?, timeoutMs?, run_in_background? }).',
+  )
+  lines.push(
+    '- Windows resources: remote_pwsh({ server: "<name>", command: "<command>", ... }).',
+  )
+  lines.push(
+    '- Several resources in one step: remote_exec({ tasks: [{ server: "<name>", command: "<command>" }], concurrency? }). Tasks run concurrently and never depend on a remembered target.',
+  )
+  lines.push(
+    '- Pass server explicitly on every call. The resource names above are authoritative; never read ~/.dsh/ssh-workbench/servers.json or other config files to find them.',
+  )
+  lines.push(
+    '- read/write/edit/glob/grep are the native local file tools; they never touch a remote resource.',
+  )
+  lines.push(
+    '- Remote files: remote_read({ server, path, maxBytes? }), remote_glob({ server, pattern, path?, maxResults?, maxDepth? }) and remote_grep({ server, pattern, path?, ignoreCase?, maxResults? }). Use absolute paths or paths under ~.',
+  )
+  if (hints.remoteFileWrite === true) {
+    lines.push(
+      '- Remote writes are enabled: remote_write({ server, path, content }) and remote_edit({ server, path, oldText, newText, replaceAll? }). remote_edit requires one exact match unless replaceAll=true.',
+    )
+  } else {
+    lines.push(
+      '- Remote writes are disabled by config: remote_write/remote_edit will refuse. Use the workbench SFTP panel for uploads, or ask the user to enable remoteFileWrite.',
+    )
+  }
+  const candidates = Array.isArray(hints.candidates) ? hints.candidates.filter(Boolean) : []
+  if (candidates.length > 0) {
+    lines.push(
+      `- The user mentioned: ${candidates.join(', ')}. Prefer these resources when the request is ambiguous, but still pass server explicitly.`,
+    )
+  }
+  const lastExecuted = typeof hints.lastExecuted === 'string' && hints.lastExecuted.length > 0
+    ? hints.lastExecuted
+    : null
+  if (lastExecuted) lines.push(`- Last remote execution in this conversation: ${lastExecuted}.`)
+  lines.push(
+    '- If no resource is named and the request does not identify one, ask the user or use the resource named in the request; do not guess silently.',
+  )
+  return lines.join('\n')
+}
+
+/**
+ * Build one user-role context message, preferring the host's message factory.
+ * `@` symbols are avoided so this message can never be re-matched as a mention.
+ */
+export function buildManagedContextMessage(servers, hints, createUserMessage) {
+  const text = renderManagedContext(servers, hints)
+  const source = {
+    kind: TARGET_CONTEXT_KIND,
+    form: 'notice',
+    summary: 'managed remote resources',
+  }
+  const input = { content: [{ type: 'text', text }], source }
+  if (typeof createUserMessage === 'function') return createUserMessage(input)
+  return { role: 'user', id: `ssh-workbench-context-${randomUUID()}`, ...structuredClone(input) }
+}
+
+/**
+ * Install the resource-context provider.
+ *
+ * @param {object} ctx plugin context
+ * @param {{
+ *   enabled?: boolean,
+ *   remoteAvailable?: boolean,
+ *   hostPlatform?: 'win32'|'posix',
+ *   targets?: object,
+ *   loadInventory?: () => object[],
+ *   loadLastExecuted?: (sessionId: string) => string|null,
+ *   createUserMessage?: Function,
+ * }} [options]
+ */
+export function installManagedContext(ctx, options = {}) {
+  const enabled = options.enabled !== false
+  const remoteAvailable = options.remoteAvailable !== false
+  const loadInventory = options.loadInventory ?? loadServers
+  const targets = options.targets ?? createTargetStore({ loadInventory })
+  const maxContextServers = Number.isInteger(options.maxContextServers) && options.maxContextServers > 0
+    ? options.maxContextServers
+    : DEFAULT_MAX_CONTEXT_SERVERS
+  const warn = (message) => {
+    try {
+      ctx?.logger?.warn?.(`dsh-ssh-workbench: ${message}`)
+    } catch {
+      // Logging must never fail the plugin.
+    }
+  }
+  if (!ctx || typeof ctx.on !== 'function') return { targets }
+
+  let factory = options.createUserMessage
+  const messageFactory = async () => {
+    if (factory !== undefined) return factory
+    try {
+      const mod = await import('@deepseek-ai/dsh-llm')
+      factory = typeof mod.createUserMessage === 'function' ? mod.createUserMessage : null
+    } catch {
+      factory = null
+    }
+    return factory
+  }
+
+  const handler = async (payload, next) => {
+    const decision = await next()
+    try {
+      if (!decision || decision.kind === 'reject' || payload?.signal?.aborted) return decision
+      if (enabled === false) return decision
+      // Never describe a remote world the Host cannot execute in.
+      if (!remoteAvailable) return decision
+      const agent = payload?.agent
+      const session = agent?.session
+      const key = session?.id ?? agent?.id
+      if (typeof key !== 'string' || key.length === 0) return decision
+      let servers
+      try {
+        servers = loadInventory()
+      } catch (error) {
+        warn(`inventory unavailable: ${describeError(error)}`)
+        return decision
+      }
+      if (!Array.isArray(servers) || servers.length === 0) return decision
+      // Restore resumed-Session mention hints once; deriveMessages() is
+      // intentionally skipped on later steps.
+      if (targets.get(key)?.seeded !== true) {
+        try {
+          const history = typeof session?.deriveMessages === 'function' ? session.deriveMessages() : []
+          targets.ensureSeeded(key, history, servers)
+        } catch {
+          targets.ensureSeeded(key, [], servers)
+        }
+      }
+      const human = lastHumanMessage(decision.messages)
+      const mentions = human ? extractServerMentions(extractUserText(human), servers) : []
+      const state = targets.bindMentions(key, mentions, human?.id)
+      if (!state) return decision
+      const changed = state.version !== state.injectedVersion
+      const firstStep = payload?.step === 1
+      if (!changed) {
+        if (!firstStep) return decision
+        // One context message per turn is enough while it is still present in
+        // the step messages. Re-inject after compaction or a new human turn.
+        const hasContext = decision.messages.some((message) => message?.source?.kind === TARGET_CONTEXT_KIND)
+        if (hasContext) return decision
+      }
+      let lastExecuted = null
+      try {
+        lastExecuted = typeof options.loadLastExecuted === 'function' ? options.loadLastExecuted(key) : null
+      } catch {
+        lastExecuted = null
+      }
+      const hints = {
+        candidates: state.candidates,
+        lastExecuted: typeof lastExecuted === 'string' && lastExecuted.length > 0 ? lastExecuted : null,
+        hostPlatform: options.hostPlatform,
+        maxServers: maxContextServers,
+      }
+      const message = buildManagedContextMessage(servers, hints, await messageFactory())
+      targets.markInjected(key, state.version)
+      return { ...decision, messages: [...decision.messages, message] }
+    } catch (error) {
+      warn(`resource context skipped: ${describeError(error)}`)
+      return decision
+    }
+  }
+
+  const offPreStep = ctx.on('agent/pre-step', handler, { prepend: true })
+  const offDisposed = ctx.on('agent/disposed', (disposed) => {
+    try {
+      const session = disposed?.agent?.session
+      const key = session?.id ?? disposed?.agent?.id
+      if (typeof key === 'string') targets.clear(key)
+    } catch {
+      // Best effort cleanup.
+    }
+  })
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(
+      () => () => {
+        try {
+          offPreStep?.()
+        } catch {
+          // Disposal is best effort.
+        }
+        try {
+          offDisposed?.()
+        } catch {
+          // Disposal is best effort.
+        }
+        targets.clearAll?.()
+      },
+      'dsh-ssh-workbench: resource context',
+    )
+  }
+  return { targets, offPreStep, offDisposed }
+}