dsh-ssh-workbench 0.0.0-stage → 1.6.4

package/lib/core/store.js

@@ -0,0 +1,83 @@
+/**
+ * Server inventory: JSON document under the harness home.
+ * Pure data logic; no DSH imports so it stays unit testable without the host
+ * runtime.
+ */
+import { randomUUID } from 'node:crypto'
+import { serversPath, writePrivateFile, readTextFile } from './paths.js'
+
+const PLATFORMS = new Set(['posix', 'windows'])
+
+function defaultShellFor(platform) {
+  return platform === 'windows' ? 'powershell' : 'bash'
+}
+
+function asString(value, fallback = '') {
+  return typeof value === 'string' ? value.trim() : fallback
+}
+
+function asStringArray(value) {
+  if (!Array.isArray(value)) return []
+  return value.map((item) => asString(item)).filter(Boolean)
+}
+
+/**
+ * Validate and canonicalise one stored server record. Throws on records the
+ * plugin could never execute, so a corrupt inventory fails loud at the
+ * boundary instead of deep inside an SSH call.
+ */
+export function normalizeServer(raw, { idFactory = () => `srv_${randomUUID()}` } = {}) {
+  if (!raw || typeof raw !== 'object') throw new Error('server record must be an object')
+  const name = asString(raw.name)
+  const host = asString(raw.host)
+  if (!name) throw new Error('server.name is required')
+  if (!host) throw new Error(`server "${name}" needs a host`)
+  const port = Number.isInteger(raw.port) && raw.port > 0 && raw.port < 65536 ? raw.port : 22
+  const username = asString(raw.username, 'root') || 'root'
+  const platform = PLATFORMS.has(raw.platform) ? raw.platform : 'posix'
+  const authRef = normalizeAuthRef(raw.authRef, name)
+  return {
+    id: asString(raw.id, idFactory()) || idFactory(),
+    name,
+    host,
+    port,
+    username,
+    platform,
+    defaultShell: asString(raw.defaultShell, defaultShellFor(platform)) || defaultShellFor(platform),
+    tags: asStringArray(raw.tags),
+    description: asString(raw.description),
+    enabled: raw.enabled !== false,
+    facts: raw.facts && typeof raw.facts === 'object' ? { ...raw.facts } : {},
+    authRef,
+  }
+}
+
+function normalizeAuthRef(raw, serverName) {
+  if (!raw || typeof raw !== 'object') throw new Error(`server "${serverName}" needs authRef`)
+  if (raw.type === 'sshKey') {
+    const keyPath = asString(raw.path)
+    if (!keyPath) throw new Error(`server "${serverName}" sshKey authRef needs a path`)
+    return { type: 'sshKey', path: keyPath }
+  }
+  if (raw.type === 'password') return { type: 'password' }
+  throw new Error(`server "${serverName}" has unsupported authRef type`)
+}
+
+export function loadServers(file = serversPath()) {
+  const text = readTextFile(file)
+  if (!text.trim()) return []
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`servers.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (!Array.isArray(parsed)) throw new Error('servers.json must be an array')
+  return parsed.map((record) => normalizeServer(record))
+}
+
+export function saveServers(servers, file = serversPath()) {
+  const normalized = servers.map((record) => normalizeServer(record))
+  writePrivateFile(file, `${JSON.stringify(normalized, null, 2)}\n`)
+  return normalized
+}

package/lib/core/targets.js

@@ -0,0 +1,250 @@
+/**
+ * Per-session remote target binding.
+ *
+ * A session owns at most one *active* target: the managed server its native
+ * `bash` tool runs on. `@name` mentions in a human message are the primary
+ * input; the `ssh_workbench_target` tool switches the active target explicitly so a
+ * conversation that mentions several servers stays unambiguous.
+ *
+ * State is process-local and keyed by Session id. It is a derived cache, not a
+ * source of truth: the durable input is the human messages in the Session log,
+ * which `replayTargets()` folds back in when a Session resumes.
+ */
+import { loadServers } from './store.js'
+
+/** Tool name the model calls to switch targets. */
+export const TARGET_TOOL_NAME = 'ssh_workbench_target'
+
+/** Source kind recorded on the injected target-context message. */
+export const TARGET_CONTEXT_KIND = 'ssh-workbench-target'
+
+/** The sentinel that detaches the session from any remote target. */
+export const LOCAL_TARGET = 'local'
+
+/** Concatenate the text blocks of one message. */
+export function extractUserText(message) {
+  if (!message || message.role !== 'user' || !Array.isArray(message.content)) return ''
+  return message.content
+    .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('\n')
+}
+
+/** Find the latest human-authored user message in a step's messages. */
+export function lastHumanMessage(messages) {
+  if (!Array.isArray(messages)) return undefined
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index]
+    if (message && message.role === 'user' && message.source?.kind === 'user') return message
+  }
+  return undefined
+}
+
+/**
+ * Match `@name` tokens against the managed inventory (name or id,
+ * case-insensitive). Returns matched server records in mention order, without
+ * duplicates. Unknown tokens are ignored.
+ */
+export function extractServerMentions(text, servers) {
+  if (typeof text !== 'string' || !Array.isArray(servers) || servers.length === 0) return []
+  const byAlias = new Map()
+  for (const server of servers) {
+    if (!server || typeof server.name !== 'string' || server.name.length === 0) continue
+    byAlias.set(server.name.toLowerCase(), server)
+    if (typeof server.id === 'string' && server.id.length > 0) byAlias.set(server.id.toLowerCase(), server)
+  }
+  // Match known aliases directly instead of a generic `@token` regex: a CJK
+  // server name is often followed immediately by CJK text (`@测试机看下磁盘`),
+  // so only the known name length tells us where the mention ends.
+  const aliases = [...byAlias.keys()].sort((left, right) => right.length - left.length)
+  const seen = new Set()
+  const matched = []
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] !== '@') continue
+    // Like an email address: `ops@example.com` is not a mention.
+    const previous = index > 0 ? text[index - 1] : ''
+    if (previous && /[A-Za-z0-9._-]/.test(previous)) continue
+    for (const alias of aliases) {
+      if (text.slice(index + 1, index + 1 + alias.length).toLowerCase() !== alias) continue
+      const tail = text[index + 1 + alias.length] ?? ''
+      // `@web-12` is a different token than `@web-1`; CJK continuation is fine.
+      if (tail && /[A-Za-z0-9._-]/.test(tail)) break
+      const server = byAlias.get(alias)
+      if (server && !seen.has(server.id ?? server.name)) {
+        seen.add(server.id ?? server.name)
+        matched.push(server)
+      }
+      break
+    }
+  }
+  return matched
+}
+
+function sameList(left, right) {
+  if (left.length !== right.length) return false
+  return left.every((value, index) => value === right[index])
+}
+
+function freshState() {
+  return { candidates: [], active: null, version: 0, injectedVersion: -1, notifiedVersion: -1, seeded: false }
+}
+
+/**
+ * Fold the mention rules over one session state.
+ *
+ * - one mention       → that server becomes the active target;
+ * - several mentions  → candidates are remembered, active target is cleared;
+ * - no mention        → state is unchanged (a follow-up keeps its target).
+ */
+export function applyMentions(state, mentions) {
+  if (!Array.isArray(mentions) || mentions.length === 0) return state
+  const names = mentions.map((server) => server.name)
+  if (mentions.length === 1) {
+    if (state.active === names[0] && sameList(state.candidates, names)) return state
+    return { ...state, candidates: names, active: names[0], version: state.version + 1 }
+  }
+  // Several mentions never pick a target by guesswork; the model must call the
+  // selector tool. The previous active target is dropped for the same reason.
+  const active = null
+  if (active === state.active && sameList(state.candidates, names)) return state
+  return { ...state, candidates: names, active, version: state.version + 1 }
+}
+
+/** Replay the mention rules over a Session's historical messages. */
+export function replayTargets(messages, servers) {
+  let state = freshState()
+  if (Array.isArray(messages)) {
+    for (const message of messages) {
+      if (message?.role !== 'user' || message.source?.kind !== 'user') continue
+      state = applyMentions(state, extractServerMentions(extractUserText(message), servers))
+    }
+  }
+  return state
+}
+
+/** Resolve one target reference against the inventory (name or id). */
+export function findTarget(servers, ref) {
+  const value = String(ref ?? '').trim()
+  if (!value) return undefined
+  return servers.find((server) => server.id === value || server.name === value)
+}
+
+/**
+ * Create the per-session target store.
+ * @param {{ loadInventory?: () => object[] }} [options]
+ */
+export function createTargetStore(options = {}) {
+  const loadInventory = options.loadInventory ?? loadServers
+  /** @type {Map<string, object>} */
+  const sessions = new Map()
+
+  function sessionKey(session) {
+    if (session === undefined || session === null) return undefined
+    if (typeof session === 'string') return session
+    const id = session.id
+    return typeof id === 'string' && id.length > 0 ? id : undefined
+  }
+
+  function get(key) {
+    const sessionId = sessionKey(key)
+    if (sessionId === undefined) return undefined
+    return sessions.get(sessionId)
+  }
+
+  function ensure(key) {
+    const sessionId = sessionKey(key)
+    if (sessionId === undefined) return undefined
+    let state = sessions.get(sessionId)
+    if (state === undefined) {
+      state = freshState()
+      sessions.set(sessionId, state)
+    }
+    return state
+  }
+
+  /** Seed one session once from its historical messages (resume support). */
+  function ensureSeeded(key, messages, servers = loadInventory()) {
+    const state = ensure(key)
+    if (state === undefined || state.seeded) return state
+    const replayed = replayTargets(messages, servers)
+    const next = {
+      ...state,
+      candidates: replayed.candidates,
+      active: replayed.active,
+      version: replayed.version,
+      seeded: true,
+    }
+    sessions.set(sessionKey(key), next)
+    return next
+  }
+
+  function bindMentions(key, mentions) {
+    const state = ensure(key)
+    if (state === undefined) return undefined
+    const next = { ...applyMentions(state, mentions), seeded: true }
+    if (next !== state) sessions.set(sessionKey(key), next)
+    return next
+  }
+
+  /** Switch the active target explicitly. `local` detaches. */
+  function setActive(key, ref, servers = loadInventory()) {
+    const state = ensure(key)
+    if (state === undefined) return { ok: false, error: 'session is not addressable' }
+    if (String(ref).trim().toLowerCase() === LOCAL_TARGET) {
+      // Detaching also clears any pending @a @b ambiguity, so bash is plainly
+      // local again instead of staying blocked on "choose a target".
+      const next = { ...state, active: null, candidates: [], version: state.version + 1, seeded: true }
+      sessions.set(sessionKey(key), next)
+      return { ok: true, state: next }
+    }
+    const server = findTarget(servers, ref)
+    if (server === undefined) {
+      return { ok: false, error: `unknown server "${String(ref)}"`, state }
+    }
+    if (server.enabled === false) {
+      return { ok: false, error: `server "${server.name}" is disabled`, state }
+    }
+    const next = {
+      ...state,
+      active: server.name,
+      candidates: state.candidates.includes(server.name) ? state.candidates : [server.name],
+      version: state.version + 1,
+      seeded: true,
+    }
+    sessions.set(sessionKey(key), next)
+    return { ok: true, state: next, server }
+  }
+
+  function markInjected(key, version) {
+    const state = get(key)
+    if (state === undefined) return
+    if (state.injectedVersion === version) return
+    sessions.set(sessionKey(key), { ...state, injectedVersion: version })
+  }
+
+  /**
+   * Remember that the bash router already showed the target to the model/UI
+   * (one stderr line after each target change), so it is not repeated per call.
+   */
+  function markNotified(key, version) {
+    const state = get(key)
+    if (state === undefined) return
+    if (state.notifiedVersion === version) return
+    sessions.set(sessionKey(key), { ...state, notifiedVersion: version })
+  }
+
+  function clear(key) {
+    const sessionId = sessionKey(key)
+    if (sessionId !== undefined) sessions.delete(sessionId)
+  }
+
+  function clearAll() {
+    sessions.clear()
+  }
+
+  function size() {
+    return sessions.size
+  }
+
+  return { get, ensure, ensureSeeded, bindMentions, setActive, markInjected, markNotified, clear, clearAll, size, loadInventory }
+}

package/lib/core/terminals.js

@@ -0,0 +1,299 @@
+/**
+ * Interactive terminal sessions for the workbench.
+ *
+ * Remote sessions run on the existing ssh2 broker shell channel; local ones use
+ * the Host subprocess service's PTY (`spawnTerminal`). The browser renders them
+ * with xterm and polls `read`, so the transport needs no new socket protocol
+ * and stays on the plugin's authenticated routes.
+ *
+ * Sessions are process-local, buffered (bounded) and reclaimed after a period
+ * of inactivity or when their server/plugin goes away. Closing a session ends
+ * the remote channel or the local PTY; nothing survives a Host restart.
+ */
+import { randomUUID } from 'node:crypto'
+import { StringDecoder } from 'node:string_decoder'
+
+const MAX_BUFFER_CHARS = 512 * 1024
+const MAX_SESSIONS = 12
+const MAX_WAIT_MS = 20000
+const DEFAULT_IDLE_MS = 30 * 60 * 1000
+
+function clampDimension(value, fallback, max) {
+  const number = Number(value)
+  if (!Number.isFinite(number) || number < 1) return fallback
+  return Math.min(Math.max(Math.floor(number), 1), max)
+}
+
+function describe(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export function createTerminalHub({ runtime, getSubprocess, getLocalCwd, log = () => {} } = {}) {
+  /** @type {Map<string, object>} */
+  const sessions = new Map()
+  // Slots reserved by opens that are still waiting for their transport. The
+  // cap must be checked atomically: `open()` awaits the transport, so counting
+  // only inserted sessions lets concurrent calls all pass the same check.
+  let pendingOpens = 0
+  let disposed = false
+
+  function notify(session) {
+    for (const wake of [...session.waiters]) {
+      session.waiters.delete(wake)
+      try { wake() } catch { /* a waiter must never break the session */ }
+    }
+  }
+
+  function append(session, text) {
+    if (!text) return
+    session.text += text
+    if (session.text.length > MAX_BUFFER_CHARS) {
+      let drop = session.text.length - MAX_BUFFER_CHARS
+      // Never cut a UTF-16 surrogate pair in half: a slice starting on the low
+      // half would leave an orphan surrogate that the client renders as U+FFFD.
+      const first = session.text.charCodeAt(drop)
+      if (first >= 0xdc00 && first <= 0xdfff) drop += 1
+      session.text = session.text.slice(drop)
+      session.base += drop
+    }
+    notify(session)
+  }
+
+  function finish(session, exitCode, signal) {
+    if (session.exited) return
+    append(session, session.decoder.end())
+    session.exited = true
+    session.exitCode = Number.isInteger(exitCode) ? exitCode : null
+    session.signal = typeof signal === 'string' ? signal : null
+    notify(session)
+  }
+
+  function snapshot(session, cursor) {
+    let offset = Number.isInteger(cursor) && cursor >= 0 ? cursor : 0
+    let reset = false
+    if (offset < session.base) {
+      reset = true
+      offset = session.base
+    }
+    return {
+      session: session.id,
+      cursor: session.base + session.text.length,
+      data: session.text.slice(offset - session.base),
+      reset,
+      exited: session.exited,
+      exitCode: session.exitCode,
+      signal: session.signal,
+      title: session.title,
+      kind: session.kind,
+    }
+  }
+
+  function publicSession(session) {
+    return {
+      session: session.id,
+      kind: session.kind,
+      title: session.title,
+      server: session.server?.name ?? null,
+      cols: session.cols,
+      rows: session.rows,
+      cwd: session.cwd,
+    }
+  }
+
+  function closeSession(session, reason) {
+    if (!session || session.closed) return
+    session.closed = true
+    sessions.delete(session.id)
+    // Mark the session exited *before* waking readers so a suspended
+    // `/terminal/read` long-poll returns `exited:true` immediately instead of
+    // holding the request until its wait timeout (or reporting the stale
+    // "not found" of a removed session).
+    session.exited = true
+    session.exitCode = null
+    session.signal = null
+    notify(session)
+    session.waiters.clear()
+    const handle = session.handle
+    session.handle = null
+    if (handle) {
+      try {
+        if (typeof handle.close === 'function') handle.close()
+        else if (typeof handle.terminate === 'function') handle.terminate()
+      } catch (error) {
+        log(`terminal close failed (${reason ?? 'close'})`, { error: describe(error) })
+      }
+    }
+  }
+
+  async function open({ kind, server, cols, rows, cwd } = {}) {
+    if (disposed) throw new Error('terminal hub is disposed')
+    // Reserve the slot synchronously, before the first await, so two concurrent
+    // opens cannot both pass the cap check and overshoot MAX_SESSIONS.
+    if (sessions.size + pendingOpens >= MAX_SESSIONS) {
+      throw new Error(`too many terminals (${MAX_SESSIONS}); close one first`)
+    }
+    pendingOpens += 1
+    const session = {
+      id: `term_${randomUUID()}`,
+      kind: kind === 'remote' ? 'remote' : 'local',
+      title: kind === 'remote' ? (server?.name ?? 'remote') : 'local',
+      server: server ?? null,
+      cwd: typeof cwd === 'string' ? cwd : undefined,
+      cols: clampDimension(cols, 80, 500),
+      rows: clampDimension(rows, 24, 300),
+      text: '',
+      base: 0,
+      waiters: new Set(),
+      exited: false,
+      exitCode: null,
+      signal: null,
+      closed: false,
+      decoder: new StringDecoder('utf8'),
+      handle: null,
+      lastUsed: Date.now(),
+    }
+    try {
+      if (session.kind === 'remote') {
+        if (!server) throw new Error('remote terminal needs a managed resource')
+        const handle = await runtime.shell(server, { cols: session.cols, rows: session.rows })
+        session.handle = handle
+        session.title = server.name
+        handle.onData((data) => {
+          const buffer = Buffer.isBuffer(data) ? data : Buffer.from(String(data))
+          append(session, session.decoder.write(buffer))
+        })
+        handle.onClose(() => finish(session, null, null))
+        handle.onError((error) => {
+          append(session, `\r\n[remote shell error: ${describe(error)}]\r\n`)
+          finish(session, null, null)
+        })
+      } else {
+        const subprocess = getSubprocess?.()
+        if (!subprocess || typeof subprocess.spawnTerminal !== 'function') {
+          throw new Error('local terminals are unavailable on this host')
+        }
+        const environment = await subprocess.terminalEnvironment?.()
+        // The Host PTY provider names its platform (`windows` on win32) and the
+        // preferred shell (ComSpec on Windows, $SHELL/login shell on POSIX).
+        // `-i` is a POSIX login-shell flag: cmd.exe/pwsh reject it, so only
+        // POSIX shells get it.
+        const localPlatform = environment?.platform === 'windows' || (environment?.platform === undefined && process.platform === 'win32')
+          ? 'windows'
+          : 'posix'
+        const shell = environment?.defaultShell || (localPlatform === 'windows' ? (process.env.ComSpec || 'cmd.exe') : '/bin/sh')
+        const argv = localPlatform === 'windows' ? [shell] : [shell, '-i']
+        const handle = await subprocess.spawnTerminal({
+          argv,
+          cwd: typeof cwd === 'string' && cwd ? cwd : getLocalCwd?.(),
+          cols: session.cols,
+          rows: session.rows,
+          terminalType: 'xterm-256color',
+          graceMs: 1000,
+        })
+        session.handle = {
+          write: (data) => handle.write(data),
+          resize: (nextCols, nextRows) => handle.resize(nextCols, nextRows),
+          close: () => handle.terminate(),
+        }
+        handle.output.on('data', (data) => {
+          const buffer = Buffer.isBuffer(data) ? data : Buffer.from(String(data))
+          append(session, session.decoder.write(buffer))
+        })
+        handle.done.then(
+          (outcome) => finish(session, outcome?.exitCode, outcome?.signal),
+          (error) => {
+            append(session, `\r\n[local terminal error: ${describe(error)}]\r\n`)
+            finish(session, null, null)
+          },
+        )
+      }
+      // The hub may have been disposed while the transport was connecting: do
+      // not leak a session (or a PTY) into a torn-down hub.
+      if (disposed) throw new Error('terminal hub is disposed')
+    } catch (error) {
+      closeSession(session, 'open failed')
+      throw error
+    } finally {
+      pendingOpens -= 1
+    }
+    sessions.set(session.id, session)
+    session.lastUsed = Date.now()
+    return publicSession(session)
+  }
+
+  function input(id, data) {
+    const session = sessions.get(id)
+    if (!session || session.exited || !session.handle) return false
+    session.lastUsed = Date.now()
+    session.handle.write(String(data ?? ''))
+    return true
+  }
+
+  function resize(id, cols, rows) {
+    const session = sessions.get(id)
+    if (!session || session.exited || !session.handle) return false
+    session.lastUsed = Date.now()
+    session.cols = clampDimension(cols, session.cols, 500)
+    session.rows = clampDimension(rows, session.rows, 300)
+    try {
+      session.handle.resize(session.cols, session.rows)
+    } catch (error) {
+      log('terminal resize failed', { error: describe(error) })
+    }
+    return true
+  }
+
+  async function read(id, { cursor = 0, waitMs = 0 } = {}) {
+    const session = sessions.get(id)
+    if (!session) throw new Error('terminal session not found')
+    session.lastUsed = Date.now()
+    const initial = snapshot(session, cursor)
+    const wait = Math.min(Math.max(Number(waitMs) || 0, 0), MAX_WAIT_MS)
+    if (initial.data || initial.exited || wait === 0) return initial
+    await new Promise((resolve) => {
+      const wake = () => {
+        clearTimeout(timer)
+        session.waiters.delete(wake)
+        resolve()
+      }
+      const timer = setTimeout(wake, wait)
+      timer.unref?.()
+      session.waiters.add(wake)
+    })
+    return snapshot(session, cursor)
+  }
+
+  function close(id) {
+    const session = sessions.get(id)
+    if (!session) return false
+    closeSession(session, 'requested')
+    return true
+  }
+
+  function closeForServer(serverId) {
+    let closed = 0
+    for (const session of [...sessions.values()]) {
+      if (session.server?.id !== serverId) continue
+      closeSession(session, 'server changed')
+      closed += 1
+    }
+    return closed
+  }
+
+  function dispose() {
+    disposed = true
+    for (const session of [...sessions.values()]) closeSession(session, 'plugin unloaded')
+    if (cleanup) clearInterval(cleanup)
+  }
+
+  const cleanup = setInterval(() => {
+    const cutoff = Date.now() - DEFAULT_IDLE_MS
+    for (const session of [...sessions.values()]) {
+      if (session.waiters.size > 0) continue
+      if (session.lastUsed < cutoff) closeSession(session, 'idle')
+    }
+  }, 60 * 1000)
+  cleanup.unref?.()
+
+  return { open, read, input, resize, close, closeForServer, dispose, count: () => sessions.size }
+}