@linxin666/dsh-ssh 0.4.4 → 0.4.6

package/lib/index.js

@@ -1016,7 +1016,7 @@ function sweepPool(engine) {
 * Run `fn` with a live client for `alias`, reconnecting (up to the
 * attempt budget) when the connection broke mid-flight.
 */
-async function withClient(engine, alias, fn, attempts = 3) {
+async function withClient(engine, alias, fn, attempts = 3, signal) {
 	let lastError;
 	for (let attempt = 1; attempt <= attempts; attempt += 1) {
 		let record = engine.pool.get(alias);
@@ -1032,6 +1032,7 @@ async function withClient(engine, alias, fn, attempts = 3) {
 			return result;
 		} catch (error) {
 			lastError = error;
+			if (signal?.aborted === true) throw error;
 			if (!record.broken) throw error;
 			disposeRecord(engine, alias, record);
 		} finally {
@@ -1041,16 +1042,33 @@ async function withClient(engine, alias, fn, attempts = 3) {
 	throw lastError instanceof Error ? lastError : new Error(String(lastError));
 }
 /** Run one command on `alias` (reusing the pooled connection). */
-async function execCommand(engine, alias, command, timeoutMs) {
+async function execCommand(engine, alias, command, timeoutMs, signal) {
 	const started = Date.now();
 	const budget = timeoutMs !== void 0 && timeoutMs > 0 ? timeoutMs : engine.opts.defaultExecTimeoutMs;
 	return withClient(engine, alias, async (client) => {
 		return await new Promise((resolve, reject) => {
+			let aborted = signal !== void 0 && signal.aborted;
+			let kill = () => {};
+			const onAbort = () => {
+				aborted = true;
+				kill();
+			};
+			if (signal !== void 0 && !signal.aborted) signal.addEventListener("abort", onAbort, { once: true });
 			client.exec(command, (error, stream) => {
 				if (error !== void 0) {
+					signal?.removeEventListener("abort", onAbort);
 					reject(error);
 					return;
 				}
+				kill = () => {
+					try {
+						stream.signal("KILL");
+					} catch {}
+					try {
+						stream.close();
+					} catch {}
+				};
+				if (aborted) kill();
 				const stdout = {
 					text: "",
 					truncated: false
@@ -1061,10 +1079,21 @@ async function execCommand(engine, alias, command, timeoutMs) {
 				};
 				let timedOut = false;
 				let settled = false;
+				/** One cancelled outcome: the remote channel was killed on caller request. */
+				const cancelledResult = () => ({
+					success: false,
+					exitCode: null,
+					timedOut: false,
+					stdout: stdout.text,
+					stderr: stderr.text,
+					durationMs: Date.now() - started,
+					error: "command cancelled by the caller"
+				});
 				const finish = () => {
 					if (settled) return;
 					settled = true;
 					clearTimeout(timer);
+					signal?.removeEventListener("abort", onAbort);
 					resolve({
 						success: false,
 						exitCode: null,
@@ -1091,6 +1120,11 @@ async function execCommand(engine, alias, command, timeoutMs) {
 					if (settled) return;
 					settled = true;
 					clearTimeout(timer);
+					signal?.removeEventListener("abort", onAbort);
+					if (aborted) {
+						resolve(cancelledResult());
+						return;
+					}
 					if (typeof code !== "number" && !timedOut) {
 						reject(/* @__PURE__ */ new Error("ssh: connection lost mid-flight (channel closed without an exit status)"));
 						return;
@@ -1108,6 +1142,11 @@ async function execCommand(engine, alias, command, timeoutMs) {
 					if (settled) return;
 					settled = true;
 					clearTimeout(timer);
+					signal?.removeEventListener("abort", onAbort);
+					if (aborted) {
+						resolve(cancelledResult());
+						return;
+					}
 					reject(streamError);
 				});
 			});
@@ -1413,6 +1452,24 @@ function fastGet(sftp, src, dst, concurrency, onProgress) {
 * to a pooled connection so an idle sweep never closes it, with per-tunnel
 * socket tracking and stop (single / alias-scoped / all).
 */
+/** Destroy one socket or channel stream, tolerating an already-dead peer. */
+function destroyQuietly(target) {
+	try {
+		target.destroy();
+	} catch {}
+}
+/**
+* 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, id) {
+	try {
+		stopTunnel(engine, id);
+	} catch {}
+}
 /** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
 async function startTunnel(engine, alias, options) {
 	if (!Number.isInteger(options.remotePort) || options.remotePort < 1 || options.remotePort > 65535) throw new Error("remotePort must be an integer in 1..65535");
@@ -1435,30 +1492,44 @@ async function startTunnel(engine, alias, options) {
 	const record = engine.pool.get(alias) ?? await acquire(engine, alias);
 	const client = record.client;
 	const sockets = /* @__PURE__ */ new Set();
+	const onLinkClosed = () => {
+		abortTunnel(engine, id);
+	};
+	const detachLink = () => {
+		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 !== void 0) {
-				socket.destroy();
-				return;
-			}
-			const destroy = () => {
-				try {
-					socket.destroy();
-				} catch {}
-				try {
-					stream.close();
-				} catch {}
-			};
-			stream.on("error", destroy);
-			socket.on("error", destroy);
-			stream.on("close", destroy);
-			socket.on("close", destroy);
-			stream.pipe(socket).pipe(stream);
-		});
+		if (record.broken) {
+			destroyQuietly(socket);
+			abortTunnel(engine, id);
+			return;
+		}
+		try {
+			client.forwardOut("127.0.0.1", 0, remoteHost, options.remotePort, (error, stream) => {
+				if (error !== void 0) {
+					destroyQuietly(socket);
+					return;
+				}
+				const destroy = () => {
+					destroyQuietly(socket);
+					try {
+						stream.close();
+					} catch {}
+				};
+				stream.on("error", destroy);
+				socket.on("error", destroy);
+				stream.on("close", destroy);
+				socket.on("close", destroy);
+				stream.pipe(socket).pipe(stream);
+			});
+		} catch {
+			destroyQuietly(socket);
+			abortTunnel(engine, id);
+		}
 	});
 	try {
 		await new Promise((resolve, reject) => {
@@ -1481,8 +1552,15 @@ async function startTunnel(engine, alias, options) {
 		server,
 		alias,
 		record,
-		sockets
+		sockets,
+		detachLink
 	});
+	client.once("close", onLinkClosed);
+	if (record.broken) {
+		info.state = "failed";
+		info.error = "ssh link closed while the tunnel was starting";
+		abortTunnel(engine, id);
+	}
 	return info;
 }
 /** All active tunnels. */
@@ -1495,11 +1573,12 @@ function stopTunnel(engine, id) {
 	if (tunnel === void 0) return false;
 	engine.tunnels.delete(id);
 	try {
-		tunnel.server.close();
+		tunnel.detachLink?.();
 	} catch {}
-	for (const socket of tunnel.sockets) try {
-		socket.destroy();
+	try {
+		tunnel.server.close();
 	} catch {}
+	for (const socket of tunnel.sockets) destroyQuietly(socket);
 	tunnel.sockets.clear();
 	if (![...engine.tunnels.values()].some((candidate) => candidate.record === tunnel.record)) if (engine.pool.get(tunnel.alias) === tunnel.record) disposeRecord(engine, tunnel.alias, tunnel.record);
 	else endRecordChain(tunnel.record);
@@ -1535,7 +1614,7 @@ async function cluster(engine, options) {
 		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,
@@ -1595,8 +1674,8 @@ var SshEngine = class {
 		return entry === void 0 ? void 0 : this.store.summarize(entry);
 	}
 	/** Run one command on `alias` (reusing the pooled connection). */
-	async exec(alias, command, timeoutMs) {
-		return execCommand(this, alias, command, timeoutMs);
+	async exec(alias, command, timeoutMs, signal) {
+		return execCommand(this, alias, command, timeoutMs, signal);
 	}
 	/** Run one command against many hosts concurrently. */
 	async cluster(options) {
@@ -2594,7 +2673,7 @@ function renderTunnel(tunnel) {
 function sshListTool(engine) {
 	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."
@@ -2670,6 +2749,7 @@ function sshListTool(engine) {
 			},
 			render: (_args, value) => text(renderHosts(value.hosts ?? []))
 		},
+		isConcurrencySafe: () => true,
 		async execute(args) {
 			return { hosts: engine.list(args.query).map(toAgentHostRow) };
 		}
@@ -2679,7 +2759,7 @@ function sshListTool(engine) {
 function sshExecTool(engine) {
 	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",
@@ -2730,9 +2810,9 @@ function sshExecTool(engine) {
 			},
 			render: (_args, value) => text(renderExec(value))
 		},
-		async execute(args) {
+		async execute(args, exec) {
 			try {
-				return await engine.exec(args.alias, args.command, args.timeoutMs);
+				return await engine.exec(args.alias, args.command, args.timeoutMs, exec.signal);
 			} catch (error) {
 				return {
 					success: false,
@@ -2751,7 +2831,7 @@ function sshExecTool(engine) {
 function sshUploadTool(engine) {
 	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",
@@ -2806,7 +2886,7 @@ function sshUploadTool(engine) {
 function sshDownloadTool(engine) {
 	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",
@@ -2858,7 +2938,7 @@ function sshDownloadTool(engine) {
 function sshTunnelTool(engine) {
 	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",
@@ -3053,7 +3133,7 @@ function sshTunnelTool(engine) {
 function sshClusterTool(engine) {
 	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",
@@ -3114,9 +3194,12 @@ function sshClusterTool(engine) {
 			},
 			render: (_args, value) => text(renderCluster(value.results ?? []))
 		},
-		async execute(args) {
+		async execute(args, exec) {
 			if (!(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() !== ""))) throw new Error("ssh_cluster requires aliases, environment, or tags to limit the target set");
-			return { results: await engine.cluster(args) };
+			return { results: await engine.cluster({
+				...args,
+				signal: exec.signal
+			}) };
 		}
 	});
 }
@@ -3235,6 +3318,66 @@ function mountOnce(packageName, fn) {
 	return mount;
 }
 //#endregion
+//#region src/tool-surface.ts
+/**
+* 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.
+*/
+const PLUGIN_TOOL_SECTION_ORDERS = {
+	ssh: 150,
+	"task-board": 200
+};
+/**
+* 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.
+*/
+function visibleToolText(tools, toolNames, text) {
+	if (tools === void 0) return () => text;
+	return (context) => {
+		for (const name of toolNames) try {
+			if (tools.get(name, context.scope) !== void 0) return text;
+		} catch {
+			return text;
+		}
+		return "";
+	};
+}
+//#endregion
 //#region src/index.ts
 /** Stable cordis plugin name. */
 const name = "ssh";
@@ -3275,8 +3418,17 @@ function profileConfig(ctx) {
 	if (typeof config !== "object" || config === null || Array.isArray(config)) return void 0;
 	return config;
 }
-/** 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"
+];
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
 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 / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
 /**
@@ -3332,7 +3484,7 @@ function applyImpl(ctx, config) {
 		if (value.announceToAgent) disposeSection = ctx.systemPrompt.section({
 			name: "plugin:dsh-ssh",
 			order: SECTION_ORDER,
-			text: SSH_GUIDANCE
+			text: visibleToolText(ctx.tools, SSH_TOOL_NAMES, SSH_GUIDANCE)
 		});
 		disposeRoutes = ctx.effect(() => {
 			const disposers = routes.map((route) => ctx.webServer.register(route));

package/lib/types/client/api.d.ts

@@ -18,22 +18,33 @@ 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 declare function terminalSocketUrl(location: PageLocation, search: string): string | undefined;
+export declare function terminalSocketUrl(location: PageLocation, search: string, streamBaseUrl?: string | undefined): string | undefined;
 /** 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. */

package/lib/types/client/locales.d.ts

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

package/lib/types/engine/cluster.d.ts

@@ -11,6 +11,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. */
 export declare function cluster(engine: PoolEngine, options: ClusterOptions): Promise<ClusterResult[]>;

package/lib/types/engine/connection-pool.d.ts

@@ -107,6 +107,6 @@ export declare 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 declare function withClient<T>(engine: PoolEngine, alias: string, fn: (client: Client) => Promise<T>, attempts?: number): Promise<T>;
+export declare function withClient<T>(engine: PoolEngine, alias: string, fn: (client: Client) => Promise<T>, attempts?: number, signal?: AbortSignal): Promise<T>;
 /** Run one command on `alias` (reusing the pooled connection). */
-export declare function execCommand(engine: PoolEngine, alias: string, command: string, timeoutMs?: number): Promise<ExecResult>;
+export declare function execCommand(engine: PoolEngine, alias: string, command: string, timeoutMs?: number, signal?: AbortSignal): Promise<ExecResult>;

package/lib/types/engine/tunnel.d.ts

@@ -14,6 +14,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). */
 export interface TunnelEngine extends PoolEngine {

package/lib/types/engine.d.ts

@@ -36,7 +36,7 @@ export declare class SshEngine {
     /** One host summary by alias. */
     find(alias: string): SshHostSummary | undefined;
     /** Run one command on `alias` (reusing the pooled connection). */
-    exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult>;
+    exec(alias: string, command: string, timeoutMs?: number, signal?: AbortSignal): Promise<ExecResult>;
     /** Run one command against many hosts concurrently. */
     cluster(options: {
         command: string;
@@ -45,6 +45,7 @@ export declare class SshEngine {
         tags?: string[];
         timeoutMs?: number;
         maxWorkers?: number;
+        signal?: AbortSignal;
     }): Promise<ClusterResult[]>;
     /** Open a PTY shell session for the web terminal (standalone connection). */
     openShell(alias: string, size: {

package/lib/types/tool-surface.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 declare const PLUGIN_TOOL_SECTION_ORDERS: {
+    readonly ssh: 150;
+    readonly 'task-board': 200;
+};
+/** 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 declare 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 declare function visibleToolText(tools: ScopedToolLookup | undefined, toolNames: readonly string[], text: string): (context: SectionScopeContext) => string;