Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Polish harness creation and clarify quick-open results

deehw15132dfc74b9
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index b6c113089..6327fe49f 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -1475,7 +1475,11 @@ class _SwarmScreenState extends State<SwarmScreen> {
Widget _tabStrip() => LayoutBuilder(
builder: (context, constraints) {
- final compact = constraints.maxWidth < _labelledStripMinWidth;
+ final compact =
+ constraints.maxWidth <
+ _labelledStripMinWidth *
+ MediaQuery.textScalerOf(context).scale(12) /
+ 12;
return Container(
height: 52,
color: grid.AppPalette.swarmTabBar,
diff --git a/desktop/lib/shared/widgets/app_choice_picker.dart b/desktop/lib/shared/widgets/app_choice_picker.dart
index 3dc2030ee..2e97f7a85 100644
--- a/desktop/lib/shared/widgets/app_choice_picker.dart
+++ b/desktop/lib/shared/widgets/app_choice_picker.dart
@@ -246,8 +246,8 @@ class _AppChoicePickerState<T> extends State<AppChoicePicker<T>> {
final selectedExtra = extra != null && extra.value == widget.value;
final size = widget.tileSize!;
return Wrap(
- spacing: 10,
- runSpacing: 10,
+ spacing: AppChoiceTile.gap,
+ runSpacing: AppChoiceTile.gap,
children: [
for (final option in ordered.take(3))
AppChoiceTile(
@@ -270,12 +270,13 @@ class _AppChoicePickerState<T> extends State<AppChoicePicker<T>> {
onChanged: _choose,
width: size.width,
height: size.height,
+ padding: AppChoiceTile.padding,
selected: selectedExtra,
fillColor: selectedExtra
? AppPalette.swarmAccent.withValues(alpha: .16)
: AppSurface.recess,
trigger: AppChoiceTileContent(
- label: extra?.label ?? 'More',
+ label: extra?.label ?? widget.moreLabel,
detail: extra?.detail,
leading: extra == null
? widget.moreLeading
@@ -385,6 +386,9 @@ class _AppChoicePickerState<T> extends State<AppChoicePicker<T>> {
/// A shared tile keeps engine, machine and project rows on the same grid.
class AppChoiceTile extends StatelessWidget {
+ static const double gap = 12;
+ static const padding = EdgeInsets.symmetric(horizontal: 18, vertical: 16);
+
const AppChoiceTile({
super.key,
required this.size,
@@ -419,7 +423,7 @@ class AppChoiceTile extends StatelessWidget {
backgroundColor: selected
? AppPalette.swarmAccent.withValues(alpha: .16)
: AppSurface.recess,
- padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
+ padding: padding,
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(AppControl.radius),
),
@@ -457,7 +461,7 @@ class AppChoiceTileContent extends StatelessWidget {
@override
Widget build(BuildContext context) => Row(
children: [
- if (leading != null) ...[leading!, const SizedBox(width: 10)],
+ if (leading != null) ...[leading!, const SizedBox(width: 12)],
Expanded(
child: Column(
mainAxisSize: MainAxisSize.min,
@@ -470,14 +474,14 @@ class AppChoiceTileContent extends StatelessWidget {
style: TextStyle(
fontFamily: AppFont.sans,
fontFamilyFallback: AppFont.sansFallback,
- fontSize: 14,
+ fontSize: 16,
height: 1.25,
- fontWeight: FontWeight.w500,
+ fontWeight: AppFont.medium,
color: AppPalette.textPrimary,
),
),
if (detail != null) ...[
- const SizedBox(height: 2),
+ const SizedBox(height: 4),
Text(
detail!,
maxLines: 1,
@@ -485,7 +489,7 @@ class AppChoiceTileContent extends StatelessWidget {
style: TextStyle(
fontFamily: AppFont.sans,
fontFamilyFallback: AppFont.sansFallback,
- fontSize: 12,
+ fontSize: 14,
height: 1.25,
color: AppPalette.textSecondary,
),
@@ -494,8 +498,10 @@ class AppChoiceTileContent extends StatelessWidget {
],
),
),
- const SizedBox(width: 8),
- SizedBox(width: 18, child: trailing),
+ if (trailing != null) ...[
+ const SizedBox(width: 8),
+ SizedBox(width: 18, child: trailing),
+ ],
],
);
}
diff --git a/desktop/lib/shared/widgets/app_select_field.dart b/desktop/lib/shared/widgets/app_select_field.dart
index 10b7f3889..37bf52bb9 100644
--- a/desktop/lib/shared/widgets/app_select_field.dart
+++ b/desktop/lib/shared/widgets/app_select_field.dart
@@ -74,6 +74,7 @@ class AppSelectField<T> extends StatefulWidget {
this.width,
this.menuWidth,
this.height = AppControl.height,
+ this.padding = const EdgeInsets.only(left: 10, right: 8),
this.trigger,
this.focusNode,
this.fillColor,
@@ -94,6 +95,7 @@ class AppSelectField<T> extends StatefulWidget {
/// glance. Never narrower than the field itself.
final double? menuWidth;
final double height;
+ final EdgeInsetsGeometry padding;
/// An alternate compact trigger, such as the agent picker's More button.
/// Selection, keyboard navigation and menu rows remain shared.
@@ -437,7 +439,7 @@ class _AppSelectFieldState<T> extends State<AppSelectField<T>> {
child: AnimatedContainer(
duration: AppMotion.hover,
curve: AppMotion.curve,
- padding: const EdgeInsets.only(left: 10, right: 8),
+ padding: widget.padding,
decoration: BoxDecoration(
color: _hovered || _focused || controller.isOpen
? widget.fillColor == null
diff --git a/desktop/lib/state/swarm_navigation.dart b/desktop/lib/state/swarm_navigation.dart
index c8776ffe6..10756b9c2 100644
--- a/desktop/lib/state/swarm_navigation.dart
+++ b/desktop/lib/state/swarm_navigation.dart
@@ -2,6 +2,7 @@ import 'package:flutter/foundation.dart' show listEquals, setEquals;
import '../core/fuzzy_match.dart';
import '../core/models.dart';
+import '../widgets/engine_identity.dart';
import 'app_state.dart';
import 'pane_arrangement.dart';
import 'session_preview.dart';
@@ -120,7 +121,7 @@ class SwarmNavigationHistory {
pane.session?.engineId,
),
],
- for (final machine in app.machineStates.values)
+ for (final machine in app.machineStates.values) ...[
(
machine.machine,
machine.nodeOnline,
@@ -129,6 +130,8 @@ class SwarmNavigationHistory {
machine.localEndpoint?.agentProjects,
machine.localProjects,
),
+ ...machine.dsh.byId.values,
+ ],
];
if (listEquals(_menuPresentation, presentation)) return _menuDestinations;
_menuPresentation = presentation;
@@ -201,25 +204,33 @@ class SwarmDestination {
enum SwarmSearchAction { open, addHere }
({String text, int? branchOffset}) _harnessDetail(
+ String? type,
AgentProject? project,
String machine,
bool offline,
) {
- final name = project?.name;
+ final prefix = [
+ type,
+ project?.name,
+ ].whereType<String>().where((part) => part.isNotEmpty).join(' · ');
final branch = project?.branch;
return (
text: [
- name,
+ prefix,
branch,
machine,
if (offline) 'Offline',
].whereType<String>().where((part) => part.isNotEmpty).join(' · '),
branchOffset: branch?.isNotEmpty == true
- ? (name?.isNotEmpty == true ? name!.length + 3 : 0)
+ ? (prefix.isNotEmpty ? prefix.length + 3 : 0)
: null,
);
}
+String? _harnessType(MachineState? machine, String? engine) =>
+ (engine == null ? null : machine?.dsh[engine]?.category) ??
+ engineIdentity(engine).category;
+
class SwarmSearchSelection {
const SwarmSearchSelection(
this.destination, [
@@ -257,7 +268,7 @@ List<Object?> _catalogPresentation(
pane.session?.engineId,
),
],
- for (final machine in app.machineStates.values)
+ for (final machine in app.machineStates.values) ...[
(
machine.machine,
machine.nodeOnline,
@@ -267,6 +278,8 @@ List<Object?> _catalogPresentation(
machine.localEndpoint?.agentProjects,
machine.localProjects,
),
+ ...machine.dsh.byId.values,
+ ],
];
/// One catalog for all search entry points. Terminal output leaves these
@@ -284,7 +297,15 @@ class SwarmSearchCatalog {
final presentation = _catalogPresentation(app, projects, recent: recent);
if (listEquals(_presentation, presentation)) return _entries;
_presentation = presentation;
- final entries = swarmDestinations(app, recent: recent);
+ final groups = swarmProjects(app, projects);
+ final entries = swarmDestinations(
+ app,
+ recent: recent,
+ projectGroups: groups,
+ );
+ // A one-harness tab is another view of that harness, not another result.
+ // Its name remains an alias on the harness, including after a tab rename.
+ entries.removeWhere((entry) => entry.isSwarm && entry.members.length == 1);
final agentsById = {
for (final entry in entries)
if (entry.agentId != null) entry.id: entry,
@@ -293,7 +314,6 @@ class SwarmSearchCatalog {
for (final entry in agentsById.values) {
(machineMembers[entry.machineId!] ??= {}).add(entry.id);
}
- final groups = swarmProjects(app, projects);
for (final machine in app.machineStates.values) {
final id = machine.machine.machineId;
final members = machineMembers[id] ?? const <String>{};
@@ -303,7 +323,7 @@ class SwarmSearchCatalog {
title: machine.machine.displayName,
detail: [
'Machine',
- _agentCountLabel(members),
+ _countLabel(members.length, 'harness'),
if (machine.needsLink)
'Link required'
else if (machine.nodeOnline == false)
@@ -329,7 +349,7 @@ class SwarmSearchCatalog {
id: 'project:${group.id}',
projectId: group.id,
title: group.name,
- detail: 'Project · ${_agentCountLabel(members)}',
+ detail: 'Project · ${_countLabel(members.length, 'harness')}',
swarmId: null,
current: false,
members: Set.unmodifiable(members),
@@ -418,6 +438,7 @@ class SwarmLocationCatalog {
final machineLabel = machine?.machine.displayName ?? pane.machineId;
final engine = agent?.identityEngine ?? pane.session?.engineId;
final detail = _harnessDetail(
+ _harnessType(machine, engine),
project,
machineLabel,
machine?.nodeOnline == false,
@@ -694,6 +715,11 @@ String _agentCountLabel(Iterable<String?> ids) {
return '$count ${count == 1 ? 'agent' : 'agents'}';
}
+String _countLabel(int count, String noun) {
+ final plural = noun == 'harness' ? 'harnesses' : '${noun}s';
+ return '$count ${count == 1 ? noun : plural}';
+}
+
String _swarmMachineLabel(AppNotifier app, Iterable<String> machineIds) {
final ids = machineIds.toSet();
if (ids.isEmpty) return '';
@@ -746,11 +772,19 @@ List<SwarmDestination> swarmDestinations(
AppNotifier app, {
List<String> recent = const [],
bool openOnly = false,
+ List<SwarmProjectGroup> projectGroups = const [],
}) {
final owners = <String, List<Swarm>>{};
final agents = <String, (MachineState, Agent)>{};
final result = <SwarmDestination>[];
final recency = {for (var i = 0; i < recent.length; i++) recent[i]: i};
+ final projectsByAgent = <String, Set<String>>{};
+ for (final group in projectGroups) {
+ for (final entry in group.agents) {
+ final id = agentDestinationId(entry.machineId, entry.agent.id);
+ (projectsByAgent[id] ??= {}).add(group.id);
+ }
+ }
for (final machine in app.machineStates.values) {
for (final agent in machine.agents) {
agents[agentDestinationId(machine.machine.machineId, agent.id)] = (
@@ -761,43 +795,48 @@ List<SwarmDestination> swarmDestinations(
}
for (final swarm in app.swarms) {
final context = <String?>[];
- for (final pane in swarm.panes) {
- if (pane.agentId == null) continue;
+ final panes = swarm.panes.where((pane) => pane.agentId != null).toList();
+ final members = <String>{};
+ final projects = <String>{};
+ final machines = <String>{};
+ for (final pane in panes) {
final id = agentDestinationId(pane.machineId, pane.agentId!);
+ members.add(id);
+ machines.add(pane.machineId);
(owners[id] ??= []).add(swarm);
final row = agents[id];
final project = row?.$1.projectOf(row.$2);
+ if (project != null) projects.add(project.identity(pane.machineId));
+ projects.addAll(projectsByAgent[id] ?? const {});
context.addAll([
row?.$1.machine.displayName,
row?.$2.name ?? pane.session?.agentName,
project?.name,
project?.branch,
project?.cwd,
+ _harnessType(row?.$1, row?.$2.identityEngine ?? pane.session?.engineId),
]);
}
result.add(
SwarmDestination(
id: swarmDestinationId(swarm.id),
title: swarm.name,
- engine: swarm.panes.length == 1
+ engine: panes.length == 1
? agents[agentDestinationId(
- swarm.panes.single.machineId,
- swarm.panes.single.agentId ?? '',
+ panes.single.machineId,
+ panes.single.agentId!,
)]
?.$2
- .engine ??
- swarm.panes.single.session?.engineId
+ .identityEngine ??
+ panes.single.session?.engineId
: null,
- machineLabel: _swarmMachineLabel(app, [
- for (final pane in swarm.panes)
- if (pane.agentId != null) pane.machineId,
- ]),
- detail: _agentCountLabel(swarm.panes.map((pane) => pane.agentId)),
- members: {
- for (final pane in swarm.panes)
- if (pane.agentId != null)
- agentDestinationId(pane.machineId, pane.agentId!),
- },
+ machineLabel: _swarmMachineLabel(app, machines),
+ detail: [
+ _countLabel(members.length, 'harness'),
+ if (projects.isNotEmpty) _countLabel(projects.length, 'project'),
+ if (machines.isNotEmpty) _countLabel(machines.length, 'machine'),
+ ].join(' · '),
+ members: members,
swarmId: swarm.id,
current: swarm.id == app.activeSwarmId,
searchFields: context.toSet(),
@@ -835,7 +874,9 @@ List<SwarmDestination> swarmDestinations(
final project = row?.$1.projectOf(row.$2);
final machineName = machine?.machine.displayName ?? machineId;
final engine = row?.$2.identityEngine ?? pane?.session?.engineId;
+ final type = _harnessType(machine, engine);
final detail = _harnessDetail(
+ type,
project,
machineName,
machine?.nodeOnline == false,
@@ -855,6 +896,7 @@ List<SwarmDestination> swarmDestinations(
current:
owner?.id == app.activeSwarmId && pane?.id == app.focusedPaneId,
searchFields: [
+ type,
machineName,
project?.name,
project?.branch,
diff --git a/desktop/lib/state/swarm_search.dart b/desktop/lib/state/swarm_search.dart
index cad1fd1c2..62a520054 100644
--- a/desktop/lib/state/swarm_search.dart
+++ b/desktop/lib/state/swarm_search.dart
@@ -127,7 +127,7 @@ class SwarmSearchController extends ChangeNotifier {
row.agentId == null &&
split == null &&
_missingIds(row).length > 1
- ? 'Open ${_missingIds(row).length} Agents'
+ ? 'Open ${_missingIds(row).length} Harnesses'
: primaryAction
: row == null
? 'Go to'
@@ -137,8 +137,8 @@ class SwarmSearchController extends ChangeNotifier {
split != null && !app.isPaneSplitCurrent(split!)
? 'The layout changed. Split the pane again.'
: selected != null && alreadyHere(selected!)
- ? 'This agent is already open here.'
- : 'No room for another agent.';
+ ? 'This harness is already open here.'
+ : 'No room for another harness.';
void _refresh() {
final next = navigating
diff --git a/desktop/lib/widgets/agent_picker.dart b/desktop/lib/widgets/agent_picker.dart
index cbe3f8b95..dad63ca36 100644
--- a/desktop/lib/widgets/agent_picker.dart
+++ b/desktop/lib/widgets/agent_picker.dart
@@ -44,7 +44,10 @@ class AgentPicker extends StatelessWidget {
label: option.value == 'claude' ? 'Claude Code' : option.label,
note: option.note,
detail: option.detail,
- leading: () => EngineMark(engine: option.value, size: 18),
+ leading: () => EngineMark(
+ engine: option.value,
+ size: tileSize == null ? 18 : 22,
+ ),
trailing: option.trailing,
),
],
@@ -54,6 +57,6 @@ class AgentPicker extends StatelessWidget {
optionKey: (id) => ValueKey('new-agent-quick-$id'),
moreKey: const Key('new-agent-engine-field'),
moreLabel: 'More agents',
- moreLeading: const Icon(LucideIcons.layoutGrid, size: 18),
+ moreLeading: Icon(LucideIcons.layoutGrid, size: tileSize == null ? 18 : 22),
);
}
diff --git a/desktop/lib/widgets/new_agent_dialog.dart b/desktop/lib/widgets/new_agent_dialog.dart
index 115483d13..74d947e90 100644
--- a/desktop/lib/widgets/new_agent_dialog.dart
+++ b/desktop/lib/widgets/new_agent_dialog.dart
@@ -24,6 +24,7 @@ import 'codex_profile_field.dart';
import 'agent_picker.dart';
import 'remote_folder_picker.dart';
import 'new_agent_project_picker.dart';
+import 'new_harness_help.dart';
import 'dsh_install_panel.dart';
/// Mirrors the harness CLI's `BYPASS_PERMISSION_FLAGS`
@@ -524,6 +525,8 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
}
Widget _buildDialog(BuildContext context) {
+ final edgePadding = MediaQuery.sizeOf(context).width < 700 ? 24.0 : 36.0;
+ final compactHeight = MediaQuery.sizeOf(context).height < 800;
final bypassFlag = kEngineBypassPermissionFlag[_baseEngine(_engine)];
final canCreate =
(_preparedFolder != null ||
@@ -544,7 +547,9 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
},
},
child: AlertDialog(
- constraints: const BoxConstraints.tightFor(width: _dialogWidth + 56),
+ constraints: BoxConstraints.tightFor(
+ width: _dialogWidth + edgePadding * 2,
+ ),
backgroundColor: grid.AppPalette.swarmField,
surfaceTintColor: Colors.transparent,
shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)),
@@ -554,23 +559,36 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
null => 'New Harness',
}),
titleTextStyle: Theme.of(context).textTheme.headlineSmall?.copyWith(
- fontSize: 24,
+ fontSize: 28,
+ height: 1.2,
fontWeight: grid.AppFont.semibold,
color: grid.AppPalette.textPrimary,
),
- titlePadding: const EdgeInsets.fromLTRB(28, 28, 28, 0),
- contentPadding: const EdgeInsets.fromLTRB(28, 24, 28, 16),
- actionsPadding: const EdgeInsets.fromLTRB(28, 0, 28, 24),
+ titlePadding: EdgeInsets.fromLTRB(
+ edgePadding,
+ compactHeight ? 24 : 32,
+ edgePadding,
+ 0,
+ ),
+ contentPadding: EdgeInsets.fromLTRB(
+ edgePadding,
+ compactHeight ? 24 : 32,
+ edgePadding,
+ 40,
+ ),
+ actionsPadding: EdgeInsets.fromLTRB(
+ edgePadding,
+ 0,
+ edgePadding,
+ compactHeight ? 24 : 28,
+ ),
actionsOverflowButtonSpacing: 8,
content: SizedBox(
width: _dialogWidth,
child: ConstrainedBox(
- constraints: BoxConstraints(
- maxHeight: math.min(
- 650,
- math.max(220, MediaQuery.sizeOf(context).height - 230),
- ),
- ),
+ // AlertDialog gives the form the space left by its title and
+ // footer, including when the footer wraps or text is enlarged.
+ constraints: const BoxConstraints(maxHeight: 840),
child: Scrollbar(
controller: _choicesScroll,
thickness: 4,
@@ -585,7 +603,12 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
absorbing: _choicesLocked,
child: ExcludeFocus(
excluding: _choicesLocked,
- child: _choices(),
+ // Clipped choices can overlap the fixed footer in
+ // screen coordinates. Keep Tab in the form's order.
+ child: FocusTraversalGroup(
+ policy: WidgetOrderTraversalPolicy(),
+ child: _choices(),
+ ),
),
),
// Under everything chosen, and OUTSIDE the AbsorbPointer
@@ -757,36 +780,76 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
);
}
- Widget _sectionLabel(String label) => Padding(
- padding: const EdgeInsets.only(bottom: 10),
- child: Text(
- label,
- style: TextStyle(
- fontSize: 14,
- fontWeight: FontWeight.w500,
- color: grid.AppPalette.textSecondary,
- ),
+ Widget _sectionHeader(
+ String label,
+ String prompt,
+ HarnessHelpTopic helpTopic, {
+ required bool compactHeight,
+ }) => Padding(
+ padding: EdgeInsets.only(bottom: compactHeight ? 12 : 16),
+ child: OverflowBar(
+ alignment: MainAxisAlignment.spaceBetween,
+ overflowAlignment: OverflowBarAlignment.end,
+ spacing: 20,
+ overflowSpacing: 4,
+ children: [
+ Semantics(
+ header: true,
+ child: Text.rich(
+ TextSpan(
+ children: [
+ TextSpan(
+ text: '$label.',
+ style: TextStyle(
+ fontWeight: grid.AppFont.semibold,
+ color: grid.AppPalette.textPrimary,
+ ),
+ ),
+ TextSpan(text: ' $prompt'),
+ ],
+ ),
+ style: TextStyle(
+ fontSize: 20,
+ height: 1.35,
+ fontWeight: grid.AppFont.regular,
+ color: grid.AppPalette.textSecondary,
+ ),
+ ),
+ ),
+ HarnessHelpLink(topic: helpTopic),
+ ],
),
);
Widget _choices() => LayoutBuilder(
builder: (context, constraints) {
final scaler = MediaQuery.textScalerOf(context);
- final minimumTileWidth = 180 * math.min(1.3, scaler.scale(14) / 14);
- final columns = constraints.maxWidth >= minimumTileWidth * 4 + 30
+ final compactHeight = MediaQuery.sizeOf(context).height < 800;
+ final sectionGap = compactHeight ? 24.0 : 32.0;
+ final minimumTileWidth = 172 * math.min(1.3, scaler.scale(16) / 16);
+ final columns =
+ constraints.maxWidth >= minimumTileWidth * 4 + AppChoiceTile.gap * 3
? 4
- : constraints.maxWidth >= minimumTileWidth * 2 + 10
+ : constraints.maxWidth >= minimumTileWidth * 2 + AppChoiceTile.gap
? 2
: 1;
final tileSize = Size(
- (constraints.maxWidth - 10 * (columns - 1)) / columns,
- math.max(76, scaler.scale(14) * 2.5 + scaler.scale(12) * 1.25 + 24),
+ (constraints.maxWidth - AppChoiceTile.gap * (columns - 1)) / columns,
+ math.max(
+ compactHeight ? 96 : 100,
+ scaler.scale(16) * 2.5 + scaler.scale(14) * 1.25 + 38,
+ ),
);
return Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
children: [
- _sectionLabel('Choose an agent'),
+ _sectionHeader(
+ 'Agent',
+ 'Choose who you’ll work with.',
+ HarnessHelpTopic.agent,
+ compactHeight: compactHeight,
+ ),
AgentPicker(
compact: true,
tileSize: tileSize,
@@ -862,11 +925,21 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
],
),
],
- const SizedBox(height: _gapField),
- _sectionLabel('Where will this agent run?'),
+ SizedBox(height: sectionGap),
+ _sectionHeader(
+ 'Machine',
+ 'Where would you like your agent to run?',
+ HarnessHelpTopic.machine,
+ compactHeight: compactHeight,
+ ),
_machineOptions(tileSize),
- const SizedBox(height: _gapField),
- _sectionLabel('Which project will this agent work in?'),
+ SizedBox(height: sectionGap),
+ _sectionHeader(
+ 'Project',
+ 'Start something new or choose an existing project.',
+ HarnessHelpTopic.project,
+ compactHeight: compactHeight,
+ ),
PageStorage(
bucket: _projectChoices,
child: NewAgentProjectPicker(
@@ -1010,7 +1083,7 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
value: _machineId,
moreKey: const Key('new-agent-machine-more'),
moreLabel: 'More machines',
- moreLeading: const Icon(LucideIcons.monitor, size: 18),
+ moreLeading: const Icon(LucideIcons.monitor, size: 22),
optionKey: (id) => ValueKey('new-agent-machine-$id'),
showDetails: true,
compact: true,
@@ -1024,14 +1097,14 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
SelectOption(
value: machine.machine.machineId,
label: machine.machine.displayName,
- detail: machine.isLocalMachine ? 'This machine' : null,
+ detail: machine.isLocalMachine ? 'This computer' : 'Remote',
leading: () => Icon(
_machineOnline(machine)
? (machine.isLocalMachine
? LucideIcons.laptop
: LucideIcons.monitor)
: LucideIcons.monitorOff,
- size: 18,
+ size: 22,
color: _machineOnline(machine)
? grid.AppPalette.textPrimary
: grid.AppPalette.textFaint,
@@ -1065,9 +1138,6 @@ const double _dialogWidth = 1080;
/// Blocks inside one card: the command, the facts, the reason.
const double _gapBlock = 12;
-/// One field and the next, down the choices column.
-const double _gapField = 24;
-
class _BypassCheck extends StatelessWidget {
const _BypassCheck({
required this.value,
diff --git a/desktop/lib/widgets/new_agent_project_picker.dart b/desktop/lib/widgets/new_agent_project_picker.dart
index 9beb2c2ba..4eafd90e0 100644
--- a/desktop/lib/widgets/new_agent_project_picker.dart
+++ b/desktop/lib/widgets/new_agent_project_picker.dart
@@ -202,15 +202,15 @@ class _NewAgentProjectPickerState extends State<NewAgentProjectPicker> {
mainAxisSize: MainAxisSize.min,
children: [
Wrap(
- spacing: 10,
- runSpacing: 10,
+ spacing: AppChoiceTile.gap,
+ runSpacing: AppChoiceTile.gap,
children: [
AppChoiceTile(
key: const Key('new-agent-folder-newProject'),
size: widget.tileSize,
focusNode: widget.focusNode,
label: 'New project',
- leading: const Icon(LucideIcons.folderPlus, size: 18),
+ leading: const Icon(LucideIcons.folderPlus, size: 22),
selected: _source == _ProjectSource.newProject,
onPressed: widget.locked
? null
@@ -220,11 +220,11 @@ class _NewAgentProjectPickerState extends State<NewAgentProjectPicker> {
key: const Key('new-agent-project-browse'),
size: widget.tileSize,
focusNode: _localFocus,
- label: 'Local',
+ label: 'Existing folder',
detail: _source == _ProjectSource.local && _folder != null
? p.basename(_folder!)
: null,
- leading: const Icon(LucideIcons.folderOpen, size: 18),
+ leading: const Icon(LucideIcons.folderOpen, size: 22),
selected: _source == _ProjectSource.local,
onPressed: widget.locked || _browsing ? null : _browse,
),
@@ -233,7 +233,7 @@ class _NewAgentProjectPickerState extends State<NewAgentProjectPicker> {
size: widget.tileSize,
label: 'Git',
detail: _repository?.name,
- leading: const Icon(LucideIcons.gitBranch, size: 18),
+ leading: const Icon(LucideIcons.gitBranch, size: 22),
selected: _source == _ProjectSource.git,
onPressed: widget.locked ? null : _git,
),
@@ -246,6 +246,7 @@ class _NewAgentProjectPickerState extends State<NewAgentProjectPicker> {
options: recent,
width: widget.tileSize.width,
height: widget.tileSize.height,
+ padding: AppChoiceTile.padding,
selected: selectedRecent,
fillColor: selectedRecent
? grid.AppPalette.swarmAccent.withValues(alpha: .16)
@@ -258,7 +259,7 @@ class _NewAgentProjectPickerState extends State<NewAgentProjectPicker> {
detail: selectedRecent && _folder != null
? p.basename(_folder!)
: null,
- leading: const Icon(LucideIcons.history, size: 18),
+ leading: const Icon(LucideIcons.history, size: 22),
trailing: const Icon(Icons.keyboard_arrow_down, size: 18),
),
),
diff --git a/desktop/lib/widgets/new_harness_help.dart b/desktop/lib/widgets/new_harness_help.dart
new file mode 100644
index 000000000..0a6349193
--- /dev/null
+++ b/desktop/lib/widgets/new_harness_help.dart
@@ -0,0 +1,349 @@
+import 'package:flutter/material.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
+
+import '../shared/theme/app_theme.dart';
+import '../shared/widgets/app_dialog.dart';
+import 'engine_identity.dart';
+
+enum HarnessHelpTopic { agent, machine, project }
+
+/// Optional guidance beside the choices it explains. A separate route keeps
+/// the form, its scroll position and its keyboard shortcuts underneath it.
+class HarnessHelpLink extends StatefulWidget {
+ const HarnessHelpLink({super.key, required this.topic});
+
+ final HarnessHelpTopic topic;
+
+ @override
+ State<HarnessHelpLink> createState() => _HarnessHelpLinkState();
+}
+
+class _HarnessHelpLinkState extends State<HarnessHelpLink> {
+ final _focus = FocusNode();
+
+ @override
+ void dispose() {
+ _focus.dispose();
+ super.dispose();
+ }
+
+ Future<void> _open() async {
+ await showAppDialog<void>(
+ context: context,
+ builder: (_) => _HarnessHelpDialog(topic: widget.topic),
+ );
+ if (mounted) _focus.requestFocus();
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ AppTheme.watch(context);
+ final label = switch (widget.topic) {
+ HarnessHelpTopic.agent => 'Need help choosing?',
+ HarnessHelpTopic.machine => 'Local or remote?',
+ HarnessHelpTopic.project => 'Where to start?',
+ };
+ return TextButton(
+ key: ValueKey('harness-help-${widget.topic.name}'),
+ focusNode: _focus,
+ onPressed: _open,
+ style:
+ TextButton.styleFrom(
+ foregroundColor: AppPalette.textSecondary,
+ minimumSize: const Size(0, 32),
+ padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 6),
+ textStyle: TextStyle(
+ fontFamily: AppFont.sans,
+ fontFamilyFallback: AppFont.sansFallback,
+ fontSize: 14,
+ fontWeight: FontWeight.w400,
+ height: 1.4,
+ ),
+ side: BorderSide.none,
+ shape: RoundedRectangleBorder(
+ borderRadius: BorderRadius.circular(6),
+ ),
+ ).copyWith(
+ // Keep hover and keyboard focus visible without making guidance
+ // look like another selected agent, machine or project.
+ overlayColor: WidgetStateProperty.resolveWith(
+ (states) => states.contains(WidgetState.pressed)
+ ? AppSurface.selectedFill
+ : states.contains(WidgetState.hovered) ||
+ states.contains(WidgetState.focused)
+ ? AppSurface.hoverFill
+ : Colors.transparent,
+ ),
+ ),
+ child: Text(label),
+ );
+ }
+}
+
+class _HarnessHelpDialog extends StatefulWidget {
+ const _HarnessHelpDialog({required this.topic});
+
+ final HarnessHelpTopic topic;
+
+ @override
+ State<_HarnessHelpDialog> createState() => _HarnessHelpDialogState();
+}
+
+class _HarnessHelpDialogState extends State<_HarnessHelpDialog> {
+ final _scroll = ScrollController();
+
+ @override
+ void dispose() {
+ _scroll.dispose();
+ super.dispose();
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ AppTheme.watch(context);
+ final compact = MediaQuery.sizeOf(context).width < 700;
+ final (title, intro) = switch (widget.topic) {
+ HarnessHelpTopic.agent => (
+ 'What would you like to make?',
+ 'Choose an agent for the kind of work you have in mind. '
+ 'You’ll work with it inside your new harness.',
+ ),
+ HarnessHelpTopic.machine => (
+ 'Where would you like to work?',
+ 'Your agent runs its tools and works with files on the machine you choose.',
+ ),
+ HarnessHelpTopic.project => (
+ 'Start with a place for your work.',
+ 'A project is the folder your agent works in. '
+ 'All of these options use the machine you’ve selected.',
+ ),
+ };
+ return Dialog(
+ key: ValueKey('harness-help-guide-${widget.topic.name}'),
+ backgroundColor: AppPalette.swarmField,
+ surfaceTintColor: Colors.transparent,
+ insetPadding: EdgeInsets.all(compact ? 16 : 24),
+ constraints: const BoxConstraints(maxWidth: 800, maxHeight: 920),
+ shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)),
+ clipBehavior: Clip.antiAlias,
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ Padding(
+ padding: const EdgeInsets.fromLTRB(16, 16, 16, 0),
+ child: Align(
+ alignment: Alignment.centerRight,
+ child: IconButton(
+ key: const Key('harness-help-close'),
+ autofocus: true,
+ tooltip: 'Close guide',
+ onPressed: () => Navigator.of(context).pop(),
+ style: IconButton.styleFrom(
+ backgroundColor: AppSurface.recess,
+ foregroundColor: AppPalette.textSecondary,
+ minimumSize: const Size(40, 40),
+ shape: const CircleBorder(),
+ ),
+ icon: const Icon(LucideIcons.x, size: 22),
+ ),
+ ),
+ ),
+ Flexible(
+ child: Scrollbar(
+ controller: _scroll,
+ child: SingleChildScrollView(
+ controller: _scroll,
+ padding: EdgeInsets.fromLTRB(
+ compact ? 24 : 48,
+ 16,
+ compact ? 24 : 48,
+ compact ? 28 : 48,
+ ),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Semantics(
+ header: true,
+ child: Text(
+ title,
+ style: TextStyle(
+ fontSize: compact ? 28 : 32,
+ height: 1.2,
+ fontWeight: AppFont.semibold,
+ color: AppPalette.textPrimary,
+ ),
+ ),
+ ),
+ const SizedBox(height: 20),
+ Text(
+ intro,
+ style: TextStyle(
+ fontSize: 16,
+ height: 1.5,
+ color: AppPalette.textSecondary,
+ ),
+ ),
+ const SizedBox(height: 32),
+ ..._sections(),
+ ],
+ ),
+ ),
+ ),
+ ),
+ ],
+ ),
+ );
+ }
+
+ List<Widget> _sections() => switch (widget.topic) {
+ HarnessHelpTopic.agent => const [
+ _HelpOption(
+ leading: EngineMark(engine: 'codex', size: 32),
+ title: 'Code',
+ description:
+ 'Build apps, fix bugs, and work with existing code. '
+ 'Start with an agent you already use, such as Codex, Claude Code, or OpenCode.',
+ ),
+ _HelpOption(
+ leading: EngineMark(engine: 'autonomous/solid', size: 32),
+ title: 'Solid · 3D design',
+ description:
+ 'Design parts and objects with a live 3D view. '
+ 'Use it for prototypes, enclosures, and parts you want to 3D print.',
+ ),
+ _HelpOption(
+ leading: EngineMark(engine: 'autonomous/copper', size: 32),
+ title: 'Copper · PCB',
+ description:
+ 'Design circuit boards with a live board view. '
+ 'Use it for electronics projects, PCB layouts, and preparing a board for manufacturing.',
+ ),
+ _HelpOption(
+ leading: EngineMark(engine: 'autonomous/marp', size: 32),
+ title: 'Marp · Slides',
+ description:
+ 'Create presentations with a live slide preview. '
+ 'Use it for talks, project updates, and decks you want to export or share.',
+ last: true,
+ ),
+ ],
+ HarnessHelpTopic.machine => const [
+ _HelpOption(
+ leading: Icon(LucideIcons.laptop, size: 28),
+ title: 'This computer',
+ description:
+ 'A good place to start. Work with the files and tools on the computer '
+ 'you’re using, without setting up another machine.',
+ ),
+ _HelpOption(
+ leading: Icon(LucideIcons.monitor, size: 28),
+ title: 'Remote machine',
+ description:
+ 'Choose another linked computer when your project or tools are there. '
+ 'The work happens on that machine while you control it from here. '
+ 'Keep both computers online while you work.',
+ last: true,
+ ),
+ ],
+ HarnessHelpTopic.project => const [
+ _HelpOption(
+ leading: Icon(LucideIcons.folderPlus, size: 28),
+ title: 'New project',
+ description: 'Start fresh. Harness creates a new folder on your selected machine for your work.',
+ ),
+ _HelpOption(
+ leading: Icon(LucideIcons.folderOpen, size: 28),
+ title: 'Existing folder',
+ description:
+ 'Choose a folder that’s already on your selected machine. '
+ 'Your new harness will work with the files in that folder.',
+ ),
+ _HelpOption(
+ leading: Icon(LucideIcons.gitBranch, size: 28),
+ title: 'Git',
+ description:
+ 'Bring a project from GitHub. Paste a repository link and Harness '
+ 'clones it onto your selected machine before starting.',
+ ),
+ _HelpOption(
+ leading: Icon(LucideIcons.history, size: 28),
+ title: 'Recent',
+ description:
+ 'Quickly choose a project folder you’ve used on this machine before. '
+ 'This starts a new harness in that folder.',
+ last: true,
+ ),
+ ],
+ };
+}
+
+class _HelpOption extends StatelessWidget {
+ const _HelpOption({
+ required this.leading,
+ required this.title,
+ required this.description,
+ this.last = false,
+ });
+
+ final Widget leading;
+ final String title, description;
+ final bool last;
+
+ @override
+ Widget build(BuildContext context) {
+ AppTheme.watch(context);
+ return Padding(
+ padding: EdgeInsets.only(bottom: last ? 0 : 24),
+ child: Column(
+ children: [
+ Row(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ SizedBox(
+ width: 36,
+ child: IconTheme(
+ data: IconThemeData(color: AppPalette.textSecondary),
+ child: leading,
+ ),
+ ),
+ const SizedBox(width: 20),
+ Expanded(
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(
+ title,
+ style: TextStyle(
+ fontSize: 18,
+ height: 1.4,
+ fontWeight: AppFont.semibold,
+ color: AppPalette.textPrimary,
+ ),
+ ),
+ const SizedBox(height: 8),
+ Text(
+ description,
+ style: TextStyle(
+ fontSize: 16,
+ height: 1.5,
+ color: AppPalette.textSecondary,
+ ),
+ ),
+ ],
+ ),
+ ),
+ ],
+ ),
+ if (!last) ...[
+ const SizedBox(height: 24),
+ Divider(
+ height: 1,
+ color: AppPalette.textFaint.withValues(alpha: .25),
+ ),
+ ],
+ ],
+ ),
+ );
+ }
+}
diff --git a/desktop/lib/widgets/swarm_switcher.dart b/desktop/lib/widgets/swarm_switcher.dart
index b9e9fda8f..6ab6a64a2 100644
--- a/desktop/lib/widgets/swarm_switcher.dart
+++ b/desktop/lib/widgets/swarm_switcher.dart
@@ -409,7 +409,7 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
search.isCommandMode
? 'No matching commands'
: search.adding && search.query.isEmpty
- ? 'Create a new agent to start fresh.'
+ ? 'Create a new harness to start fresh.'
: search.adding
? 'No matching harnesses'
: 'No matching results',
@@ -583,8 +583,8 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
: selected!.isGroup &&
selected.members.length >
AppNotifier.maxPanes
- ? 'Open up to ${AppNotifier.maxPanes} agents at once'
- : 'No room to open this ${selected.isSwarm || selected.isGroup ? 'group' : 'agent'}',
+ ? 'Open up to ${AppNotifier.maxPanes} harnesses at once'
+ : 'No room to open this ${selected.isSwarm || selected.isGroup ? 'group' : 'harness'}',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: const TextStyle(
diff --git a/desktop/test/first_workspace_test.dart b/desktop/test/first_workspace_test.dart
index f15e64f5e..258d94a4a 100644
--- a/desktop/test/first_workspace_test.dart
+++ b/desktop/test/first_workspace_test.dart
@@ -28,7 +28,7 @@ final _localProject = find.byKey(const Key('new-agent-project-browse'));
final _newProject = find.byKey(const Key('new-agent-folder-newProject'));
FocusNode _localFocus(WidgetTester tester) =>
- Focus.of(tester.element(find.text('Local')));
+ Focus.of(tester.element(find.text('Existing folder')));
Future<void> _browseLocal(WidgetTester tester) async {
await tester.ensureVisible(_localProject);
@@ -164,7 +164,8 @@ void main() {
.focusNode!;
Future<void> tabTo(FocusNode node, {bool back = false}) async {
if (back) await tester.sendKeyDownEvent(LogicalKeyboardKey.shiftLeft);
- for (var i = 0; i < 12 && !node.hasPrimaryFocus; i++) {
+ // Include the optional help buttons in the dialog's tab order.
+ for (var i = 0; i < 20 && !node.hasPrimaryFocus; i++) {
await tester.sendKeyEvent(LogicalKeyboardKey.tab);
await tester.pump();
}
@@ -346,11 +347,13 @@ void main() {
await tester.tap(_newHarness);
await tester.pump();
expect(picker.opened, 0);
- await tester.tap(_localProject);
+ await _browseLocal(tester);
await tester.pump();
expect(picker.opened, 1);
expect(find.text('my-project'), findsOneWidget);
- await tester.tap(find.byKey(const ValueKey('new-agent-machine-m')));
+ final localMachine = find.byKey(const ValueKey('new-agent-machine-m'));
+ await tester.ensureVisible(localMachine);
+ await tester.tap(localMachine);
await tester.pump();
expect(find.text('my-project'), findsOneWidget);
expect(
@@ -369,7 +372,7 @@ void main() {
.options
.last
.detail,
- isNull,
+ 'Remote',
);
expect(app.launches, isEmpty);
await tester.sendKeyEvent(LogicalKeyboardKey.escape);
@@ -524,8 +527,8 @@ void main() {
);
expect(machineField.value, 'm');
expect(machineField.options.map((option) => option.detail), [
- 'This machine',
- null,
+ 'This computer',
+ 'Remote',
]);
expect(machineField.options.map((option) => option.label), [
'My computer',
@@ -637,8 +640,7 @@ void main() {
addTearDown(() => FileSelectorPlatform.instance = oldPicker);
await mount(tester, app);
await chord(tester, LogicalKeyboardKey.keyN);
- final field = _localProject;
- await tester.tap(field);
+ await _browseLocal(tester);
await tester.pump();
await tester.pump();
expect(find.text('my-project'), findsOneWidget);
@@ -699,15 +701,19 @@ void main() {
expect(engine.value, 'codex');
expect(find.byKey(const Key('new-agent-machine-field')), findsOneWidget);
expect(
- tester.getTopLeft(find.text('Choose an agent')).dy,
+ tester.getTopLeft(find.text('Agent. Choose who you’ll work with.')).dy,
lessThan(
tester
- .getTopLeft(find.text('Which project will this agent work in?'))
+ .getTopLeft(
+ find.text(
+ 'Project. Start something new or choose an existing project.',
+ ),
+ )
.dy,
),
);
expect(picker.opened, 0);
- await tester.tap(_localProject);
+ await _browseLocal(tester);
await tester.pump();
expect(picker.opened, 1);
expect(app.probes, 1);
diff --git a/desktop/test/new_agent_choices_layout_test.dart b/desktop/test/new_agent_choices_layout_test.dart
index a27772284..907bb3e95 100644
--- a/desktop/test/new_agent_choices_layout_test.dart
+++ b/desktop/test/new_agent_choices_layout_test.dart
@@ -9,8 +9,10 @@ import 'package:harness/auth/auth_session.dart';
import 'package:harness/core/config.dart';
import 'package:harness/core/engine_availability.dart';
import 'package:harness/core/models.dart';
+import 'package:harness/core/project_folder.dart';
import 'package:harness/shared/theme/app_theme.dart' as grid;
import 'package:harness/state/app_state.dart';
+import 'package:harness/state/pane_arrangement.dart';
import 'package:harness/widgets/new_agent_dialog.dart';
import 'package:harness/shared/widgets/app_choice_picker.dart';
@@ -48,6 +50,25 @@ class _ChoicesApp extends AppNotifier {
}
}
+ int createCalls = 0;
+
+ @override
+ Future<String?> createAgent(
+ String machineId, {
+ required String engine,
+ required String folder,
+ ProjectFolderRequest? projectFolder,
+ bool bypassPermission = false,
+ String? codexHome,
+ String? swarmId,
+ PaneSplitRequest? split,
+ String? dsh,
+ AgentCreationAttempt? attempt,
+ }) async {
+ createCalls++;
+ return null;
+ }
+
@override
Future<Map<String, dynamic>> readProjectPreview(
String machineId,
@@ -94,6 +115,7 @@ void main() {
for (final (size, scale) in [
(const Size(1280, 1000), 1.0),
+ (const Size(1024, 768), 1.0),
(const Size(900, 720), 1.0),
(const Size(880, 560), 1.0),
(const Size(600, 700), 2.0),
@@ -149,7 +171,14 @@ void main() {
final output = Platform.environment['HARNESS_CHOICES_CAPTURE_DIR'];
if (output == null) return;
await tester.runAsync(() async {
- for (final asset in ['codex.png', 'cursor.png', 'kilo.png']) {
+ for (final asset in [
+ 'codex.png',
+ 'cursor.png',
+ 'kilo.png',
+ 'solid.png',
+ 'copper.png',
+ 'marp.png',
+ ]) {
await precacheImage(
AssetImage('assets/engine-icons/$asset'),
boundaryKey.currentContext!,
@@ -197,7 +226,27 @@ void main() {
}
expectUniformTiles();
- expect(find.text('This machine'), findsOneWidget);
+ if (size.width >= 900 && size.height >= 720 && scale == 1) {
+ // The common desktop sizes should show every choice before scrolling.
+ final form = find.ancestor(
+ of: find.byKey(const ValueKey('new-agent-quick-codex')),
+ matching: find.byType(SingleChildScrollView),
+ );
+ final visible = tester.getRect(form);
+ for (final key in [
+ 'new-agent-quick-codex',
+ 'new-agent-machine-local',
+ 'new-agent-folder-newProject',
+ 'new-agent-project-recent',
+ ]) {
+ final choice = find.byKey(ValueKey(key));
+ final bounds = tester.getRect(choice);
+ expect(bounds.top, greaterThanOrEqualTo(visible.top));
+ expect(bounds.bottom, lessThanOrEqualTo(visible.bottom));
+ expect(choice.hitTestable(), findsOneWidget);
+ }
+ }
+ expect(find.text('This computer'), findsOneWidget);
expect(find.text('Cancel'), findsNothing);
expect(find.widgetWithText(FilledButton, 'Create'), findsOneWidget);
final advanced = find.byKey(const Key('new-agent-advanced'));
@@ -243,6 +292,75 @@ void main() {
await capture('repository');
await tester.testTextInput.receiveAction(TextInputAction.done);
await tester.pumpAndSettle();
+
+ // Help is a separate route: it must keep the current choices and scroll
+ // position, contain keyboard shortcuts, and return focus to its trigger.
+ for (final (topic, lastTitle) in [
+ ('agent', 'Marp · Slides'),
+ ('machine', 'Remote machine'),
+ ('project', 'Recent'),
+ ]) {
+ final help = find.byKey(ValueKey('harness-help-$topic'));
+ await tester.ensureVisible(help);
+ await tester.pumpAndSettle();
+ final position = Scrollable.of(tester.element(help)).position;
+ final scrollBefore = position.pixels;
+ await tester.tap(help);
+ await tester.pumpAndSettle();
+ final guide = find.byKey(ValueKey('harness-help-guide-$topic'));
+ expect(guide, findsOneWidget);
+ await capture('help-$topic');
+ for (final modifier in [
+ LogicalKeyboardKey.metaLeft,
+ LogicalKeyboardKey.controlLeft,
+ ]) {
+ await tester.sendKeyDownEvent(modifier);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.sendKeyUpEvent(modifier);
+ await tester.pumpAndSettle();
+ expect(guide, findsOneWidget);
+ expect(app.createCalls, 0);
+ }
+ final lastSection = find.descendant(
+ of: guide,
+ matching: find.text(lastTitle),
+ );
+ await tester.ensureVisible(lastSection);
+ await tester.pumpAndSettle();
+ expect(tester.getRect(lastSection).bottom, lessThan(size.height));
+ expect(tester.takeException(), isNull);
+ if (topic == 'agent') {
+ await tester.sendKeyEvent(LogicalKeyboardKey.escape);
+ } else if (topic == 'machine') {
+ await tester.tap(find.byKey(const Key('harness-help-close')));
+ } else {
+ await tester.tapAt(const Offset(2, 2));
+ }
+ await tester.pumpAndSettle();
+ expect(guide, findsNothing);
+ expect(position.pixels, closeTo(scrollBefore, 1));
+ expect(tester.widget<TextButton>(help).focusNode!.hasFocus, isTrue);
+ await capture('help-$topic-closed');
+ final selected = tester.widget<AppChoiceTile>(git);
+ expect(selected.selected, isTrue);
+ expect(selected.detail, 'repo');
+ expect(
+ tester
+ .widget<AppChoiceTile>(
+ find.byKey(const ValueKey('new-agent-quick-codex')),
+ )
+ .selected,
+ isTrue,
+ );
+ expect(
+ tester
+ .widget<AppChoicePicker<String>>(
+ find.byKey(const Key('new-agent-machine-field')),
+ )
+ .value,
+ 'local',
+ );
+ }
final moreMachines = find.byKey(const Key('new-agent-machine-more'));
await tester.ensureVisible(moreMachines);
await tester.tap(moreMachines);
diff --git a/desktop/test/new_agent_codex_profile_test.dart b/desktop/test/new_agent_codex_profile_test.dart
index 05dc1775c..8074887c0 100644
--- a/desktop/test/new_agent_codex_profile_test.dart
+++ b/desktop/test/new_agent_codex_profile_test.dart
@@ -307,7 +307,7 @@ void main() {
find.byKey(const Key('new-agent-machine-field')),
);
expect(machineField.options.single.label, 'This Mac');
- expect(machineField.options.single.detail, isNull);
+ expect(machineField.options.single.detail, 'Remote');
expect(find.widgetWithText(FilledButton, 'Create'), findsOneWidget);
expect(find.byKey(const Key('new-agent-project-recent')), findsOneWidget);
expect(
diff --git a/desktop/test/new_agent_dsh_test.dart b/desktop/test/new_agent_dsh_test.dart
index 5c0ac345d..3d523bac2 100644
--- a/desktop/test/new_agent_dsh_test.dart
+++ b/desktop/test/new_agent_dsh_test.dart
@@ -172,7 +172,11 @@ void main() {
await tester.pumpAndSettle();
// A new project needs no folder: the daemon prepares one. That keeps the
// native folder panel out of these tests, which are about the harness.
- await tester.tap(find.byKey(const ValueKey('new-agent-folder-newProject')));
+ final newProject = find.byKey(
+ const ValueKey('new-agent-folder-newProject'),
+ );
+ await tester.ensureVisible(newProject);
+ await tester.tap(newProject);
await tester.pumpAndSettle();
return notifier;
}
diff --git a/desktop/test/new_agent_engine_check_test.dart b/desktop/test/new_agent_engine_check_test.dart
index 6b9bb59c8..095565ec6 100644
--- a/desktop/test/new_agent_engine_check_test.dart
+++ b/desktop/test/new_agent_engine_check_test.dart
@@ -222,10 +222,15 @@ void main() {
app: app,
);
final pending = app.pending['machine-1'] = Completer<void>();
+ await tester.ensureVisible(find.byKey(const Key('new-agent-retry-check')));
await tester.tap(find.byKey(const Key('new-agent-retry-check')));
await tester.pump();
await tester.pump();
- await tester.tap(find.byKey(const ValueKey('new-agent-machine-machine-2')));
+ final otherMachine = find.byKey(
+ const ValueKey('new-agent-machine-machine-2'),
+ );
+ await tester.ensureVisible(otherMachine);
+ await tester.tap(otherMachine);
await tester.pumpAndSettle();
await tester.ensureVisible(
find.byKey(const ValueKey('new-agent-quick-codex')),
diff --git a/desktop/test/swarm_navigation_test.dart b/desktop/test/swarm_navigation_test.dart
index f74bd7acd..dda0ce368 100644
--- a/desktop/test/swarm_navigation_test.dart
+++ b/desktop/test/swarm_navigation_test.dart
@@ -97,7 +97,7 @@ void main() {
final catalog = swarmDestinations(app);
expect(
catalog.singleWhere((row) => row.agentId == 'auth').detail,
- 'Payments · fix-login · Test host · Offline',
+ 'Code · Payments · fix-login · Test host · Offline',
);
for (final query in [
'HOST auth',
@@ -132,7 +132,7 @@ void main() {
expect(rows, hasLength(1));
expect(rows.single.swarmId, app.activeSwarmId);
expect(rows.single.current, isTrue);
- expect(rows.single.detail, 'Test host · Offline');
+ expect(rows.single.detail, 'Code · Test host · Offline');
});
for (final status in [
diff --git a/desktop/test/swarm_search_identity_test.dart b/desktop/test/swarm_search_identity_test.dart
new file mode 100644
index 000000000..2e22318fe
--- /dev/null
+++ b/desktop/test/swarm_search_identity_test.dart
@@ -0,0 +1,379 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/dsh_catalog.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/state/app_state.dart';
+import 'package:harness/state/swarm_catalog.dart';
+import 'package:harness/state/swarm_navigation.dart';
+import 'package:harness/state/swarm_search.dart';
+import 'package:harness/state/terminal_pane.dart';
+import 'package:harness/widgets/search_result_text.dart';
+
+import 'swarm_interactions_test.dart' show chord;
+import 'swarm_screen_test.dart' show mount, terminal;
+import 'swarm_state_test.dart' show createApp;
+
+void main() {
+ test(
+ 'single-harness tabs collapse by identity and keep their names searchable',
+ () async {
+ final app = createApp();
+ addTearDown(app.dispose);
+ final machine = app.machineStates['m']!;
+ machine.agents = [
+ for (final id in ['a0', 'a1'])
+ Agent(
+ id: id,
+ name: 'Harness extensibility architecture',
+ engine: 'claude',
+ terminalAvailable: true,
+ ),
+ ];
+ app.adoptSessionForTest(terminal('a0', []));
+ final first = app.activeSwarm;
+ app.renameSwarm(first.id, 'Architecture review');
+ // A viewer is part of the same harness, not a second harness.
+ first.panes.add(
+ TerminalPane(
+ id: 1000,
+ machineId: 'm',
+ kind: PaneKind.web,
+ ownerAgentId: 'a0',
+ url: 'http://localhost:8080',
+ ),
+ );
+ app.newSwarm(name: 'Another view');
+ await app.addAgentToSwarm('m', 'a0');
+ final cache = SwarmSearchCatalog();
+ final entries = cache.read(app, []);
+ expect(entries.where((row) => row.isSwarm), isEmpty);
+ final matches = rankSwarmDestinations(
+ entries,
+ 'Harness extensibility architecture',
+ );
+ expect(matches.map((row) => row.agentId).toSet(), {'a0', 'a1'});
+ for (final alias in ['Architecture review', 'Another view']) {
+ expect(rankSwarmDestinations(entries, alias).single.agentId, 'a0');
+ }
+ app.renameSwarm(first.id, 'Release planning');
+ final renamed = cache.read(app, []);
+ expect(
+ rankSwarmDestinations(renamed, 'Release planning').single.agentId,
+ 'a0',
+ );
+ expect(rankSwarmDestinations(renamed, 'Architecture review'), isEmpty);
+
+ // History still addresses tabs individually; this is a search collapse.
+ expect(
+ swarmDestinations(app, openOnly: true).where((row) => row.isSwarm),
+ hasLength(2),
+ );
+ },
+ );
+
+ test('harness subtitles use domain types and place the branch glyph after the project', () {
+ final app = createApp();
+ addTearDown(app.dispose);
+ final machine = app.machineStates['m']!..nodeOnline = true;
+ machine.agents = [
+ for (final (id, engine, dsh) in [
+ ('source', 'claude', null),
+ ('board', 'claude', 'autonomous/copper'),
+ ('part', 'codex', 'autonomous/solid'),
+ ('deck', 'claude', 'autonomous/marp'),
+ ])
+ Agent(
+ id: id,
+ name: id,
+ engine: engine,
+ dsh: dsh,
+ terminalAvailable: true,
+ project: const AgentProject(
+ name: 'Workbench',
+ cwd: '/work/workbench',
+ branch: 'main',
+ ),
+ ),
+ const Agent(
+ id: 'loose',
+ name: 'Loose code',
+ engine: 'codex',
+ terminalAvailable: true,
+ ),
+ const Agent(
+ id: 'no-branch',
+ name: 'Folder',
+ engine: 'codex',
+ terminalAvailable: true,
+ project: AgentProject(name: 'Folder', cwd: '/work/folder'),
+ ),
+ ];
+ final entries = SwarmSearchCatalog().read(app, []);
+ for (final (id, type) in [
+ ('source', 'Code'),
+ ('board', 'PCB'),
+ ('part', '3D design'),
+ ('deck', 'Slides'),
+ ]) {
+ final row = entries.singleWhere((row) => row.agentId == id);
+ expect(row.detail, '$type · Workbench · main · Test host');
+ expect(row.detailBranchOffset, row.detail.indexOf('main'));
+ expect(rankSwarmDestinations(entries, '$type $id').single, row);
+ }
+ final loose = entries.singleWhere((row) => row.agentId == 'loose');
+ expect(loose.detail, 'Code · Test host');
+ expect(loose.detailBranchOffset, isNull);
+ final folder = entries.singleWhere((row) => row.agentId == 'no-branch');
+ expect(folder.detail, 'Code · Folder · Test host');
+ expect(folder.detailBranchOffset, isNull);
+ });
+
+ test('machine-provided harness categories refresh the cached search', () {
+ final app = createApp();
+ addTearDown(app.dispose);
+ final machine = app.machineStates['m']!..nodeOnline = true;
+ machine.agents = const [
+ Agent(
+ id: 'robot',
+ name: 'Robot arm',
+ engine: 'codex',
+ dsh: 'studio/robotics',
+ terminalAvailable: true,
+ ),
+ ];
+ final cache = SwarmSearchCatalog();
+ final before = cache.read(app, []);
+ expect(
+ before.singleWhere((row) => row.agentId == 'robot').detail,
+ 'Test host',
+ );
+ machine.dsh.replace(const [
+ DshEntry(
+ id: 'studio/robotics',
+ name: 'Robot Studio',
+ engine: 'codex',
+ category: 'Robotics',
+ ),
+ ]);
+ final after = cache.read(app, []);
+ expect(after, isNot(same(before)));
+ expect(
+ after.singleWhere((row) => row.agentId == 'robot').detail,
+ 'Robotics · Test host',
+ );
+ expect(rankSwarmDestinations(after, 'Robotics').single.agentId, 'robot');
+ expect(cache.read(app, []), same(after));
+ });
+
+ test(
+ 'tab counts use distinct repositories and machines, ignoring viewers',
+ () async {
+ final app = createApp();
+ addTearDown(app.dispose);
+ final local = app.machineStates['m']!;
+ local.agents = const [
+ Agent(
+ id: 'a0',
+ name: 'Local checkout',
+ engine: 'codex',
+ terminalAvailable: true,
+ project: AgentProject(
+ name: 'Workbench',
+ cwd: '/local/work',
+ remote: 'github.com/team/workbench',
+ ),
+ ),
+ Agent(
+ id: 'a1',
+ name: 'Different repository',
+ engine: 'claude',
+ terminalAvailable: true,
+ project: AgentProject(
+ name: 'Workbench',
+ cwd: '/local/other',
+ remote: 'github.com/other/workbench',
+ ),
+ ),
+ ];
+ app.machineStates['remote'] =
+ MachineState(
+ const Machine(
+ machineId: 'remote',
+ name: 'Remote Mac',
+ authMode: MachineAuthMode.remote,
+ ),
+ )
+ ..nodeOnline = false
+ ..agents = const [
+ Agent(
+ id: 'a0',
+ name: 'Remote checkout',
+ engine: 'codex',
+ terminalAvailable: true,
+ project: AgentProject(
+ name: 'Workbench',
+ cwd: '/remote/work',
+ remote: 'github.com/team/workbench',
+ ),
+ ),
+ ];
+ await app.addAgentToSwarm('m', 'a0');
+ await app.addAgentToSwarm('remote', 'a0');
+ final tab = app.activeSwarm;
+ app.renameSwarm(tab.id, 'Release work');
+ tab.panes.add(
+ TerminalPane(
+ id: 1000,
+ machineId: 'm',
+ kind: PaneKind.web,
+ ownerAgentId: 'a0',
+ url: 'http://localhost:8080',
+ ),
+ );
+ final cache = SwarmSearchCatalog();
+ var rows = cache.read(app, []);
+ expect(
+ rows.singleWhere((row) => row.isSwarm).detail,
+ '2 harnesses · 1 project · 2 machines',
+ );
+ expect(rows.where((row) => row.agentId == 'a0'), hasLength(2));
+ expect(rows.singleWhere((row) => row.isSwarm).title, 'Release work');
+ await app.addAgentToSwarm('m', 'a1');
+ rows = cache.read(app, []);
+ expect(
+ rows.singleWhere((row) => row.isSwarm).detail,
+ '3 harnesses · 2 projects · 2 machines',
+ );
+
+ app.newSwarm();
+ final search = SwarmSearchController(
+ app,
+ [],
+ adding: true,
+ catalog: cache,
+ );
+ addTearDown(search.dispose);
+ search.setQuery('Release work');
+ final group = search.rows.singleWhere((row) => row.isSwarm);
+ expect(search.actionLabel(group), 'Open 3 Harnesses');
+ expect(
+ await activateSwarmSearchSelection(
+ app,
+ search.submit(group)!,
+ destinationSwarmId: app.activeSwarmId,
+ ),
+ isTrue,
+ );
+ expect(app.panes.where((pane) => pane.agentId != null), hasLength(3));
+ expect(tab.panes.where((pane) => pane.agentId != null), hasLength(3));
+ },
+ );
+
+ test(
+ 'saved project membership counts once when metadata is unavailable',
+ () async {
+ final app = createApp();
+ addTearDown(app.dispose);
+ await app.addAgentToSwarm('m', 'a0');
+ await app.addAgentToSwarm('m', 'a1');
+ const projects = [
+ SavedSwarmProject(
+ machineId: 'm',
+ path: '/work/old-daemon',
+ name: 'Legacy project',
+ members: [
+ (machineId: 'm', agentId: 'a0'),
+ (machineId: 'm', agentId: 'a1'),
+ ],
+ ),
+ ];
+ final cache = SwarmSearchCatalog();
+ expect(
+ cache.read(app, projects).singleWhere((row) => row.isSwarm).detail,
+ '2 harnesses · 1 project · 1 machine',
+ );
+ expect(
+ cache.read(app, []).singleWhere((row) => row.isSwarm).detail,
+ '2 harnesses · 1 machine',
+ );
+ },
+ );
+
+ test(
+ 'a retained harness remains searchable while its machine is unavailable',
+ () {
+ final app = createApp();
+ addTearDown(app.dispose);
+ app.adoptSessionForTest(terminal('a0', []));
+ app.renameSwarm(app.activeSwarmId, 'Offline review');
+ app.machineStates.clear();
+ final entries = SwarmSearchCatalog().read(app, []);
+ expect(entries, hasLength(1));
+ expect(entries.single.agentId, 'a0');
+ expect(
+ rankSwarmDestinations(entries, 'Offline review').single,
+ entries.single,
+ );
+ },
+ );
+
+ testWidgets(
+ 'Cmd O renders one harness result and opens it from a tab-name alias',
+ (tester) async {
+ final app = createApp();
+ final machine = app.machineStates['m']!..nodeOnline = true;
+ machine.agents = const [
+ Agent(
+ id: 'a0',
+ name: 'Harness extensibility architecture',
+ engine: 'claude',
+ terminalAvailable: true,
+ project: AgentProject(
+ name: 'autonomous-harness',
+ cwd: '/work/harness',
+ branch: 'main',
+ ),
+ ),
+ ];
+ final session = terminal('a0', []);
+ app.adoptSessionForTest(session);
+ app.renameSwarm(app.activeSwarmId, 'Architecture review');
+ final source = app.activeSwarm;
+ app.newSwarm();
+ final target = app.activeSwarm;
+ await mount(tester, app);
+ await chord(tester, LogicalKeyboardKey.keyO);
+ final input = find.byKey(const ValueKey('swarm-search-input'));
+ expect(
+ tester.widget<TextField>(input).decoration!.hintText,
+ 'Find a harness',
+ );
+ await tester.enterText(input, 'extensibility');
+ await tester.pump();
+ expect(find.byType(ListTile), findsOneWidget);
+ final result = tester.widget<ListTile>(find.byType(ListTile));
+ final subtitle = result.subtitle! as SearchResultText;
+ expect(subtitle.text, 'Code · autonomous-harness · main · Test host');
+ expect(subtitle.iconOffset, subtitle.text.indexOf('main'));
+ expect(
+ find.descendant(
+ of: find.byKey(const ValueKey('swarm-row-action')),
+ matching: find.text('Open Harness'),
+ ),
+ findsOneWidget,
+ );
+ await tester.enterText(input, 'Architecture review');
+ await tester.pump();
+ expect(find.byType(ListTile), findsOneWidget);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(app.activeSwarm, same(target));
+ expect(target.panes.single.session, same(session));
+ expect(source.panes.single.session, same(session));
+ expect(input, findsNothing);
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ },
+ );
+}