@hunan36/dsh-ssh-helper 0.0.0-stage → 0.1.0

package/host/gate.js

@@ -0,0 +1,264 @@
+/**
+ * Harness-native approval gate for remote updates.
+ *
+ * The gate is registered on `tools/pre-execute`. It is the only place that
+ * turns a valid `ssh_helper_update_apply` plan (or a resolvable
+ * `ssh_helper_update_rollback` backup) into `{ kind: 'ask' }`; every other tool
+ * and every invalid or expired request falls through with `next()` so the tool
+ * body can return its own guidance error. There is deliberately no `confirm`,
+ * `force` or `skip_approval` parameter.
+ *
+ * @module host/gate
+ */
+
+import { remotePathWarnings, shQuote } from './shell.js'
+
+/** Tool name for the approved update. */
+const APPLY_TOOL = 'ssh_helper_update_apply'
+/** Tool name for the approved rollback. */
+const ROLLBACK_TOOL = 'ssh_helper_update_rollback'
+/** Tool name for the approved upload. */
+const UPLOAD_TOOL = 'ssh_helper_upload'
+/** Maximum command length shown in an approval reason. */
+const REASON_COMMAND_LIMIT = 300
+
+/**
+ * Truncate one command for the approval prompt.
+ * @param {unknown} value - raw command.
+ * @returns {string} truncated text.
+ */
+function cut(value) {
+  if (typeof value !== 'string') return ''
+  return value.length <= REASON_COMMAND_LIMIT ? value : `${value.slice(0, REASON_COMMAND_LIMIT)}…`
+}
+
+/**
+ * Make one text value safe for a single-line approval reason.
+ *
+ * The approval prompt is a security boundary: every interpolated value must be
+ * flattened onto one line, otherwise a resource name or path carrying `\n`
+ * could forge prompt chrome such as a second `Backup: disabled.` line. Control
+ * characters and bidirectional overrides are dropped as well, so a path cannot
+ * render reversed in the prompt the operator reads.
+ *
+ * @param {unknown} value - raw text.
+ * @returns {string} one-line text.
+ */
+function line(value) {
+  if (typeof value !== 'string') return ''
+  return value
+    .replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/[\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/** Delimiter that fences a verbatim multi-line command inside a prompt. */
+const FENCE = '----- command (verbatim) -----'
+
+/**
+ * Render a command block the operator can read as data, never as prompt chrome.
+ *
+ * Multi-line shell scripts are legitimate, so they are not rejected; instead
+ * they are fenced so a reader cannot mistake a line of the script for one of
+ * the prompt's own labels. The block is truncated to keep the prompt short.
+ *
+ * @param {unknown} value - raw command.
+ * @returns {string[]} three lines: opening fence, body, closing fence.
+ */
+function fence(value) {
+  const text = typeof value === 'string' ? value.replace(/[\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g, '') : ''
+  return [FENCE, cut(text), FENCE]
+}
+
+/**
+ * Build the approval decision for one valid apply plan.
+ * @param {object} plan - cached plan.
+ * @returns {{ kind: 'ask', reason: string, displayReason: { en: string, zh: string } }} decision.
+ */
+function askForApply(plan) {
+  const backup = line(plan.backup && plan.backup.enabled ? plan.backup.file : 'disabled')
+  const name = line(plan.resourceName)
+  const server = line(plan.serverName)
+  const dir = line(plan.appDir)
+  const warnings = Array.isArray(plan.warnings) ? plan.warnings.map(line).filter(Boolean) : []
+  const restart = line(plan.restartCommand)
+  const verify = line(plan.verifyCommand)
+
+  const english = [
+    `Approve remote update plan ${line(plan.id)} for "${name}" on ${server} (${dir}).`,
+    `Backup: ${backup}.`,
+    ...fence(plan.updateCommand),
+  ]
+  if (restart !== '') english.push(`Restart command: ${cut(restart)}`)
+  if (verify !== '') english.push(`Verify command: ${cut(verify)}`)
+  if (warnings.length > 0) english.push(`Warnings: ${warnings.join('; ')}`)
+
+  const chinese = [
+    `批准更新 "${name}"：服务器 ${server}，目录 ${dir}。`,
+    `备份：${backup}。`,
+    ...fence(plan.updateCommand),
+  ]
+  if (restart !== '') chinese.push(`重启命令：${cut(restart)}`)
+  if (verify !== '') chinese.push(`校验命令：${cut(verify)}`)
+  if (warnings.length > 0) chinese.push(`警告：${warnings.join('；')}`)
+
+  return {
+    kind: 'ask',
+    reason: english.join('\n'),
+    displayReason: { en: english.join('\n'), zh: chinese.join('\n') },
+  }
+}
+
+/**
+ * Build the approval decision for one valid rollback target.
+ * @param {object} target - rollback target from `update.resolveRollbackTarget`.
+ * @returns {{ kind: 'ask', reason: string, displayReason: { en: string, zh: string } }} decision.
+ */
+function askForRollback(target) {
+  const resource = target.resource
+  const name = line(resource.name)
+  const server = line(resource.serverName || '')
+  const dir = line(resource.appDir)
+  const backupPath = line(target.backupPath)
+  const parent = line(target.parent)
+  const warnings = Array.isArray(remotePathWarnings(resource.appDir)) ? remotePathWarnings(resource.appDir).map(line).filter(Boolean) : []
+  const restart = line(resource.restartCommand)
+  const verify = line(resource.verifyCommand)
+  const restoreCommand = `tar -C ${shQuote(parent)} -xzf ${shQuote(backupPath)}`
+  const english = [
+    `Approve rollback of "${name}" on ${server} (${dir}).`,
+    `Restore backup: ${backupPath}.`,
+    `The current directory is moved aside before extraction.`,
+    `Restore command: ${cut(restoreCommand)}`,
+  ]
+  if (restart !== '') english.push(`Restart command: ${cut(restart)}`)
+  if (verify !== '') english.push(`Verify command: ${cut(verify)}`)
+  if (warnings.length > 0) english.push(`Warnings: ${warnings.join('; ')}`)
+
+  const chinese = [
+    `批准回滚 "${name}"：服务器 ${server}，目录 ${dir}。`,
+    `恢复备份：${backupPath}。`,
+    `解压前会先把当前目录移动到一旁。`,
+    `恢复命令：${cut(restoreCommand)}`,
+  ]
+  if (restart !== '') chinese.push(`重启命令：${cut(restart)}`)
+  if (verify !== '') chinese.push(`校验命令：${cut(verify)}`)
+  if (warnings.length > 0) chinese.push(`警告：${warnings.join('；')}`)
+
+  return {
+    kind: 'ask',
+    reason: english.join('\n'),
+    displayReason: { en: english.join('\n'), zh: chinese.join('\n') },
+  }
+}
+
+/**
+ * Format one byte count for a prompt line.
+ * @param {unknown} value - raw bytes.
+ * @returns {string} human readable size.
+ */
+function size(value) {
+  const bytes = typeof value === 'number' && Number.isFinite(value) ? value : 0
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KiB`
+  return `${bytes} B`
+}
+
+/**
+ * Build the approval decision for one valid upload target.
+ * @param {object} target - value from `upload.resolve`.
+ * @returns {{ kind: 'ask', reason: string, displayReason: { en: string, zh: string } }} decision.
+ */
+function askForUpload(target) {
+  const warnings = Array.isArray(target.warnings) ? target.warnings.map(line).filter(Boolean) : []
+  const fileName = line(target.fileName)
+  const serverName = line(target.serverName)
+  const remotePath = line(target.remotePath)
+  const localPath = line(target.localPath)
+  const resourceName = line(target.resourceName)
+  const english = [
+    `Approve upload of "${fileName}" (${size(target.sizeBytes)}) to ${serverName} at ${remotePath}.`,
+    `Local file: ${localPath}.`,
+    `The file is transferred over SFTP, then its size and SHA-256 are verified on the server.`,
+  ]
+  if (resourceName !== '') english.push(`Deployment resource: ${resourceName}.`)
+  if (warnings.length > 0) english.push(`Warnings: ${warnings.join('; ')}`)
+
+  const chinese = [
+    `批准上传 "${fileName}"（${size(target.sizeBytes)}）到 ${serverName} 的 ${remotePath}。`,
+    `本地文件：${localPath}。`,
+    `文件通过 SFTP 传输，随后在服务器上校验大小与 SHA-256。`,
+  ]
+  if (resourceName !== '') chinese.push(`部署资源：${resourceName}。`)
+  if (warnings.length > 0) chinese.push(`警告：${warnings.join('；')}`)
+
+  return {
+    kind: 'ask',
+    reason: english.join('\n'),
+    displayReason: { en: english.join('\n'), zh: chinese.join('\n') },
+  }
+}
+
+/**
+ * Create the `tools/pre-execute` handler.
+ * @param {{ update: object, upload?: object, resources: object }} services - services (`update` must expose `peekPlan` and `resolveRollbackTarget`; `upload` must expose `resolve`).
+ * @returns {(exec: object, next: Function) => Promise<object>} waterfall handler.
+ */
+export function createUpdateGate({ update, upload, resources } = {}) {
+  if (!update || typeof update !== 'object') throw new TypeError('createUpdateGate: update service is required')
+  void resources
+
+  return async function updateGate(exec, next) {
+    try {
+      const name =
+        exec && typeof exec.name === 'string'
+          ? exec.name
+          : exec && typeof exec.toolName === 'string'
+            ? exec.toolName
+            : exec && exec.tool && typeof exec.tool.name === 'string'
+              ? exec.tool.name
+              : ''
+      if (name !== APPLY_TOOL && name !== ROLLBACK_TOOL && name !== UPLOAD_TOOL) return next()
+
+      const args =
+        exec && typeof exec.arguments === 'object' && exec.arguments !== null && !Array.isArray(exec.arguments)
+          ? exec.arguments
+          : {}
+      const agentId = exec && exec.agent && typeof exec.agent.id === 'string' ? exec.agent.id : undefined
+
+      if (name === APPLY_TOOL) {
+        const planId = typeof args.plan_id === 'string' ? args.plan_id.trim() : ''
+        if (planId === '' || typeof update.peekPlan !== 'function') return next()
+        const plan = update.peekPlan(planId, agentId)
+        if (!plan || !Array.isArray(plan.blockers) || plan.blockers.length > 0) return next()
+        return askForApply(plan)
+      }
+
+      if (name === UPLOAD_TOOL) {
+        if (!upload || typeof upload.resolve !== 'function') return next()
+        let target
+        try {
+          target = upload.resolve(args)
+        } catch {
+          // An invalid request is rejected by the tool body with guidance; it is
+          // never turned into an approval prompt.
+          return next()
+        }
+        return askForUpload(target)
+      }
+
+      if (typeof update.resolveRollbackTarget !== 'function') return next()
+      const resource = typeof args.resource === 'string' ? args.resource.trim() : ''
+      if (resource === '') return next()
+      const historyId = typeof args.history_id === 'string' ? args.history_id.trim() : undefined
+      const target = update.resolveRollbackTarget(resource, historyId)
+      if (!target) return next()
+      if (typeof update.pinRollback !== 'function') return next()
+      update.pinRollback(target, agentId)
+      return askForRollback(target)
+    } catch {
+      return next()
+    }
+  }
+}

package/host/history.js

@@ -0,0 +1,276 @@
+/**
+ * Persistent update history store.
+ *
+ * Every apply/rollback attempt is stored newest first in `history.json`, capped
+ * at 200 entries. Step output tails are clipped to 8192 characters so history
+ * stays bounded and credential shapes are masked before they are persisted, so
+ * neither `history.json` nor the browser ever shows a leaked secret. The command
+ * text is kept verbatim because it is the audit record. The file is written
+ * atomically with mode `0600`.
+ *
+ * @module host/history
+ */
+
+import { randomUUID } from 'node:crypto'
+import path from 'node:path'
+import { createJsonFile } from './atomic.js'
+
+/** File name inside the plugin data directory. */
+const DATA_FILE = 'history.json'
+/** Maximum retained history entries. */
+const MAX_ENTRIES = 200
+/** Maximum characters kept per captured output tail. */
+const TAIL_MAX_LENGTH = 8192
+/** Default list limit (all retained entries). */
+const DEFAULT_LIST_LIMIT = MAX_ENTRIES
+/** Accepted actions. */
+const ACTIONS = new Set(['apply', 'rollback', 'upload'])
+/** Accepted statuses. */
+const STATUSES = new Set(['success', 'partial', 'failed', 'blocked'])
+
+/**
+ * Build one tagged error.
+ * @param {string} code - machine-readable code.
+ * @param {string} message - Chinese message.
+ * @param {unknown} [cause] - underlying failure.
+ * @returns {Error & { code: string }} tagged error.
+ */
+function taggedError(code, message, cause) {
+  const error = new Error(message)
+  error.code = code
+  if (cause !== undefined) error.cause = cause
+  return error
+}
+
+/** @returns {Error} invalid-input error. */
+function invalid(message) {
+  return taggedError('invalid-input', message)
+}
+
+/** @returns {Error} storage error. */
+function storageError(cause) {
+  return taggedError('storage', '无法保存更新历史', cause)
+}
+
+/** @param {unknown} value @returns {boolean} whether the value is a plain object. */
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Mask credential shapes in one captured output tail.
+ *
+ * Captured stdout/stderr routinely contains secrets: `bash -x`/`set -x` echoes
+ * the command after expansion and failing CLIs echo their argv, so a token that
+ * only ever existed on the remote host can land in `history.json` and in the
+ * browser. The command text itself stays verbatim (it is the audit record) —
+ * only the captured output is scrubbed here.
+ *
+ * @param {string} text - captured output.
+ * @returns {string} scrubbed output.
+ */
+function redactSecrets(text) {
+  return text
+    .replace(/\b(password|passwd|passphrase|token|secret|api[_-]?key)\b(\s*[=:]\s*)\S+/gi, (_match, name, separator) => `${name}${separator}<redacted>`)
+    .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '<redacted-private-key>')
+}
+
+/**
+ * Clip one captured output tail to the contract maximum (the tail, not the
+ * head), then scrub credential shapes from it.
+ * @param {unknown} value - raw output.
+ * @returns {string} clipped and scrubbed text.
+ */
+function clipTail(value) {
+  if (typeof value !== 'string') return ''
+  const clipped = value.length <= TAIL_MAX_LENGTH ? value : value.slice(value.length - TAIL_MAX_LENGTH)
+  return redactSecrets(clipped)
+}
+
+/**
+ * Normalize one history step.
+ * @param {unknown} step - raw step.
+ * @param {number} index - step index for defaults.
+ * @returns {object} sanitized step.
+ */
+function readStep(step, index) {
+  if (!isObject(step)) throw invalid('更新步骤格式无效')
+  const id = typeof step.id === 'string' && step.id !== '' ? step.id : `step-${index + 1}`
+  const title = typeof step.title === 'string' && step.title !== '' ? step.title : id
+  const status = typeof step.status === 'string' && step.status !== '' ? step.status : 'failed'
+  const record = {
+    id,
+    title,
+    status,
+    exitCode: Number.isInteger(step.exitCode) ? step.exitCode : null,
+    durationMs: typeof step.durationMs === 'number' && Number.isFinite(step.durationMs) ? Math.max(0, step.durationMs) : 0,
+    stdoutTail: clipTail(step.stdoutTail),
+    stderrTail: clipTail(step.stderrTail),
+    truncated: step.truncated === true,
+  }
+  if (typeof step.command === 'string' && step.command !== '') record.command = step.command
+  return record
+}
+
+/**
+ * Normalize one history entry.
+ * @param {unknown} entry - raw entry.
+ * @returns {object} sanitized entry.
+ */
+function readEntry(entry) {
+  if (!isObject(entry)) throw invalid('更新历史格式无效')
+  const action = typeof entry.action === 'string' ? entry.action : ''
+  if (!ACTIONS.has(action)) throw invalid('更新历史动作无效')
+  const status = typeof entry.status === 'string' ? entry.status : ''
+  if (!STATUSES.has(status)) throw invalid('更新历史状态无效')
+  const steps = Array.isArray(entry.steps) ? entry.steps.map((step, index) => readStep(step, index)) : []
+  const record = {
+    id: typeof entry.id === 'string' && entry.id !== '' ? entry.id : randomUUID(),
+    action,
+    resourceId: typeof entry.resourceId === 'string' ? entry.resourceId : '',
+    resourceName: typeof entry.resourceName === 'string' ? entry.resourceName : '',
+    serverId: typeof entry.serverId === 'string' ? entry.serverId : '',
+    serverName: typeof entry.serverName === 'string' ? entry.serverName : '',
+    appDir: typeof entry.appDir === 'string' ? entry.appDir : '',
+    backupPath: typeof entry.backupPath === 'string' ? entry.backupPath : '',
+    status,
+    startedAt: typeof entry.startedAt === 'string' ? entry.startedAt : '',
+    finishedAt: typeof entry.finishedAt === 'string' ? entry.finishedAt : '',
+    durationMs: typeof entry.durationMs === 'number' && Number.isFinite(entry.durationMs) ? Math.max(0, entry.durationMs) : 0,
+    steps,
+  }
+  if (typeof entry.message === 'string' && entry.message !== '') record.message = entry.message
+  return record
+}
+
+/**
+ * Whether a parsed entry can be loaded.
+ * @param {unknown} entry - parsed entry.
+ * @returns {boolean} usability.
+ */
+function isUsable(entry) {
+  if (!isObject(entry)) return false
+  if (typeof entry.id !== 'string' || entry.id === '') return false
+  if (typeof entry.action !== 'string' || !ACTIONS.has(entry.action)) return false
+  if (typeof entry.status !== 'string' || !STATUSES.has(entry.status)) return false
+  if (!Array.isArray(entry.steps)) return false
+  return true
+}
+
+/**
+ * Deep-copy one entry so callers cannot mutate stored state.
+ * @param {object} entry - stored entry.
+ * @returns {object} copy.
+ */
+function copyEntry(entry) {
+  return JSON.parse(JSON.stringify(entry))
+}
+
+/**
+ * Create the history store.
+ * @param {{ dir: string }} options - plugin data directory.
+ * @returns {{
+ *   load: () => void,
+ *   append: (entry: object) => Promise<object>,
+ *   list: (options?: { resourceId?: string, limit?: number }) => object[],
+ *   get: (id: string) => object | undefined,
+ * }} store API.
+ */
+export function createHistoryStore({ dir } = {}) {
+  if (typeof dir !== 'string' || dir.trim() === '') throw new TypeError('createHistoryStore: dir is required')
+  const resolvedDir = path.resolve(dir)
+  const file = createJsonFile({ dir: resolvedDir, filename: DATA_FILE })
+
+  /** @type {object[]} entries, newest first. */
+  let entries = []
+  let loaded = false
+  /** @type {Promise<unknown>} tail of the serialized mutation chain. */
+  let mutationTail = Promise.resolve()
+
+  /** Read the data file once; never throws. */
+  function load() {
+    if (loaded) return
+    loaded = true
+    const parsed = file.read()
+    if (!Array.isArray(parsed)) {
+      entries = []
+      return
+    }
+    entries = parsed.filter(isUsable).slice(0, MAX_ENTRIES).map((entry) => {
+      try {
+        return readEntry(entry)
+      } catch {
+        return undefined
+      }
+    }).filter((entry) => entry !== undefined)
+  }
+
+  /** Ensure the lazy read happened. */
+  function ensureLoaded() {
+    if (!loaded) load()
+  }
+
+  /**
+   * Serialize one mutation on top of earlier mutations.
+   * @template T
+   * @param {() => Promise<T>} task - mutation.
+   * @returns {Promise<T>} outcome.
+   */
+  function enqueue(task) {
+    const run = mutationTail.then(task, task)
+    mutationTail = run.then(
+      () => undefined,
+      () => undefined,
+    )
+    return run
+  }
+
+  /**
+   * Append one entry at the front and persist.
+   * @param {object} entry - history entry (id assigned when absent).
+   * @returns {Promise<object>} stored entry.
+   */
+  function append(entry) {
+    ensureLoaded()
+    return enqueue(async () => {
+      const record = readEntry(entry)
+      const previous = entries
+      entries = [record, ...entries].slice(0, MAX_ENTRIES)
+      try {
+        await file.write(entries)
+      } catch (error) {
+        entries = previous
+        throw storageError(error)
+      }
+      return copyEntry(record)
+    })
+  }
+
+  /**
+   * List entries newest first.
+   * @param {{ resourceId?: string, limit?: number }} [options] - filter and page size.
+   * @returns {object[]} entries.
+   */
+  function list({ resourceId, limit } = {}) {
+    ensureLoaded()
+    const max = typeof limit === 'number' && Number.isFinite(limit) ? Math.min(MAX_ENTRIES, Math.max(1, Math.round(limit))) : DEFAULT_LIST_LIMIT
+    const filtered =
+      typeof resourceId === 'string' && resourceId !== ''
+        ? entries.filter((entry) => entry.resourceId === resourceId)
+        : entries
+    return filtered.slice(0, max).map((entry) => copyEntry(entry))
+  }
+
+  /**
+   * @param {string} id - entry id.
+   * @returns {object | undefined} entry copy.
+   */
+  function get(id) {
+    ensureLoaded()
+    if (typeof id !== 'string' || id === '') return undefined
+    const entry = entries.find((candidate) => candidate.id === id)
+    return entry === undefined ? undefined : copyEntry(entry)
+  }
+
+  return { load, append, list, get }
+}

package/host/prompt.js

@@ -0,0 +1,103 @@
+/**
+ * System-prompt section for dsh-ssh-helper.
+ *
+ * The text is rebuilt on every prompt assembly from the live stores, so the
+ * model sees the accounts and deployment resources configured right now. It
+ * only reads public views, which never contain credentials.
+ *
+ * @module host/prompt
+ */
+
+/** Unique prompt section name. */
+const SECTION_NAME = 'ssh-helper:resources'
+/** Section order. */
+const SECTION_ORDER = 45
+
+/**
+ * Make one user-controlled value safe to embed in a single Markdown line.
+ * @param {unknown} value - raw value.
+ * @returns {string} one-line text.
+ */
+function singleLine(value) {
+  if (typeof value !== 'string') return ''
+  return value.replace(/[\r\n]+/g, ' ').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Build the section text.
+ * @param {{ accounts: object, resources: object }} services - stores.
+ * @returns {string} prompt text.
+ */
+function buildText({ accounts, resources }) {
+  /** @type {object[]} */
+  let accountViews = []
+  /** @type {object[]} */
+  let resourceViews = []
+  try {
+    accountViews = accounts.list()
+  } catch {
+    accountViews = []
+  }
+  try {
+    resourceViews = resources.list()
+  } catch {
+    resourceViews = []
+  }
+  if (!Array.isArray(accountViews)) accountViews = []
+  if (!Array.isArray(resourceViews)) resourceViews = []
+
+  const lines = ['## SSH Helper', '']
+
+  if (accountViews.length === 0) {
+    lines.push('No SSH accounts are configured. The user can add accounts in the SSH Helper panel in the left sidebar.')
+  } else {
+    lines.push('Configured SSH accounts (credentials are never shown):')
+    for (const account of accountViews) {
+      const name = singleLine(account.name)
+      const username = singleLine(account.username)
+      const host = singleLine(account.host)
+      const port = typeof account.port === 'number' ? account.port : 22
+      const auth = account.authType === 'key' ? 'private key' : 'password'
+      lines.push(`- ${name} — ${username}@${host}:${port} (${auth} auth)`)
+    }
+  }
+  lines.push('')
+
+  if (resourceViews.length === 0) {
+    lines.push('No deployment resources are catalogued. Discover one with `ssh_helper_discover` (scan/inspect) and save it with `ssh_helper_resources`.')
+  } else {
+    lines.push('Deployment resources:')
+    for (const resource of resourceViews) {
+      const name = singleLine(resource.name)
+      const serverName = singleLine(resource.serverName) || 'unknown server'
+      const appDir = singleLine(resource.appDir)
+      const status = singleLine(resource.lastUpdateStatus) || 'never'
+      lines.push(`- ${name} — ${serverName}:${appDir} (last update: ${status})`)
+    }
+  }
+
+  lines.push(
+    '',
+    'Workflow: use `ssh_helper_discover` to find deployment directories, then `ssh_helper_resources` to save them; use `ssh_helper_upload` to push a local build artifact (SFTP, size and SHA-256 verified) when the deployment needs one; use `ssh_helper_update_plan` to produce a read-only plan, then `ssh_helper_update_apply` to execute it; use `ssh_helper_update_rollback` to restore the last backup.',
+    '`ssh_helper_upload`, `ssh_helper_update_apply` and `ssh_helper_update_rollback` always ask the user for approval. Never try to bypass approval, never run managed directory changes through a generic `ssh_exec`, and never put passwords, private keys, passphrases or tokens in update commands.',
+  )
+  return lines.join('\n')
+}
+
+/**
+ * Register the `## SSH Helper` system-prompt section.
+ * @param {object} ctx - host plugin context (`systemPrompt` service).
+ * @param {{ accounts: object, resources: object }} services - stores.
+ * @returns {() => void} section disposer.
+ */
+export function registerPromptSection(ctx, { accounts, resources } = {}) {
+  if (!ctx || !ctx.systemPrompt || typeof ctx.systemPrompt.section !== 'function') {
+    throw new Error('dsh-ssh-helper: systemPrompt service is unavailable')
+  }
+  if (!accounts || !resources) throw new Error('dsh-ssh-helper: prompt services are unavailable')
+  return ctx.systemPrompt.section({
+    name: SECTION_NAME,
+    order: SECTION_ORDER,
+    text: () => buildText({ accounts, resources }),
+  })
+}