@linxin666/dsh-ssh 0.4.4 → 0.4.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-ssh",
   "description": "Remote SSH operations for the dsh web GUI: host config store (~/.dsh/dsh-ssh.json, import from ~/.ssh/config), a persistent ssh2 connection pool with jump-host support, exec / PTY web terminal / SFTP transfer / local port-forward tunnels / cluster execution, plus agent tools (ssh_list, ssh_exec, ssh_upload, ssh_download, ssh_tunnel, ssh_cluster). Hot-pluggable — mounted via ~/.dsh/cordis.patch.yml + a profile node_modules symlink, no dsh source changes.",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "icon": "icon.svg",
   "type": "module",
   "engines": {
@@ -14,10 +14,6 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
     "./client": {
       "types": "./lib/types/client/index.d.ts",
       "default": "./lib/client.js"
@@ -27,7 +23,7 @@
   },
   "dsh": {
     "engines": {
-      "dsh": ">=0.2.0-rc.1"
+      "dsh": ">=0.2.0-rc.2"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -50,26 +46,26 @@
     "ws": "^8.18.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh": ">=0.2.0-rc.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-layout": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-sidebar": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-scope": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-timeout": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.5",
@@ -99,7 +95,7 @@
     "url": "https://github.com/zhu1090093659/dsh-web.git"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && tsdown",
+    "build": "tsc -b tsconfig.build.json && tsdown",
     "bundle": "tsdown",
     "watch": "tsdown --watch",
     "typecheck": "tsc --noEmit",

package/src/client/api.ts

@@ -88,27 +88,84 @@ interface PageLocation {
  * The WebSocket URL the terminal route is reached at, or undefined when this
  * page cannot carry one.
  *
- * A page delivered by an application on this machine (the official DSH
- * Desktop shell serves its Web GUI from `dsh-app://app/`) has no WebSocket
- * transport: its scheme handler forwards HTTP requests to the local host but
- * cannot upgrade a socket, so `ws://app/...` never connects and the terminal
- * reports "connection error" (issue #1744). Every other page is a web page and
- * resolves the socket against its own origin, exactly as before.
+ * A web page resolves the socket against its own origin, exactly as before.
  *
- * A blank authority is treated the same as an application scheme: there is
- * nothing to dial, and the caller gets the actionable reason instead of a
- * socket that can only fail.
+ * A page delivered by an application on this machine (the official DSH Desktop
+ * shell serves its Web GUI from `dsh-app://app/`) cannot carry a socket on its
+ * own scheme: the protocol handler forwards HTTP to the local Host but has no
+ * upgrade to forward. That is exactly the case the official transport hook
+ * covers - the shell publishes `__DSH_TRANSPORT__.streamBaseUrl`, the loopback
+ * authority of the Host it owns and already forwards every other request to
+ * (issue #1744). The socket is therefore dialed there instead, with the `ws`/
+ * `wss` scheme derived from that base, which is what the shell's
+ * `onBeforeSendHeaders` hook expects to see before it attaches its
+ * authority-bound credential.
+ *
+ * The base is used only on an application-delivered page. A web page that
+ * somehow carries the hook (the remote channel grants `ownsHost` to a paired
+ * LAN page, and that page is fenced behind a pairing channel) keeps resolving
+ * against its own origin, so this cannot reroute gated traffic onto a host the
+ * page is not entitled to reach. A blank authority is treated the same as an
+ * application scheme with no base: there is nothing to dial, and the caller
+ * gets the actionable reason instead of a socket that can only fail.
  *
  * @param location - the page location to read.
  * @param search - the query string carrying `alias` or `session`.
+ * @param streamBaseUrl - `__DSH_TRANSPORT__.streamBaseUrl`, when the shell published one.
  * @returns the absolute `ws:`/`wss:` URL, or undefined when the page cannot carry one.
  */
-export function terminalSocketUrl(location: PageLocation, search: string): string | undefined {
+export function terminalSocketUrl(
+  location: PageLocation,
+  search: string,
+  streamBaseUrl?: string | undefined,
+): string | undefined {
   if (WEB_PAGE_PROTOCOLS.includes(location.protocol)) {
     const scheme = location.protocol === 'https:' ? 'wss' : 'ws'
     return scheme + '://' + location.host + SSH_API.terminal + search
   }
-  return undefined
+  // Application-delivered page: the shell-owned Host authority is the only
+  // origin the socket can reach. An unparsable or non-network base is ignored
+  // rather than guessed at, so the caller reports the actionable reason.
+  const base = hostAuthorityOf(streamBaseUrl)
+  if (base === undefined) return undefined
+  const scheme = base.protocol === 'https:' ? 'wss' : 'ws'
+  return scheme + '://' + base.authority + SSH_API.terminal + search
+}
+
+/**
+ * The authority and scheme of a shell-owned Host base, or undefined when the
+ * value is absent, unparsable, or not a network origin this Host can serve
+ * (an application scheme could only resolve back to the page that has no
+ * socket transport in the first place).
+ * @param base - the raw `streamBaseUrl` as published by the transport hook.
+ */
+function hostAuthorityOf(base: string | undefined): { protocol: string; authority: string } | undefined {
+  if (base === undefined || base === '') return undefined
+  let url: URL
+  try {
+    url = new URL(base)
+  } catch {
+    return undefined
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return undefined
+  // A base carrying userinfo or credentials would put them on the wire.
+  if (url.username !== '' || url.password !== '') return undefined
+  if (url.host === '') return undefined
+  return { protocol: url.protocol, authority: url.host }
+}
+
+/**
+ * The shell-owned Host authority the page is told to reach, read from the
+ * official transport hook. The global is written by the shell before any boot
+ * entry runs, so it is absent on every page it does not own.
+ * @param globals - the global object to read (defaults to the real one).
+ * @returns the published base URL, or undefined when the page carries none.
+ */
+function transportStreamBaseUrl(
+  globals: { __DSH_TRANSPORT__?: { streamBaseUrl?: unknown } } = globalThis as never,
+): string | undefined {
+  const published = (globals as { __DSH_TRANSPORT__?: { streamBaseUrl?: unknown } }).__DSH_TRANSPORT__?.streamBaseUrl
+  return typeof published === 'string' ? published : undefined
 }
 
 /**
@@ -448,11 +505,11 @@ export class SshApi {
 
   /** One terminal socket over either an alias (open) or a session id (attach). */
   private terminalSocket(search: string): TerminalConnection {
-    const target = terminalSocketUrl(window.location, search)
+    const target = terminalSocketUrl(window.location, search, transportStreamBaseUrl())
     if (target === undefined) {
-      // This page has no WebSocket transport at all (the desktop shell's
-      // custom scheme forwards HTTP only). Say so plainly instead of opening
-      // a socket that can only report "connection error".
+      // This page has no WebSocket transport at all: an application-delivered
+      // page whose shell published no Host authority to dial. Say so plainly
+      // instead of opening a socket that can only report "connection error".
       return failedTerminal(tt('terminal.noWebSocket'))
     }
     let socket: WebSocket

package/src/client/locales.ts

@@ -93,7 +93,7 @@ export const zh = {
   'terminal.ready': '终端已连接（{alias}）',
   'terminal.exited': '终端已退出（{alias}）',
   'terminal.error': '终端错误：{error}',
-  'terminal.noWebSocket': '当前页面不支持 WebSocket（应用外壳只转发 HTTP），请改用浏览器打开的 Web 界面使用终端。',
+  'terminal.noWebSocket': '当前页面不支持 WebSocket（应用外壳没有可连接的本地主机地址），请改用浏览器打开的 Web 界面使用终端。',
   'terminal.auth.title': '二次身份验证 (2FA / 交互式认证)',
   'terminal.auth.submit': '提交验证码',
   'terminal.auth.cancel': '取消',
@@ -254,7 +254,7 @@ export const en: Record<keyof typeof zh, string> = {
   'terminal.ready': 'Terminal connected ({alias})',
   'terminal.exited': 'Terminal exited ({alias})',
   'terminal.error': 'Terminal error: {error}',
-  'terminal.noWebSocket': 'This page cannot carry a WebSocket (the application shell forwards HTTP only). Open the Web UI in a browser to use the terminal.',
+  'terminal.noWebSocket': 'This page cannot carry a WebSocket (the application shell published no local host address to reach). Open the Web UI in a browser to use the terminal.',
   'terminal.auth.title': 'Two-Factor Authentication (2FA)',
   'terminal.auth.submit': 'Submit Code',
   'terminal.auth.cancel': 'Cancel',

package/src/engine/cluster.ts

@@ -13,6 +13,8 @@ interface ClusterOptions {
   tags?: string[]
   timeoutMs?: number
   maxWorkers?: number
+  /** Caller cancellation, forwarded to every host's command. */
+  signal?: AbortSignal
 }
 
 /** Run one command against many hosts concurrently. */
@@ -46,7 +48,7 @@ export async function cluster(engine: PoolEngine, options: ClusterOptions): Prom
     while (queue.length > 0) {
       const entry = queue.shift()!
       try {
-        const result = await execCommand(engine, entry.alias, options.command, options.timeoutMs)
+        const result = await execCommand(engine, entry.alias, options.command, options.timeoutMs, options.signal)
         results.push({ alias: entry.alias, ok: result.success, exitCode: result.exitCode, timedOut: result.timedOut, stdout: result.stdout, stderr: result.stderr, durationMs: result.durationMs })
       } catch (error) {
         results.push({ alias: entry.alias, ok: false, error: error instanceof Error ? error.message : String(error) })

package/src/engine/connection-pool.ts

@@ -398,7 +398,7 @@ export function sweepPool(engine: PoolEngine): void {
  * Run `fn` with a live client for `alias`, reconnecting (up to the
  * attempt budget) when the connection broke mid-flight.
  */
-export async function withClient<T>(engine: PoolEngine, alias: string, fn: (client: Client) => Promise<T>, attempts = 3): Promise<T> {
+export async function withClient<T>(engine: PoolEngine, alias: string, fn: (client: Client) => Promise<T>, attempts = 3, signal?: AbortSignal): Promise<T> {
   let lastError: unknown
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
     let record = engine.pool.get(alias)
@@ -414,6 +414,9 @@ export async function withClient<T>(engine: PoolEngine, alias: string, fn: (clie
       return result
     } catch (error) {
       lastError = error
+      // A cancelled call is never replayed: the caller asked for it to stop,
+      // and a retry would re-run a command that may not be idempotent.
+      if (signal?.aborted === true) throw error
       // Retry only when the connection actually broke mid-flight: drop the
       // corpse and let the next attempt reconnect (a reconnect may replay a
       // non-idempotent command — the documented trade-off). A failure on a
@@ -428,24 +431,53 @@ export async function withClient<T>(engine: PoolEngine, alias: string, fn: (clie
 }
 
 /** Run one command on `alias` (reusing the pooled connection). */
-export async function execCommand(engine: PoolEngine, alias: string, command: string, timeoutMs?: number): Promise<ExecResult> {
+export async function execCommand(engine: PoolEngine, alias: string, command: string, timeoutMs?: number, signal?: AbortSignal): Promise<ExecResult> {
   const started = Date.now()
   const budget = timeoutMs !== undefined && timeoutMs > 0 ? timeoutMs : engine.opts.defaultExecTimeoutMs
   return withClient(engine, alias, async (client) => {
     return await new Promise<ExecResult>((resolve, reject) => {
+      // Caller cancellation is cooperative and quiescent: aborting closes the
+      // remote channel and settles this call like a timeout does, so the
+      // command stops without the pool replaying it. The channel is captured
+      // in a mutable slot because abort may fire before client.exec calls back.
+      let aborted = signal !== undefined && signal.aborted
+      let kill = (): void => { /* channel not open yet */ }
+      const onAbort = (): void => {
+        aborted = true
+        kill()
+      }
+      if (signal !== undefined && !signal.aborted) signal.addEventListener('abort', onAbort, { once: true })
       client.exec(command, (error, stream) => {
         if (error !== undefined) {
+          signal?.removeEventListener('abort', onAbort)
           reject(error)
           return
         }
+        kill = (): void => {
+          try { stream.signal('KILL') } catch { /* channel gone */ }
+          try { stream.close() } catch { /* channel gone */ }
+        }
+        // The abort may already have arrived while this channel opened.
+        if (aborted) kill()
         const stdout = { text: '', truncated: false }
         const stderr = { text: '', truncated: false }
         let timedOut = false
         let settled = false
+        /** One cancelled outcome: the remote channel was killed on caller request. */
+        const cancelledResult = (): ExecResult => ({
+          success: false,
+          exitCode: null,
+          timedOut: false,
+          stdout: stdout.text,
+          stderr: stderr.text,
+          durationMs: Date.now() - started,
+          error: 'command cancelled by the caller',
+        })
         const finish = (): void => {
           if (settled) return
           settled = true
           clearTimeout(timer)
+          signal?.removeEventListener('abort', onAbort)
           resolve({
             success: false,
             exitCode: null,
@@ -470,6 +502,14 @@ export async function execCommand(engine: PoolEngine, alias: string, command: st
           if (settled) return
           settled = true
           clearTimeout(timer)
+          signal?.removeEventListener('abort', onAbort)
+          // A caller cancellation settles as cancelled, never as a broken
+          // connection: the latter would send withClient into a retry that
+          // re-runs a command the caller asked to stop.
+          if (aborted) {
+            resolve(cancelledResult())
+            return
+          }
           if (typeof code !== 'number' && !timedOut) {
             // The channel closed without an exit status: the connection
             // dropped mid-flight. Reject so withClient can reconnect and
@@ -490,6 +530,11 @@ export async function execCommand(engine: PoolEngine, alias: string, command: st
           if (settled) return
           settled = true
           clearTimeout(timer)
+          signal?.removeEventListener('abort', onAbort)
+          if (aborted) {
+            resolve(cancelledResult())
+            return
+          }
           reject(streamError)
         })
       })

package/src/engine/tunnel.ts

@@ -16,6 +16,8 @@ export interface TunnelRecord {
   /** The pooled connection this tunnel pins; siblings on one alias may share it. */
   record: PoolRecord
   sockets: Set<Socket>
+  /** Detach the link-death hook startTunnel installs on the pooled client. */
+  detachLink?: () => void
 }
 
 /** The engine slice the tunnel module needs (adds the tunnel registry). */
@@ -24,6 +26,22 @@ export interface TunnelEngine extends PoolEngine {
   nextTunnelId: number
 }
 
+/** Destroy one socket or channel stream, tolerating an already-dead peer. */
+function destroyQuietly(target: { destroy(): void }): void {
+  try { target.destroy() } catch { /* already closed */ }
+}
+
+/**
+ * Tear down one tunnel because the SSH link behind it is gone. Idempotent: the
+ * tunnel registry is the guard, so a socket callback or a link-death hook that
+ * arrives after a manual stop does nothing instead of tearing down twice, and
+ * no teardown error can escape into the net connection handler — an exception
+ * there terminates the whole host process.
+ */
+function abortTunnel(engine: TunnelEngine, id: string): void {
+  try { stopTunnel(engine, id) } catch { /* teardown already in progress */ }
+}
+
 /** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
 export async function startTunnel(
   engine: TunnelEngine,
@@ -58,26 +76,47 @@ export async function startTunnel(
   const record = engine.pool.get(alias) ?? (await acquire(engine, alias))
   const client = record.client
   const sockets = new Set<Socket>()
+  // A tunnel whose SSH link died can only refuse what it is handed, so every
+  // path that learns the link is gone tears the tunnel down as well instead
+  // of leaving a listener alive on a connection that forwards nothing.
+  const onLinkClosed = (): void => { abortTunnel(engine, id) }
+  const detachLink = (): void => { client.off('close', onLinkClosed) }
   const server = createServer((socket) => {
     sockets.add(socket)
     socket.on('close', () => { sockets.delete(socket) })
-    client.forwardOut('127.0.0.1', 0, remoteHost, options.remotePort, (error, stream) => {
-      if (error !== undefined) {
-        socket.destroy()
-        return
-      }
-      // Both ends of the pipe can die independently; destroy the pair so an
-      // unhandled 'error' event can never crash the host process.
-      const destroy = (): void => {
-        try { socket.destroy() } catch { /* gone */ }
-        try { stream.close() } catch { /* gone */ }
-      }
-      stream.on('error', destroy)
-      socket.on('error', destroy)
-      stream.on('close', destroy)
-      socket.on('close', destroy)
-      stream.pipe(socket).pipe(stream)
-    })
+    // The link can die between taking the record above and this connection.
+    if (record.broken) {
+      destroyQuietly(socket)
+      abortTunnel(engine, id)
+      return
+    }
+    try {
+      client.forwardOut('127.0.0.1', 0, remoteHost, options.remotePort, (error, stream) => {
+        if (error !== undefined) {
+          // A refused remote channel is the remote service's answer, not a
+          // dead SSH link: the tunnel itself stays up for the next attempt.
+          destroyQuietly(socket)
+          return
+        }
+        // Both ends of the pipe can die independently; destroy the pair so an
+        // unhandled 'error' event can never crash the host process.
+        const destroy = (): void => {
+          destroyQuietly(socket)
+          try { stream.close() } catch { /* gone */ }
+        }
+        stream.on('error', destroy)
+        socket.on('error', destroy)
+        stream.on('close', destroy)
+        socket.on('close', destroy)
+        stream.pipe(socket).pipe(stream)
+      })
+    } catch {
+      // ssh2 reports 'Not connected' by throwing out of forwardOut rather than
+      // through the callback; an exception escaping this connection handler
+      // is an uncaught exception that takes the host process down with it.
+      destroyQuietly(socket)
+      abortTunnel(engine, id)
+    }
   })
   try {
     await new Promise<void>((resolve, reject) => {
@@ -96,7 +135,20 @@ export async function startTunnel(
   const address = server.address()
   info.localPort = typeof address === 'object' && address !== null ? address.port : 0
   info.state = 'forwarding'
-  engine.tunnels.set(id, { info, server, alias, record, sockets })
+  engine.tunnels.set(id, { info, server, alias, record, sockets, detachLink })
+  // A dead link must not keep a listener alive: without this hook the tunnel
+  // outlives its connection and every later local connection hits the dead
+  // forwardOut path above.
+  client.once('close', onLinkClosed)
+  if (record.broken) {
+    // A link that died while the listener was binding already emitted 'close',
+    // so the pool's broken flag is the only signal left for that window. The
+    // tunnel retires right away, and the start reports that instead of
+    // handing the caller a forwarding tunnel that no longer exists.
+    info.state = 'failed'
+    info.error = 'ssh link closed while the tunnel was starting'
+    abortTunnel(engine, id)
+  }
   return info
 }
 
@@ -110,9 +162,12 @@ export function stopTunnel(engine: TunnelEngine, id: string): boolean {
   const tunnel = engine.tunnels.get(id)
   if (tunnel === undefined) return false
   engine.tunnels.delete(id)
+  // Drop the link-death hook first: a stop is never the link's death, and a
+  // long-lived pooled client outlives many tunnels.
+  try { tunnel.detachLink?.() } catch { /* already detached */ }
   try { tunnel.server.close() } catch { /* already closed */ }
   for (const socket of tunnel.sockets) {
-    try { socket.destroy() } catch { /* already closed */ }
+    destroyQuietly(socket)
   }
   tunnel.sockets.clear()
   // Sibling tunnels on the same alias share the pinned connection: release it

package/src/engine.ts

@@ -74,8 +74,8 @@ export class SshEngine {
   // ------------------------------------------------------------ exec
 
   /** Run one command on `alias` (reusing the pooled connection). */
-  async exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult> {
-    return execCommand(this, alias, command, timeoutMs)
+  async exec(alias: string, command: string, timeoutMs?: number, signal?: AbortSignal): Promise<ExecResult> {
+    return execCommand(this, alias, command, timeoutMs, signal)
   }
 
   /** Run one command against many hosts concurrently. */
@@ -86,6 +86,7 @@ export class SshEngine {
     tags?: string[]
     timeoutMs?: number
     maxWorkers?: number
+    signal?: AbortSignal
   }): Promise<ClusterResult[]> {
     return cluster(this, options)
   }

package/src/index.ts

@@ -18,6 +18,7 @@ import { makeRoutes } from './routes.ts'
 import { HostStore } from './store.ts'
 import { sshClusterTool, sshDownloadTool, sshExecTool, sshListTool, sshTunnelTool, sshUploadTool } from './tools.ts'
 import { mountOnce } from './mount-once.ts'
+import { PLUGIN_TOOL_SECTION_ORDERS, visibleToolText } from './tool-surface.ts'
 
 /** Stable cordis plugin name. */
 export const name = 'ssh'
@@ -117,8 +118,11 @@ function profileConfig(ctx: Context): Record<string, unknown> | undefined {
   return config as Record<string, unknown>
 }
 
-/** Order of the announcement section within the tool-guidance band. */
-const SECTION_ORDER = 150
+/** Order of the announcement section within the shared tool-guidance band. */
+const SECTION_ORDER = PLUGIN_TOOL_SECTION_ORDERS.ssh
+
+/** The six agent-tool names this plugin's announcement describes. */
+const SSH_TOOL_NAMES = ['ssh_list', 'ssh_exec', 'ssh_upload', 'ssh_download', 'ssh_tunnel', 'ssh_cluster'] as const
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
 export const SSH_GUIDANCE = '本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 $DSH_HOME/dsh-ssh.json（默认 ~/.dsh）（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 按 aliases/environment/tags 至少一种非空 selector 筛选后集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥、ProxyJump 跳板机（别名或 [user@]host[:port] 地址）与 OpenSSH 语义的 ProxyCommand（跳过堡垒机客户端场景，只能由用户在 GUI 配置，agent 不可写）；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
@@ -190,7 +194,11 @@ function applyImpl(ctx: Context, config?: ResolvedConfig): void {
       disposeSection = ctx.systemPrompt.section({
         name: 'plugin:dsh-ssh',
         order: SECTION_ORDER,
-        text: SSH_GUIDANCE,
+        // The announcement names the ssh_* tools, so it renders only while at
+        // least one of them is reachable: a restriction that removes the tool
+        // surface must take the guidance with it, instead of telling the model
+        // to call tools this session cannot see.
+        text: visibleToolText(ctx.tools, SSH_TOOL_NAMES, SSH_GUIDANCE),
       })
     }
     disposeRoutes = ctx.effect(

package/src/tool-surface.ts

@@ -0,0 +1,95 @@
+// Generated by scripts/sync-shared.mjs from shared/host/tool-surface.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Family-shared tool-surface conventions for the packages that register
+ * model-facing tools.
+ *
+ * One home for the prompt-section placement and the visibility gate this
+ * family previously restated per package.
+ *
+ * Modelled on the official tool packages:
+ * - `@deepseek-ai/dsh-tool-subagent` renders its section through
+ *   `tools.get(name, context.scope) === undefined ? '' : text`, so guidance
+ *   disappears together with a restricted tool.
+ * - 21 of the 22 official tool packages register their tools GLOBALLY and gate
+ *   them with a setting, not per agent. Only the Agent Teams tool package —
+ *   whose tools belong to one membership — installs into each `agent.ctx`.
+ *   This family follows the majority: registration stays global so the
+ *   registry's per-scope `restrict()` mask (which filters inherited global
+ *   tools and REJECTS scope-local names) can still withhold these tools.
+ *
+ * Structural types only: this copy lands in packages that do not all depend on
+ * the same SDK service packages.
+ */
+
+/**
+ * Prompt-section order for each package's tool guidance.
+ *
+ * These sit in the family band between the deployment persona and the SDK's
+ * `PLAN_POLICY` (500). Values are owned here rather than written per package so
+ * the host plugins whose guidance shares one prompt cannot drift into an
+ * accidental tie.
+ */
+export const PLUGIN_TOOL_SECTION_ORDERS = {
+  ssh: 150,
+  'task-board': 200,
+} as const
+
+/** One plugin id keyed by {@link PLUGIN_TOOL_SECTION_ORDERS}. */
+export type PluginToolSectionId = keyof typeof PLUGIN_TOOL_SECTION_ORDERS
+
+/**
+ * Order of an external provider extension's own guidance section, right after
+ * the band of the plugin it extends.
+ *
+ * An extension names itself, not the plugin it plugs into, so its order stays
+ * out of {@link PLUGIN_TOOL_SECTION_ORDERS}: every package's copy of this module
+ * then carries no provider id. The slot still has one owner and cannot collide
+ * with a host plugin's band.
+ */
+export const EXTENSION_TOOL_SECTION_ORDER = 210
+
+/**
+ * The scoped tool lookup a section provider needs: the registry read for one
+ * assembly's scope. Matches `ctx.tools.get(name, scope)`.
+ */
+export interface ScopedToolLookup {
+  get(name: string, scope?: unknown): unknown
+}
+
+/** One assembly context carrying the scope the section is rendered for. */
+export interface SectionScopeContext {
+  scope?: unknown
+}
+
+/**
+ * Build a section provider that renders \`text\` only while at least one of
+ * \`toolNames\` is visible to the rendering scope.
+ *
+ * The native convention: a tool that a restriction, a preset, or a missing
+ * registry removed must not leave guidance behind telling the model to call it.
+ * An unreadable registry renders the text unchanged — guidance that outlives a
+ * momentary read failure is recoverable; guidance for a tool that is gone is
+ * not.
+ * @param tools - the scoped tool registry, when the deployment serves one.
+ * @param toolNames - registered names the guidance describes.
+ * @param text - the guidance rendered while they are reachable.
+ * @returns the section text provider.
+ */
+export function visibleToolText(
+  tools: ScopedToolLookup | undefined,
+  toolNames: readonly string[],
+  text: string,
+): (context: SectionScopeContext) => string {
+  if (tools === undefined) return () => text
+  return (context: SectionScopeContext) => {
+    for (const name of toolNames) {
+      try {
+        if (tools.get(name, context.scope) !== undefined) return text
+      } catch {
+        // A refused lookup is not proof the tool is gone; keep the guidance.
+        return text
+      }
+    }
+    return ''
+  }
+}