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.

Swarm Manage models: the first share or run sets the Swarm up; a simpler window

bitcoinbuilderdb94e982edce
diff --git a/desktop/lib/models/swarm_models_target.dart b/desktop/lib/models/swarm_models_target.dart
index eb87d2128..e1bef45df 100644
--- a/desktop/lib/models/swarm_models_target.dart
+++ b/desktop/lib/models/swarm_models_target.dart
@@ -15,12 +15,75 @@ class SwarmModelsTarget extends ChangeNotifier {
required this.app,
required this.grid,
required this.machineId,
+ this.ready = true,
+ this.canSetUp = false,
+ this.onSetUp,
+ this.setupNote,
+ this.setupError,
});
+ /// Whether the Swarm's models are set up, its grid made. Until they are, nothing is shared or run for it: the owner's
+ /// first share or run sets them up first ([whenSetUp]), and anyone else waits for the owner (2026-10-24: a list of
+ /// actions that could not be taken until a separate Set up read as broken).
+ bool ready;
+ bool get setupNeeded => !ready;
+
+ /// Whether this person may set them up: the Swarm's owner.
+ final bool canSetUp;
+
+ /// Sets them up from this computer; answers the Swarm's grid, or why it could not.
+ final Future<({String? grid, String? error})> Function()? onSetUp;
+
+ /// What a person who may not set them up is told instead: the owner has not, or is.
+ final String? setupNote;
+
+ /// Why the last set up failed, until another is tried.
+ String? setupError;
+
+ /// A set up under way.
+ bool settingUp = false;
+
+ /// The Swarm's models set up, once their grid is known (here, or on the owner's other computer).
+ void markReady(String swarmGrid) {
+ if (ready && grid == swarmGrid) return;
+ ready = true;
+ grid = swarmGrid;
+ setupError = null;
+ if (!_disposed) notifyListeners();
+ }
+
+ /// Runs [action] once the Swarm's models are set up, setting them up first when this person may and they are not.
+ /// Answers why it could not, or null.
+ Future<String?> whenSetUp(Future<String?> Function() action) async {
+ if (ready) return action();
+ final run = onSetUp;
+ if (run == null || !canSetUp || settingUp) return setupNote;
+ settingUp = true;
+ setupError = null;
+ if (!_disposed) notifyListeners();
+ ({String? grid, String? error}) answer;
+ try {
+ answer = await run();
+ } finally {
+ settingUp = false;
+ if (!_disposed) notifyListeners();
+ }
+ if (answer.grid case final swarmGrid? when answer.error == null) {
+ markReady(swarmGrid);
+ final error = await action();
+ await refresh();
+ return error;
+ }
+ setupError =
+ answer.error ?? 'Models could not be set up for this Swarm. Try again.';
+ if (!_disposed) notifyListeners();
+ return setupError;
+ }
+
final AppNotifier app;
- /// The Swarm's grid.
- final String grid;
+ /// The Swarm's grid; empty until its models are set up.
+ String grid;
/// This computer: the APIs are its own saved ones, and only it shares them.
final String machineId;
@@ -43,6 +106,8 @@ class SwarmModelsTarget extends ChangeNotifier {
shares.contains(shareKey(connectionId, model));
Future<void> refresh() async {
+ // No grid yet: nothing is shared or offered there.
+ if (!ready) return;
try {
final answer = await app.swarmOffers(machineId, grid);
offers = _keys(answer['offers'], 'sharedGrid');
diff --git a/desktop/lib/state/swarm_search.dart b/desktop/lib/state/swarm_search.dart
index bbd2e6306..7108c66e7 100644
--- a/desktop/lib/state/swarm_search.dart
+++ b/desktop/lib/state/swarm_search.dart
@@ -475,6 +475,28 @@ class SwarmSearchController extends ChangeNotifier {
/// person (agents on their machines use it as it is), a download under way (the preview's Cancel).
({String label, String command, Future<String?> Function()? run})?
swarmModelAction(SwarmDestination? row) {
+ final action = _swarmModelAction(row);
+ final swarm = swarmModels;
+ // Before the Swarm's models are set up, the owner's first share or run sets them up, then does it; a download needs
+ // nothing of the Swarm. Anyone else waits for the owner (the preview says so).
+ if (action == null ||
+ swarm == null ||
+ !swarm.setupNeeded ||
+ action.command == 'picker.model_download') {
+ return action;
+ }
+ final run = action.run;
+ return (
+ label: swarm.settingUp ? 'Setting up…' : action.label,
+ command: action.command,
+ run: run == null || !swarm.canSetUp || swarm.settingUp
+ ? null
+ : () => swarm.whenSetUp(run),
+ );
+ }
+
+ ({String label, String command, Future<String?> Function()? run})?
+ _swarmModelAction(SwarmDestination? row) {
final swarm = swarmModels;
final entry = models?.entries[row?.modelId];
if (swarm == null || entry == null) return null;
@@ -487,16 +509,21 @@ class SwarmSearchController extends ChangeNotifier {
owner.machine?.connectionStatus == ConnectionStatus.connected &&
owner.machine?.needsLink == false &&
(owner.targetMachineId == null || owner.machine?.isOffline == false);
- Future<String?> Function() act(String action, {String? grid}) =>
+ // The Swarm's grid is read when the action runs: a first run sets the Swarm's models up, and names it then.
+ Future<String?> Function() act(String action, {bool forSwarm = false}) =>
() async {
- await owner.control(local, action, grid: grid);
+ await owner.control(
+ local,
+ action,
+ grid: forSwarm ? swarm.grid : null,
+ );
return owner.error;
};
if (local.servedOn(swarm.grid)) {
return (
label: 'Stop for Swarm',
command: 'picker.model_stop',
- run: ready ? act('stop', grid: swarm.grid) : null,
+ run: ready ? act('stop', forSwarm: true) : null,
);
}
// Too small or too slow to drive a coding agent: no Builder would be offered it, so neither Get nor Run is
@@ -515,7 +542,7 @@ class SwarmSearchController extends ChangeNotifier {
label: 'Run for Swarm',
command: 'picker.model_start',
run: ready && capable && local.canStart
- ? act('start', grid: swarm.grid)
+ ? act('start', forSwarm: true)
: null,
);
}
diff --git a/desktop/lib/super_tabs/local_models.dart b/desktop/lib/super_tabs/local_models.dart
index c036e807f..3fe842e3c 100644
--- a/desktop/lib/super_tabs/local_models.dart
+++ b/desktop/lib/super_tabs/local_models.dart
@@ -60,7 +60,8 @@ class _SwarmModelsWindowState extends State<_SwarmModelsWindow> {
/// then has this computer's Harness set grid up — installed and signed in with the Harness account if it is not —
/// create the grid and add the Swarm's people, and tells the Swarm how that went. The owner's computers keep the
/// members in step afterwards (CLI `superTabs/swarmGrids.ts`).
- Future<void> _setUp() async {
+ /// Answers the Swarm's grid once it is ready, else null ([_error] says why).
+ Future<String?> _setUp() async {
final c = widget.controller, app = widget.app;
setState(() {
_settingUp = true;
@@ -81,12 +82,12 @@ class _SwarmModelsWindowState extends State<_SwarmModelsWindow> {
if (grid == null) {
_error =
c.operationError ?? 'The Swarm could not be reached. Try again.';
- return;
+ return null;
}
final machineId = app?.modelManager.machine?.machine.machineId;
if (app == null || machineId == null) {
// Nothing here can run grid: the owner's other computers finish it in the background.
- return;
+ return null;
}
final members = [
for (final person in c.snapshot?.people ?? const <SuperTabPerson>[])
@@ -113,7 +114,12 @@ class _SwarmModelsWindowState extends State<_SwarmModelsWindow> {
if (error != null)
'error': error.length > 500 ? error.substring(0, 500) : error,
});
- if (!ready) _error = error ?? 'Grid could not be set up. Try again.';
+ if (!ready) {
+ _error =
+ error ?? 'Models could not be set up for this Swarm. Try again.';
+ return null;
+ }
+ return grid;
} finally {
if (mounted) setState(() => _settingUp = false);
}
@@ -128,20 +134,24 @@ class _SwarmModelsWindowState extends State<_SwarmModelsWindow> {
builder: (context, _) {
final local = c.snapshot?.localModels;
final on = local?.enabled == true;
- final picker = on && local?.ready == true && app != null;
+ // The models list whenever this computer can run models, as ⌘I's is; before the Swarm's are set up it offers
+ // Set up in it, as ⌘I offers setting Grid up (owner, 2026-10-24). The panel below is for a window with no models.
+ final ready = on && local?.ready == true;
+ final picker = app != null;
final String? failed = _settingUp
? null
: _error ??
(on && local?.ready == false
- ? local?.error ?? 'grid refused the request'
+ ? local?.error ?? 'the request was refused'
: null);
final header = Padding(
padding: EdgeInsets.fromLTRB(24, 18, 16, picker ? 14 : 4),
child: Row(
children: [
Expanded(
- child: Column(
- crossAxisAlignment: CrossAxisAlignment.start,
+ child: Row(
+ crossAxisAlignment: CrossAxisAlignment.baseline,
+ textBaseline: TextBaseline.alphabetic,
children: [
Text(
'Manage models',
@@ -151,25 +161,17 @@ class _SwarmModelsWindowState extends State<_SwarmModelsWindow> {
height: 1.35,
).copyWith(fontWeight: FontWeight.w600),
),
+ // The computer whose models and APIs these are, beside the title.
if (picker) ...[
- const SizedBox(height: 2),
- Row(
- key: const ValueKey('super-local-models-ready'),
- children: [
- Container(
- width: 6,
- height: 6,
- decoration: BoxDecoration(
- color: grid.AppPalette.online,
- shape: BoxShape.circle,
- ),
- ),
- const SizedBox(width: 6),
- Text(
- 'Swarm grid ready · ${_capitalized(thisComputerName())}',
- style: DesktopChrome.metadata(),
- ),
- ],
+ const SizedBox(width: 10),
+ Flexible(
+ child: Text(
+ _capitalized(thisComputerName()),
+ key: const ValueKey('super-local-models-machine'),
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: DesktopChrome.metadata(),
+ ),
),
],
],
@@ -206,8 +208,7 @@ class _SwarmModelsWindowState extends State<_SwarmModelsWindow> {
: failed != null
? 'Could not set up: ${_sentence(failed)}'
: c.isOwner
- ? 'Set up gets this computer ready with your Harness account and creates the Swarm\'s grid. '
- 'People in the Swarm are added to it, now and as they join.'
+ ? 'Set up connects this computer to the Swarm with your Harness account. Everyone in the Swarm can then use the models you run and the APIs you share, now and as they join.'
: 'The Swarm owner has not set up models yet.',
style: DesktopChrome.metadata(
color: failed != null
@@ -259,7 +260,23 @@ class _SwarmModelsWindowState extends State<_SwarmModelsWindow> {
header,
if (picker) ...[
Expanded(
- child: _SwarmModelsPicker(app: app, grid: local!.grid),
+ child: _SwarmModelsPicker(
+ app: app,
+ grid: local?.grid ?? '',
+ ready: ready,
+ canSetUp: c.isOwner,
+ onSetUp: () async {
+ final grid = await _setUp();
+ return (
+ grid: grid,
+ error: grid == null ? _error : null,
+ );
+ },
+ setupNote: on && local?.ready == null
+ ? 'The Swarm owner is setting up its models.'
+ : 'The Swarm owner has not set up models yet.',
+ setupError: _settingUp ? null : failed,
+ ),
),
] else
setup,
@@ -275,10 +292,23 @@ class _SwarmModelsWindowState extends State<_SwarmModelsWindow> {
/// ⌘I's Models list and preview, for the Swarm whose grid is [grid].
class _SwarmModelsPicker extends StatefulWidget {
- const _SwarmModelsPicker({required this.app, required this.grid});
+ const _SwarmModelsPicker({
+ required this.app,
+ required this.grid,
+ this.ready = true,
+ this.canSetUp = false,
+ this.onSetUp,
+ this.setupNote,
+ this.setupError,
+ });
final AppNotifier app;
final String grid;
+ final bool ready;
+ final bool canSetUp;
+ final Future<({String? grid, String? error})> Function()? onSetUp;
+ final String? setupNote;
+ final String? setupError;
@override
State<_SwarmModelsPicker> createState() => _SwarmModelsPickerState();
@@ -304,6 +334,11 @@ class _SwarmModelsPickerState extends State<_SwarmModelsPicker> {
app: app,
grid: widget.grid,
machineId: app.modelManager.machine?.machine.machineId ?? '',
+ ready: widget.ready,
+ canSetUp: widget.canSetUp,
+ onSetUp: widget.onSetUp,
+ setupNote: widget.setupNote,
+ setupError: widget.setupError,
);
unawaited(_target.refresh());
// `adding`/`offersCreate`: the APIs section ends in Add API connection, as ⌘I's does.
@@ -317,6 +352,16 @@ class _SwarmModelsPickerState extends State<_SwarmModelsPicker> {
)..setQuery(':');
}
+ @override
+ void didUpdateWidget(covariant _SwarmModelsPicker oldWidget) {
+ super.didUpdateWidget(oldWidget);
+ // Set up meanwhile, here or on the owner's other computer: the same list goes on, on the Swarm's grid.
+ if (widget.ready && !_target.ready && widget.grid.isNotEmpty) {
+ _target.markReady(widget.grid);
+ unawaited(_target.refresh());
+ }
+ }
+
@override
void dispose() {
widget.app.modelManager.setPanelVisible(false);
@@ -346,7 +391,6 @@ class _SwarmModelsPickerState extends State<_SwarmModelsPicker> {
@override
Widget build(BuildContext context) {
- final hints = KeyHints.visibleOf(context);
return Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
@@ -387,11 +431,6 @@ class _SwarmModelsPickerState extends State<_SwarmModelsPicker> {
),
),
),
- if (hints)
- ListenableBuilder(
- listenable: Listenable.merge([_search, _target]),
- builder: (context, _) => _SwarmModelsHints(search: _search),
- ),
],
);
}
@@ -480,67 +519,6 @@ class _SwarmModelScopes extends StatelessWidget {
}
}
-/// The window's keys, along its foot: Return says what it does on the chosen row.
-class _SwarmModelsHints extends StatelessWidget {
- const _SwarmModelsHints({required this.search});
-
- final SwarmSearchController search;
-
- @override
- Widget build(BuildContext context) {
- final row = search.selected;
- final action = row == null ? null : search.swarmModelAction(row);
- final enter = row == null
- ? null
- : row.isCreate
- ? 'Add API connection'
- // Enter does nothing on an action that cannot run (a model too small for Builders): no hint for it.
- : action != null
- ? (action.run == null ? null : action.label)
- : search.canExpandApi(row) ||
- search.isModelDownloadsRow(row) ||
- search.canGetModel(row)
- ? search.actionLabel(row)
- : null;
- Widget hint(String key, String label) => Row(
- mainAxisSize: MainAxisSize.min,
- children: [
- Container(
- padding: const EdgeInsets.symmetric(horizontal: 5),
- decoration: BoxDecoration(
- color: DesktopChrome.foreground.withValues(alpha: .07),
- borderRadius: BorderRadius.circular(4),
- ),
- child: Text(key, style: DesktopChrome.text(size: 11, height: 1.45)),
- ),
- const SizedBox(width: 6),
- Text(
- label,
- style: DesktopChrome.text(size: 11, color: DesktopChrome.muted),
- ),
- ],
- );
- return Container(
- key: const ValueKey('super-local-models-hints'),
- height: 36,
- padding: const EdgeInsets.symmetric(horizontal: 20),
- decoration: BoxDecoration(
- border: Border(top: BorderSide(color: DesktopChrome.rim)),
- ),
- child: Row(
- children: [
- hint('↑↓', 'Select'),
- if (enter != null) ...[const SizedBox(width: 16), hint('↵', enter)],
- const SizedBox(width: 16),
- hint('⇥', 'Actions'),
- const Spacer(),
- hint('esc', 'Close'),
- ],
- ),
- );
- }
-}
-
String _capitalized(String text) =>
text.isEmpty ? text : '${text[0].toUpperCase()}${text.substring(1)}';
diff --git a/desktop/lib/super_tabs/project_sidebar.dart b/desktop/lib/super_tabs/project_sidebar.dart
index f58b10116..04c27698e 100644
--- a/desktop/lib/super_tabs/project_sidebar.dart
+++ b/desktop/lib/super_tabs/project_sidebar.dart
@@ -401,7 +401,7 @@ class ProjectSidebar extends StatelessWidget {
_navigationRow(
key: 'super-local-models',
label: 'Manage models',
- icon: AppIcons.cpu,
+ icon: AppIcons.brain,
onTap: () =>
showSwarmLocalModels(context, controller, app: app, now: now),
),
diff --git a/desktop/lib/widgets/swarm_resource_preview.dart b/desktop/lib/widgets/swarm_resource_preview.dart
index 1099c1cd2..cb9f3ecdb 100644
--- a/desktop/lib/widgets/swarm_resource_preview.dart
+++ b/desktop/lib/widgets/swarm_resource_preview.dart
@@ -1448,6 +1448,40 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
),
),
],
+ // Not set up yet: what the first share or run does first, or who sets it up (SwarmModelsTarget.whenSetUp).
+ if (widget.search.swarmModels case final swarm?
+ when swarm.setupNeeded &&
+ const {
+ SwarmModelKind.apiModel,
+ SwarmModelKind.local,
+ SwarmModelKind.live,
+ SwarmModelKind.shared,
+ }.contains(kind)) ...[
+ const SizedBox(height: 10),
+ ConstrainedBox(
+ constraints: const BoxConstraints(maxWidth: 460),
+ child: Text(
+ key: const ValueKey('swarm-model-setup-note'),
+ swarm.settingUp
+ ? 'Setting up this Swarm\'s models… The first time can take a few minutes.'
+ : swarm.canSetUp
+ ? 'This Swarm\'s models are not set up yet. Your first share or run sets them up: it connects this '
+ 'computer to the Swarm with your Harness account, and everyone in the Swarm can then use them.'
+ : swarm.setupNote ??
+ 'The Swarm owner has not set up models yet.',
+ style: DesktopChrome.metadata(),
+ ),
+ ),
+ if (!swarm.settingUp && swarm.setupError != null) ...[
+ const SizedBox(height: 8),
+ Text(
+ 'Could not set up: ${swarm.setupError}',
+ style: DesktopChrome.metadata(
+ color: Theme.of(context).colorScheme.error,
+ ),
+ ),
+ ],
+ ],
for (final line in errors) ...[
const SizedBox(height: 10),
Text(line, style: DesktopChrome.text(size: 12, color: error)),
@@ -1670,7 +1704,7 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
]
: [
'More models',
- 'The rest of the models the grid catalog ranks for this machine, best first.',
+ 'The rest of the models that fit this machine, best first.',
],
controls: true,
);
diff --git a/desktop/test/super_tab_sidebar_test.dart b/desktop/test/super_tab_sidebar_test.dart
index 2b9753966..f3017b032 100644
--- a/desktop/test/super_tab_sidebar_test.dart
+++ b/desktop/test/super_tab_sidebar_test.dart
@@ -481,7 +481,7 @@ void main() {
await tester.pumpAndSettle();
expect(find.byType(Switch), findsNothing);
expect(
- find.textContaining('Set up gets this computer ready'),
+ find.textContaining('Set up connects this computer to the Swarm'),
findsOneWidget,
);
await tester.tap(setUp);
diff --git a/desktop/test/swarm_local_models_picker_test.dart b/desktop/test/swarm_local_models_picker_test.dart
index d4ef1a83c..45d3b9766 100644
--- a/desktop/test/swarm_local_models_picker_test.dart
+++ b/desktop/test/swarm_local_models_picker_test.dart
@@ -21,6 +21,7 @@ class _Subscriptions extends ModelsMenuController {
class _SwarmApp extends ModelManagerTestApp {
_SwarmApp() : super(ModelManagerConnection());
final shareCalls = <({String connectionId, String model, bool start})>[];
+ final shareGrids = <String>[];
final shared = <({String connectionId, String model})>{};
String? shareError;
bool sharesFail = false;
@@ -75,6 +76,7 @@ class _SwarmApp extends ModelManagerTestApp {
required bool start,
}) async {
shareCalls.add((connectionId: connectionId, model: model, start: start));
+ shareGrids.add(grid);
if (shareError != null) return {'error': shareError};
final key = (connectionId: connectionId, model: model);
start ? shared.add(key) : shared.remove(key);
@@ -263,23 +265,25 @@ void main() {
expect(sections, contains(ModelSearchSection.local));
search.setModelScope(ModelSearchSection.catalog);
expect(search.rows, isNotEmpty);
- expect(
- search.rows.map(search.modelSection).toSet(),
- {ModelSearchSection.catalog},
- );
+ expect(search.rows.map(search.modelSection).toSet(), {
+ ModelSearchSection.catalog,
+ });
search.setModelScope(null);
expect(search.rows.map(search.modelSection).toSet(), sections);
});
- test('offers neither Run nor Get for a model too small to drive a coding agent', () {
- final run = search.swarmModelAction(row('tiny'))!;
- expect(run.label, 'Run for Swarm');
- expect(run.run, isNull);
- final get = search.swarmModelAction(row('tiny-get'))!;
- expect(get.label, 'Get');
- expect(get.run, isNull);
- expect(search.swarmModelAction(row('downloaded'))!.run, isNotNull);
- });
+ test(
+ 'offers neither Run nor Get for a model too small to drive a coding agent',
+ () {
+ final run = search.swarmModelAction(row('tiny'))!;
+ expect(run.label, 'Run for Swarm');
+ expect(run.run, isNull);
+ final get = search.swarmModelAction(row('tiny-get'))!;
+ expect(get.label, 'Get');
+ expect(get.run, isNull);
+ expect(search.swarmModelAction(row('downloaded'))!.run, isNotNull);
+ },
+ );
test('stops a model running for the Swarm on the Swarm\'s grid', () async {
await search.swarmModelAction(row('served'))!.run!();
@@ -307,4 +311,48 @@ void main() {
expect(await target.share('c1', 'deepseek', start: false), isNull);
expect(target.shared('c1', 'deepseek'), isFalse);
});
+
+ // 2026-10-24: a list of actions that could not be taken until a separate Set up read as broken. The owner's first
+ // share or run sets the Swarm's models up, then does it; anyone else waits for the owner.
+ test('before set up, the owner\'s first share sets the Swarm\'s models up, then shares on its grid', () async {
+ var setUps = 0;
+ final fresh = SwarmModelsTarget(
+ app: app,
+ grid: '',
+ machineId: 'm',
+ ready: false,
+ canSetUp: true,
+ onSetUp: () async {
+ setUps++;
+ return (
+ grid: setUps == 1 ? null : _grid,
+ error: setUps == 1 ? 'offline' : null,
+ );
+ },
+ );
+ addTearDown(fresh.dispose);
+ Future<String?> share() => fresh.share('c1', 'deepseek', start: true);
+ // A failed set up shares nothing and says why.
+ expect(await fresh.whenSetUp(share), 'offline');
+ expect(fresh.setupError, 'offline');
+ expect(app.shareCalls, isEmpty);
+ expect(await fresh.whenSetUp(share), isNull);
+ expect(fresh.ready, isTrue);
+ expect(app.shareGrids, [_grid]);
+ // Set up now: the action runs as it is.
+ expect(await fresh.whenSetUp(() async => 'ran'), 'ran');
+ expect(setUps, 2);
+ // Someone who may not set it up is told who does.
+ final member = SwarmModelsTarget(
+ app: app,
+ grid: '',
+ machineId: 'm',
+ ready: false,
+ setupNote: 'The owner sets it up.',
+ );
+ addTearDown(member.dispose);
+ expect(await member.whenSetUp(() async => 'ran'), 'The owner sets it up.');
+ member.markReady(_grid);
+ expect(member.grid, _grid);
+ });
}