@linxin666/dsh-ssh 0.3.17 → 0.3.18

package/lib/index.js

@@ -2094,6 +2094,10 @@ function stopAllTunnels(engine, alias) {
 //#region src/engine/cluster.ts
 /** Run one command against many hosts concurrently. */
 async function cluster(engine, options) {
+	const hasAliases = Array.isArray(options.aliases) && options.aliases.some((alias) => typeof alias === "string" && alias.trim() !== "");
+	const hasEnvironment = typeof options.environment === "string" && options.environment.trim() !== "";
+	const hasTags = Array.isArray(options.tags) && options.tags.some((tag) => typeof tag === "string" && tag.trim() !== "");
+	if (!hasAliases && !hasEnvironment && !hasTags) throw new Error("ssh_cluster requires aliases, environment, or tags to limit the target set");
 	let targets = engine.store.list();
 	if (options.aliases !== void 0 && options.aliases.length > 0) targets = targets.filter((entry) => options.aliases.includes(entry.alias));
 	if (options.environment !== void 0 && options.environment !== "") targets = targets.filter((entry) => entry.environment === options.environment);
@@ -2552,6 +2556,13 @@ function makeRoutes(deps) {
 					const environment = typeof body?.environment === "string" ? body.environment : void 0;
 					const timeoutMs = typeof body?.timeoutMs === "number" ? body.timeoutMs : void 0;
 					const maxWorkers = typeof body?.maxWorkers === "number" ? body.maxWorkers : void 0;
+					const hasAliases = aliases?.some((alias) => alias.trim() !== "") === true;
+					const hasEnvironment = typeof environment === "string" && environment.trim() !== "";
+					const hasTags = tags?.some((tag) => tag.trim() !== "") === true;
+					if (!hasAliases && !hasEnvironment && !hasTags) {
+						writeJson(res, 400, { error: "ssh_cluster requires aliases, environment, or tags to limit the target set" });
+						return;
+					}
 					try {
 						writeJson(res, 200, { results: await engine.cluster({
 							command,
@@ -3437,7 +3448,7 @@ function sshTunnelTool(engine) {
 function sshClusterTool(engine) {
 	return defineTool({
 		name: "ssh_cluster",
-		description: "Run one command concurrently across many SSH hosts (all hosts, or filtered by aliases / environment / tags). Triggers: run on all 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. Triggers: run on selected servers, batch operation, production servers, cluster command.",
 		parameters: {
 			command: {
 				type: "string",
@@ -3447,16 +3458,16 @@ function sshClusterTool(engine) {
 			aliases: {
 				type: "array",
 				items: { type: "string" },
-				description: "Explicit alias list; when absent every configured host matches."
+				description: "Optional alias filter; at least one of aliases, environment, or tags is required."
 			},
 			environment: {
 				type: "string",
-				description: "Only hosts with this environment label."
+				description: "Optional environment filter; at least one selector is required."
 			},
 			tags: {
 				type: "array",
 				items: { type: "string" },
-				description: "Only hosts carrying ALL these tags."
+				description: "Optional ALL-tags filter; at least one selector is required."
 			},
 			timeoutMs: {
 				type: "integer",
@@ -3499,6 +3510,7 @@ function sshClusterTool(engine) {
 			render: (_args, value) => text(renderCluster(value.results ?? []))
 		},
 		async execute(args) {
+			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) };
 		}
 	});
@@ -3570,7 +3582,7 @@ const DEFAULT_ANNOUNCE = false;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 150;
 /** 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 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
+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 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
 /**
 * Mount the SSH engine, routes, tools, and announcement.
 * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

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

@@ -126,7 +126,7 @@ export declare const zh: {
     readonly 'cluster.command': "命令";
     readonly 'cluster.run': "执行";
     readonly 'cluster.confirm': "确定在匹配的主机上执行该命令吗？该操作会真实运行在远程服务器上。";
-    readonly 'cluster.aliases': "主机别名（逗号分隔，留空为全部）";
+    readonly 'cluster.aliases': "主机别名（逗号分隔，与环境、标签至少填一项）";
     readonly 'cluster.environment': "环境过滤";
     readonly 'cluster.tags': "标签过滤（逗号分隔）";
     readonly 'cluster.results': "执行结果";

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

@@ -1,6 +1,6 @@
 /**
- * Cluster execution: run one command concurrently across many hosts (all, or
- * filtered by explicit aliases / environment / tags with ALL semantics).
+ * Cluster execution: run one command concurrently across selected hosts; the
+ * caller must provide at least one non-empty aliases / environment / tags filter.
  */
 import type { ClusterResult } from '../protocol.ts';
 import { type PoolEngine } from './connection-pool.ts';

package/lib/types/index.d.ts

@@ -39,7 +39,7 @@ export interface Config {
 }
 export declare const Config: z<Config>;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export declare const SSH_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-ssh \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B SSH \u8FD0\u7EF4\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CSSH\u300D\u5165\u53E3\uFF1B\u5728 dsh-web \u63D2\u4EF6\u5168\u5BB6\u6876\u4ED3\u5E93\uFF08packages/dsh-ssh\uFF09\u7EDF\u4E00\u7EF4\u62A4\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 $DSH_HOME/dsh-ssh.json\uFF08\u9ED8\u8BA4 ~/.dsh\uFF09\uFF08\u53EF\u4ECE ~/.ssh/config \u5BFC\u5165\uFF09\uFF1B\u6301\u4E45\u8FDE\u63A5\u6C60\u590D\u7528\u957F\u8FDE\u63A5\uFF08\u7A7A\u95F2 30 \u5206\u949F\u81EA\u52A8\u65AD\u5F00\uFF09\uFF1Bssh_list \u5217\u51FA\u4E3B\u673A\u3001ssh_exec \u6267\u884C\u8FDC\u7A0B\u547D\u4EE4\u3001ssh_upload/ssh_download \u4F20\u8F93\u6587\u4EF6\u3001ssh_tunnel \u672C\u5730\u7AEF\u53E3\u8F6C\u53D1\uFF08\u8BBF\u95EE\u8FDC\u7A0B\u6570\u636E\u5E93/\u5185\u7F51\u670D\u52A1\uFF09\u3001ssh_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801/ssh-agent \u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u4E0E ProxyJump \u8DF3\u677F\u673A\uFF1BWeb \u7EC8\u7AEF\u8D70 WebSocket\u3002\u9650\u5236\uFF1A\u4E3B\u673A\u64CD\u4F5C\u7531\u7528\u6237\u5728 GUI \u4E2D\u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u539F\u6837\u8FD4\u56DE\u3001\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u65AD\u7EBF\u91CD\u8FDE\u53EF\u80FD\u91CD\u653E\u975E\u5E42\u7B49\u547D\u4EE4\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u8DEF\u5F84\u533A\u5206\uFF1A\u672C\u673A\uFF08dsh host\uFF09\u4E0A\u7684\u6587\u4EF6\u4E0E\u547D\u4EE4\u4E00\u5F8B\u7528\u672C\u5730\u5DE5\u5177\uFF08read / write / edit / bash\uFF09\uFF0Cssh_* \u5DE5\u5177\u53EA\u9488\u5BF9\u8FDC\u7A0B\u4E3B\u673A\u4E0A\u7684\u8DEF\u5F84\u3002\u7528\u6237\u63D0\u5230\u300CSSH / \u8FDC\u7A0B\u670D\u52A1\u5668 / \u670D\u52A1\u5668\u64CD\u4F5C / \u8DF3\u677F\u673A / \u96A7\u9053 / \u90E8\u7F72 / \u4E0A\u4F20\u4E0B\u8F7D\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const SSH_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-ssh \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B SSH \u8FD0\u7EF4\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CSSH\u300D\u5165\u53E3\uFF1B\u5728 dsh-web \u63D2\u4EF6\u5168\u5BB6\u6876\u4ED3\u5E93\uFF08packages/dsh-ssh\uFF09\u7EDF\u4E00\u7EF4\u62A4\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 $DSH_HOME/dsh-ssh.json\uFF08\u9ED8\u8BA4 ~/.dsh\uFF09\uFF08\u53EF\u4ECE ~/.ssh/config \u5BFC\u5165\uFF09\uFF1B\u6301\u4E45\u8FDE\u63A5\u6C60\u590D\u7528\u957F\u8FDE\u63A5\uFF08\u7A7A\u95F2 30 \u5206\u949F\u81EA\u52A8\u65AD\u5F00\uFF09\uFF1Bssh_list \u5217\u51FA\u4E3B\u673A\u3001ssh_exec \u6267\u884C\u8FDC\u7A0B\u547D\u4EE4\u3001ssh_upload/ssh_download \u4F20\u8F93\u6587\u4EF6\u3001ssh_tunnel \u672C\u5730\u7AEF\u53E3\u8F6C\u53D1\uFF08\u8BBF\u95EE\u8FDC\u7A0B\u6570\u636E\u5E93/\u5185\u7F51\u670D\u52A1\uFF09\u3001ssh_cluster \u6309 aliases/environment/tags \u81F3\u5C11\u4E00\u79CD\u975E\u7A7A selector \u7B5B\u9009\u540E\u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801/ssh-agent \u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u4E0E ProxyJump \u8DF3\u677F\u673A\uFF1BWeb \u7EC8\u7AEF\u8D70 WebSocket\u3002\u9650\u5236\uFF1A\u4E3B\u673A\u64CD\u4F5C\u7531\u7528\u6237\u5728 GUI \u4E2D\u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u539F\u6837\u8FD4\u56DE\u3001\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u65AD\u7EBF\u91CD\u8FDE\u53EF\u80FD\u91CD\u653E\u975E\u5E42\u7B49\u547D\u4EE4\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u8DEF\u5F84\u533A\u5206\uFF1A\u672C\u673A\uFF08dsh host\uFF09\u4E0A\u7684\u6587\u4EF6\u4E0E\u547D\u4EE4\u4E00\u5F8B\u7528\u672C\u5730\u5DE5\u5177\uFF08read / write / edit / bash\uFF09\uFF0Cssh_* \u5DE5\u5177\u53EA\u9488\u5BF9\u8FDC\u7A0B\u4E3B\u673A\u4E0A\u7684\u8DEF\u5F84\u3002\u7528\u6237\u63D0\u5230\u300CSSH / \u8FDC\u7A0B\u670D\u52A1\u5668 / \u670D\u52A1\u5668\u64CD\u4F5C / \u8DF3\u677F\u673A / \u96A7\u9053 / \u90E8\u7F72 / \u4E0A\u4F20\u4E0B\u8F7D\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 /**
  * Mount the SSH engine, routes, tools, and announcement.
  * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

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.3.17",
+  "version": "0.3.18",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"

package/src/client/locales.ts

@@ -133,7 +133,7 @@ export const zh = {
   'cluster.command': '命令',
   'cluster.run': '执行',
   'cluster.confirm': '确定在匹配的主机上执行该命令吗？该操作会真实运行在远程服务器上。',
-  'cluster.aliases': '主机别名（逗号分隔，留空为全部）',
+  'cluster.aliases': '主机别名（逗号分隔，与环境、标签至少填一项）',
   'cluster.environment': '环境过滤',
   'cluster.tags': '标签过滤（逗号分隔）',
   'cluster.results': '执行结果',
@@ -282,7 +282,7 @@ export const en: Record<keyof typeof zh, string> = {
   'cluster.command': 'Command',
   'cluster.run': 'Run',
   'cluster.confirm': 'Run this command on the matching hosts? It executes for real on the remote servers.',
-  'cluster.aliases': 'Host aliases (comma-separated; empty = all)',
+  'cluster.aliases': 'Host aliases (comma-separated; require at least one filter)',
   'cluster.environment': 'Environment filter',
   'cluster.tags': 'Tag filter (comma-separated)',
   'cluster.results': 'Results',

package/src/engine/cluster.ts

@@ -1,6 +1,6 @@
 /**
- * Cluster execution: run one command concurrently across many hosts (all, or
- * filtered by explicit aliases / environment / tags with ALL semantics).
+ * Cluster execution: run one command concurrently across selected hosts; the
+ * caller must provide at least one non-empty aliases / environment / tags filter.
  */
 
 import type { ClusterResult } from '../protocol.ts'
@@ -17,6 +17,13 @@ interface ClusterOptions {
 
 /** Run one command against many hosts concurrently. */
 export async function cluster(engine: PoolEngine, options: ClusterOptions): Promise<ClusterResult[]> {
+  const hasAliases = Array.isArray(options.aliases) && options.aliases.some(alias => typeof alias === 'string' && alias.trim() !== '')
+  const hasEnvironment = typeof options.environment === 'string' && options.environment.trim() !== ''
+  const hasTags = Array.isArray(options.tags) && options.tags.some(tag => typeof tag === 'string' && tag.trim() !== '')
+  if (!hasAliases && !hasEnvironment && !hasTags) {
+    throw new Error('ssh_cluster requires aliases, environment, or tags to limit the target set')
+  }
+
   let targets = engine.store.list()
   if (options.aliases !== undefined && options.aliases.length > 0) {
     targets = targets.filter(entry => options.aliases!.includes(entry.alias))

package/src/index.ts

@@ -64,7 +64,7 @@ const DEFAULT_ANNOUNCE = false
 const SECTION_ORDER = 150
 
 /** 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 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
+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 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
 
 /**
  * Mount the SSH engine, routes, tools, and announcement.

package/src/routes.ts

@@ -225,6 +225,13 @@ const maxUploadBytes = deps.maxUploadBytes ?? MAX_UPLOAD_BYTES
         const environment = typeof body?.environment === 'string' ? body.environment : undefined
         const timeoutMs = typeof body?.timeoutMs === 'number' ? body.timeoutMs : undefined
         const maxWorkers = typeof body?.maxWorkers === 'number' ? body.maxWorkers : undefined
+        const hasAliases = aliases?.some(alias => alias.trim() !== '') === true
+        const hasEnvironment = typeof environment === 'string' && environment.trim() !== ''
+        const hasTags = tags?.some(tag => tag.trim() !== '') === true
+        if (!hasAliases && !hasEnvironment && !hasTags) {
+          writeJson(res, 400, { error: 'ssh_cluster requires aliases, environment, or tags to limit the target set' })
+          return
+        }
         try {
           writeJson(res, 200, { results: await engine.cluster({ command, aliases, environment, tags, timeoutMs, maxWorkers }) })
         } catch (error) {

package/src/tools.ts

@@ -327,13 +327,13 @@ export function sshTunnelTool(engine: SshEngine) {
 export function sshClusterTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_cluster',
-    description: 'Run one command concurrently across many SSH hosts (all hosts, or filtered by aliases / environment / tags). ' +
-      'Triggers: run on all 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. ' +
+      'Triggers: run on selected servers, batch operation, production servers, cluster command.',
     parameters: {
       command: { type: 'string', required: true, description: 'The shell command to run on every matched host.' },
-      aliases: { type: 'array', items: { type: 'string' }, description: 'Explicit alias list; when absent every configured host matches.' },
-      environment: { type: 'string', description: 'Only hosts with this environment label.' },
-      tags: { type: 'array', items: { type: 'string' }, description: 'Only hosts carrying ALL these tags.' },
+      aliases: { type: 'array', items: { type: 'string' }, description: 'Optional alias filter; at least one of aliases, environment, or tags is required.' },
+      environment: { type: 'string', description: 'Optional environment filter; at least one selector is required.' },
+      tags: { type: 'array', items: { type: 'string' }, description: 'Optional ALL-tags filter; at least one selector is required.' },
       timeoutMs: { type: 'integer', description: 'Per-host timeout in milliseconds.' },
       maxWorkers: { type: 'integer', description: 'Concurrency cap (default 8).' },
     },
@@ -365,6 +365,10 @@ export function sshClusterTool(engine: SshEngine) {
       render: (_args, value: { results?: ClusterResult[] }) => text(renderCluster(value.results ?? [])),
     },
     async execute(args) {
+      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) }
     },
   })