@linxin666/dsh-ssh 0.4.3 → 0.4.5

package/src/client/api.ts

@@ -76,6 +76,136 @@ function query(params: Record<string, string | number | undefined>): string {
   return text === '' ? '' : '?' + text
 }
 
+/** The location facts a terminal socket URL is built from. */
+interface PageLocation {
+  /** Page scheme with its colon (for example `https:` or `dsh-app:`). */
+  protocol: string
+  /** Page authority, empty for a scheme that carries none. */
+  host: string
+}
+
+/**
+ * The WebSocket URL the terminal route is reached at, or undefined when this
+ * page cannot carry one.
+ *
+ * A web page resolves the socket against its own origin, exactly as before.
+ *
+ * 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,
+  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
+  }
+  // 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
+}
+
+/**
+ * Schemes a network page can be delivered with. Every other scheme belongs to
+ * an application on this machine, which is the same classification the remote
+ * channel and the update seat use (`isWebPageProtocol` / `isApplicationDeliveredPage`).
+ */
+const WEB_PAGE_PROTOCOLS: readonly string[] = [
+  'http:',
+  'https:',
+  'blob:',
+  'data:',
+  'about:',
+  'filesystem:',
+]
+
+/**
+ * A terminal connection that never opened: it reports one failure once the
+ * view has attached its `onExit`, so the tab shows why instead of sitting on a
+ * spinner, and every later frame is a no-op.
+ */
+function failedTerminal(reason: string): TerminalConnection {
+  const connection: TerminalConnection = {
+    onReady: undefined,
+    onOutput: undefined,
+    onExit: undefined,
+    onAuthPrompt: undefined,
+    send: () => undefined,
+    resize: () => undefined,
+    sendAuthResponse: () => undefined,
+    detach: () => undefined,
+    close: () => undefined,
+  }
+  // The view binds onExit after the open() call returns, so the failure is
+  // delivered on the next microtask - never synchronously, which would race
+  // the handler the caller is about to assign.
+  queueMicrotask(() => { connection.onExit?.(null, reason) })
+  return connection
+}
+
 /** One open terminal connection (WebSocket JSON frames). */
 export interface TerminalConnection {
   /** Fired on the ready frame (shell is up); carries the host session id and alias. */
@@ -375,9 +505,19 @@ export class SshApi {
 
   /** One terminal socket over either an alias (open) or a session id (attach). */
   private terminalSocket(search: string): TerminalConnection {
-    const scheme = window.location.protocol === 'https:' ? 'wss' : 'ws'
-    const url = scheme + '://' + window.location.host + SSH_API.terminal + search
-    const socket = new WebSocket(url)
+    const target = terminalSocketUrl(window.location, search, transportStreamBaseUrl())
+    if (target === undefined) {
+      // 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
+    try {
+      socket = new WebSocket(target)
+    } catch (error) {
+      return failedTerminal(error instanceof Error ? error.message : String(error))
+    }
     // A deliberate detach/close must not surface as a transport error: the
     // view tears down silently, and only an UNEXPECTED close reports exit.
     let leaving = false

package/src/client/index.ts

@@ -54,7 +54,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 /** Required services (fiber inject waiting — the runtime must be up first). */
-export const inject = ['slots', 'locale', 'configForms']
+export const inject = ['slots', 'locale', 'configForms', 'layout']
 
 /** Type-only surface (export discipline: no value exports beyond the plugin contract). */
 export type { PanelControllerSnapshot } from './panel/controller.ts'
@@ -98,7 +98,7 @@ export function apply(ctx: ClientContext): void {
   const controller = new PanelController({
     panel: {
       select: panelId => {
-        const layout = ctx.get('layout') as { selectPanel?: (id: string | null) => void } | undefined
+        const layout = (ctx as unknown as { get?(name: string): unknown }).get?.('layout') as { selectPanel?: (id: string | null) => void } | undefined
         layout?.selectPanel?.(panelId)
       },
     },
@@ -122,7 +122,7 @@ export function apply(ctx: ClientContext): void {
     disposers.push(registerSshPanel(ctx, controller, api, terminalFont))
     // The layout's panel selection is reconciled back into the controller, so
     // the panel follows the user clicking another panel row.
-    const layoutFace = ctx.get('layout') as { panelInfo?: { subscribe(listener: () => void): () => void; getSnapshot(): { activePanelId: unknown } } } | undefined
+    const layoutFace = (ctx as unknown as { get?(name: string): unknown }).get?.('layout') as { panelInfo?: { subscribe(listener: () => void): () => void; getSnapshot(): { activePanelId: unknown } } } | undefined
     if (layoutFace?.panelInfo !== undefined) {
       const sync = (): void => {
         const active = layoutFace.panelInfo!.getSnapshot().activePanelId

package/src/client/locales.ts

@@ -93,6 +93,7 @@ export const zh = {
   'terminal.ready': '终端已连接（{alias}）',
   'terminal.exited': '终端已退出（{alias}）',
   'terminal.error': '终端错误：{error}',
+  'terminal.noWebSocket': '当前页面不支持 WebSocket（应用外壳没有可连接的本地主机地址），请改用浏览器打开的 Web 界面使用终端。',
   'terminal.auth.title': '二次身份验证 (2FA / 交互式认证)',
   'terminal.auth.submit': '提交验证码',
   'terminal.auth.cancel': '取消',
@@ -253,6 +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 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 }) }
     },
   })
 }