fix(cli)!: select sub agent if available and error on multiple agents

mafredri · mafredri · commit 647181ea93a0 · 2025-06-18T13:07:55.000Z
In the past we randomly selected workspace agent if there were multiple. Unless both are running on the same machine with the same configuration, this would be very confusing behavior for a user. With the introduction of sub agents (devcontainer agents), it was decided prioritize them if present. Similarly as before, selecting a devcontainer randomly would be confusing. We now error out if the agent name is not specified and there are multiple agents. Fixes coder/internal#696
diff --git a/cli/ssh.go b/cli/ssh.go
@@ -925,36 +925,44 @@ func getWorkspaceAndAgent(ctx context.Context, inv *serpent.Invocation, client *
 func getWorkspaceAgent(workspace codersdk.Workspace, agentName string) (workspaceAgent codersdk.WorkspaceAgent, err error) {
 	resources := workspace.LatestBuild.Resources
 
-	agents := make([]codersdk.WorkspaceAgent, 0)
+	var (
+		availableNames []string
+		agents         []codersdk.WorkspaceAgent
+		subAgents      []codersdk.WorkspaceAgent
+	)
 	for _, resource := range resources {
-		agents = append(agents, resource.Agents...)
+		for _, agent := range resource.Agents {
+			availableNames = append(availableNames, agent.Name)
+			if agent.ParentID.UUID == uuid.Nil {
+				agents = append(agents, agent)
+			} else {
+				subAgents = append(subAgents, agent)
+			}
+		}
 	}
 	if len(agents) == 0 {
 		return codersdk.WorkspaceAgent{}, xerrors.Errorf("workspace %q has no agents", workspace.Name)
 	}
+	slices.Sort(availableNames)
 	if agentName != "" {
+		agents = append(agents, subAgents...)
 		for _, otherAgent := range agents {
 			if otherAgent.Name != agentName {
 				continue
 			}
-			workspaceAgent = otherAgent
-			break
-		}
-		if workspaceAgent.ID == uuid.Nil {
-			return codersdk.WorkspaceAgent{}, xerrors.Errorf("agent not found by name %q", agentName)
+			return otherAgent, nil
 		}
+		return codersdk.WorkspaceAgent{}, xerrors.Errorf("agent not found by name %q, available agents: %v", agentName, availableNames)
 	}
-	if workspaceAgent.ID == uuid.Nil {
-		if len(agents) > 1 {
-			workspaceAgent, err = cryptorand.Element(agents)
-			if err != nil {
-				return codersdk.WorkspaceAgent{}, err
-			}
-		} else {
-			workspaceAgent = agents[0]
-		}
+	if len(subAgents) == 1 {
+		return subAgents[0], nil
+	} else if len(subAgents) > 1 {
+		return codersdk.WorkspaceAgent{}, xerrors.Errorf("multiple sub-agents found, please specify the agent name, available agents: %v", availableNames)
+	}
+	if len(agents) == 1 {
+		return agents[0], nil
 	}
-	return workspaceAgent, nil
+	return codersdk.WorkspaceAgent{}, xerrors.Errorf("multiple agents found, please specify the agent name, available agents: %v", availableNames)
 }
 
 // Attempt to poll workspace autostop. We write a per-workspace lockfile to
