@linxin666/dsh-ssh 0.4.4 → 0.4.5

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.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 ''
+  }
+}

package/src/tools.ts

@@ -91,8 +91,7 @@ function renderTunnel(tunnel: TunnelInfo): string {
 export function sshListTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_list',
-    description: 'List configured SSH hosts (alias, host, user, auth, environment, tags, description). Use ssh_exec etc. with the alias. ' +
-      'Triggers: SSH, remote server, server IP/hostname, connect/login, check server/status, deploy, upload/download, jump host, tunnel, port forward.',
+    description: 'List configured SSH hosts (alias, host, user, auth, environment, tags, description). Use ssh_exec etc. with the alias.',
     parameters: {
       query: { type: 'string', description: 'Optional fuzzy match against alias, description, host, and tags.' },
     },
@@ -129,6 +128,8 @@ export function sshListTool(engine: SshEngine) {
       },
       render: (_args, value: { hosts?: AgentHostRow[] }) => text(renderHosts(value.hosts ?? [])),
     },
+    // Reads the local host registry only: safe to overlap with sibling calls.
+    isConcurrencySafe: () => true,
     async execute(args) {
       return { hosts: engine.list(args.query).map(toAgentHostRow) }
     },
@@ -139,8 +140,7 @@ export function sshListTool(engine: SshEngine) {
 export function sshExecTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_exec',
-    description: 'Execute a shell command on a REMOTE SSH host by alias; the command runs on the remote host, never on this machine. For commands on this machine, use the local bash tool. Prefer combining independent read-only queries into one command. ' +
-      'Triggers: run command on server, deploy, check server/status, service control, view logs, any remote operation.',
+    description: 'Execute a shell command on a REMOTE SSH host by alias; the command runs on the remote host, never on this machine. For commands on this machine, use the local bash tool. Prefer combining independent read-only queries into one command.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
       command: { type: 'string', required: true, description: 'The shell command to run remotely.' },
@@ -162,9 +162,11 @@ export function sshExecTool(engine: SshEngine) {
       },
       render: (_args, value: ExecResult) => text(renderExec(value)),
     },
-    async execute(args) {
+    async execute(args, exec) {
       try {
-        return await engine.exec(args.alias, args.command, args.timeoutMs)
+        // Forward the caller's cancellation: aborting closes the remote channel
+        // instead of leaving the command running on the host.
+        return await engine.exec(args.alias, args.command, args.timeoutMs, exec.signal)
       } catch (error) {
         return {
           success: false,
@@ -184,8 +186,7 @@ export function sshExecTool(engine: SshEngine) {
 export function sshUploadTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_upload',
-    description: 'Transfer a file FROM this machine (the dsh host) TO a remote SSH host. Use this only when the file must be copied to the remote host. Files that stay on this machine are handled with the local file tools (read / write / edit), not ssh_upload. ' +
-      'Triggers: upload file to server, deploy artifact, copy config to server.',
+    description: 'Transfer a file FROM this machine (the dsh host) TO a remote SSH host. Use this only when the file must be copied to the remote host. Files that stay on this machine are handled with the local file tools (read / write / edit), not ssh_upload.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
       localPath: { type: 'string', required: true, description: 'Absolute path of the source file on THIS machine (the dsh host) — not a path on the remote host.' },
@@ -221,8 +222,7 @@ export function sshUploadTool(engine: SshEngine) {
 export function sshDownloadTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_download',
-    description: 'Copy a remote FILE from a configured SSH host to this machine (the dsh host). Use this only when the source is on the remote host; files already on this machine are read with the local file tools (read / write / edit), not ssh_download. Directory download is not supported — download files individually. ' +
-      'Triggers: download file from server, fetch remote log/artifact.',
+    description: 'Copy a remote FILE from a configured SSH host to this machine (the dsh host). Use this only when the source is on the remote host; files already on this machine are read with the local file tools (read / write / edit), not ssh_download. Directory download is not supported — download files individually.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
       remotePath: { type: 'string', required: true, description: 'Absolute path of the source file on the remote SSH host.' },
@@ -257,8 +257,7 @@ export function sshDownloadTool(engine: SshEngine) {
 export function sshTunnelTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_tunnel',
-    description: 'Manage local port-forward tunnels to a configured SSH host. Start a tunnel to reach a remote internal service (database, web UI, API) through 127.0.0.1 on this machine. ' +
-      'Triggers: tunnel, port forward, connect database, access internal service.',
+    description: 'Manage local port-forward tunnels to a configured SSH host. Start a tunnel to reach a remote internal service (database, web UI, API) through 127.0.0.1 on this machine.',
     parameters: {
       action: { type: 'string', required: true, enum: ['start', 'list', 'stop', 'stop-all'], description: 'start / list / stop / stop-all.' },
       alias: { type: 'string', description: 'Host alias (required for start, optional for stop-all).' },
@@ -357,8 +356,7 @@ export function sshTunnelTool(engine: SshEngine) {
 export function sshClusterTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_cluster',
-    description: 'Run one command concurrently across selected SSH hosts; at least one aliases, environment, or tags filter is required. ' +
-      'Triggers: run on selected servers, batch operation, production servers, cluster command.',
+    description: 'Run one command concurrently across selected SSH hosts; at least one aliases, environment, or tags filter is required.',
     parameters: {
       command: { type: 'string', required: true, description: 'The shell command to run on every matched host.' },
       aliases: { type: 'array', items: { type: 'string' }, description: 'Optional alias filter; at least one of aliases, environment, or tags is required.' },
@@ -394,12 +392,13 @@ export function sshClusterTool(engine: SshEngine) {
       },
       render: (_args, value: { results?: ClusterResult[] }) => text(renderCluster(value.results ?? [])),
     },
-    async execute(args) {
+    async execute(args, exec) {
       const hasSelector = (Array.isArray(args.aliases) && args.aliases.some((alias) => typeof alias === 'string' && alias.trim() !== '')) ||
         (typeof args.environment === 'string' && args.environment.trim() !== '') ||
         (Array.isArray(args.tags) && args.tags.some((tag) => typeof tag === 'string' && tag.trim() !== ''))
       if (!hasSelector) throw new Error('ssh_cluster requires aliases, environment, or tags to limit the target set')
-      return { results: await engine.cluster(args) }
+      // Cancellation reaches every host's in-flight command.
+      return { results: await engine.cluster({ ...args, signal: exec.signal }) }
     },
   })
 }