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.

feat(swarm): size machine slots from total RAM (#1605)

0xken15f1afc1038350
diff --git a/cli/src/superTabs/contribution.spec.ts b/cli/src/superTabs/contribution.spec.ts
index 6028b50b8..c7955b984 100644
--- a/cli/src/superTabs/contribution.spec.ts
+++ b/cli/src/superTabs/contribution.spec.ts
@@ -45,20 +45,31 @@ describe('one-field machine preparation', () => {
})
it('uses the lead project on its host and probes all engines without inventing authentication', async () => {
const f = fixture()
- expect(await f.run()).toEqual({ ok: true, state: 'ready', cwd: '/repo', engines: ['claude', 'pi'], maxAgents: 8 })
+ expect(await f.run()).toEqual({ ok: true, state: 'ready', cwd: '/repo', engines: ['claude', 'pi'], maxAgents: 8, maxAvailableAgents: 16 })
expect(f.request).toHaveBeenCalledWith('engines_probe', { accounts: true }, 20000)
expect(f.deps.prepare).not.toHaveBeenCalled()
expect(f.close).toHaveBeenCalledOnce()
})
- it('offers one slot per 2 GiB free, the memory each start needs, between one and eight', async () => {
+ it.each([
+ { totalGiB: 32, usedGiB: 30, maxAgents: 8, maxAvailableAgents: 16 },
+ { totalGiB: 16, usedGiB: 15, maxAgents: 4, maxAvailableAgents: 8 },
+ { totalGiB: 64, usedGiB: 63, maxAgents: 16, maxAvailableAgents: 16 },
+ { totalGiB: 2, usedGiB: 1, maxAgents: 1, maxAvailableAgents: 1 },
+ ])('suggests $maxAgents of $maxAvailableAgents slots from $totalGiB GiB total RAM', async ({ totalGiB, usedGiB, maxAgents, maxAvailableAgents }) => {
+ const f = fixture()
+ f.deps.capacity.mockResolvedValueOnce({ ok: true, resources: {
+ memoryTotalBytes: totalGiB * GiB, memoryUsedBytes: usedGiB * GiB, projectDiskFreeBytes: 100 * GiB,
+ } })
+ expect(await f.run()).toMatchObject({ maxAgents, maxAvailableAgents })
+ })
+ it('keeps the suggestion when free RAM changes but total RAM does not', async () => {
const f = fixture()
const slots = async (freeBytes: number) => {
f.deps.capacity.mockResolvedValueOnce({ ok: true, resources: { memoryTotalBytes: 32 * GiB, memoryUsedBytes: 32 * GiB - freeBytes, projectDiskFreeBytes: 100 * GiB } })
return (await f.run() as { maxAgents?: number }).maxAgents
}
- // Diego's Mac on 2026-10-21: 32 GiB, about 5.3 GiB free.
- expect(await slots(5.3 * GiB)).toBe(2)
- expect(await slots(GiB)).toBe(1)
+ expect(await slots(5.3 * GiB)).toBe(8)
+ expect(await slots(GiB)).toBe(8)
expect(await slots(30 * GiB)).toBe(8)
})
it('prepares the repository on another machine and reuses an existing contribution', async () => {
diff --git a/cli/src/superTabs/contribution.ts b/cli/src/superTabs/contribution.ts
index c193530a8..e257f0710 100644
--- a/cli/src/superTabs/contribution.ts
+++ b/cli/src/superTabs/contribution.ts
@@ -45,12 +45,12 @@ export async function prepareContribution(core: CoreApi, input: Json, deps = {
if (!engines.length) throw new Error('Sign in to an agent on this machine, then try again.')
const resources = object('resources' in capability ? capability.resources : null)
if (capability.ok !== true || typeof resources.projectDiskFreeBytes !== 'number') throw new Error('The project folder is unavailable on this machine.')
- const available = typeof resources.memoryTotalBytes === 'number' && typeof resources.memoryUsedBytes === 'number'
- ? Math.max(0, resources.memoryTotalBytes - resources.memoryUsedBytes) : 0
- // A ceiling, not a promise: each actual start still needs 2 GiB free at that moment (START_REQUIREMENTS), so it
- // matches that. At 4 GiB a 32 GiB Mac with 5 GiB free offered one slot while it could run two.
- const maxAgents = Math.max(1, Math.min(8, Math.floor(available / START_REQUIREMENTS.memoryBytes)))
- return { ok: true, state: 'ready', cwd, engines: [...new Set(engines)], maxAgents, ...(swarm ? { scope: 'swarm' } : {}) }
+ const total = typeof resources.memoryTotalBytes === 'number' ? resources.memoryTotalBytes : 0
+ // Free memory is checked again for every start. It must not shrink the machine's
+ // configured limit just because other work happens to be running during setup.
+ const maxAvailableAgents = Math.max(1, Math.min(16, Math.floor(total / START_REQUIREMENTS.memoryBytes)))
+ const maxAgents = Math.max(1, Math.min(16, Math.floor(total / (2 * START_REQUIREMENTS.memoryBytes))))
+ return { ok: true, state: 'ready', cwd, engines: [...new Set(engines)], maxAgents, maxAvailableAgents, ...(swarm ? { scope: 'swarm' } : {}) }
} finally { connection.close() }
}
diff --git a/cli/src/superTabs/contribution.windows.spec.ts b/cli/src/superTabs/contribution.windows.spec.ts
index 49e8f1b0c..247f96194 100644
--- a/cli/src/superTabs/contribution.windows.spec.ts
+++ b/cli/src/superTabs/contribution.windows.spec.ts
@@ -34,7 +34,7 @@ describe('contributing a Windows machine to a swarm', () => {
])('$name', async ({ existing, cwd }) => {
const { core, deps, close } = fixture(existing)
const result = await prepareContribution(core, { tabId: 'tab', scope: 'swarm' }, deps as never)
- expect(result).toEqual({ ok: true, state: 'ready', scope: 'swarm', cwd, engines: ['claude'], maxAgents: 4 })
+ expect(result).toEqual({ ok: true, state: 'ready', scope: 'swarm', cwd, engines: ['claude'], maxAgents: 2, maxAvailableAgents: 4 })
expect(mkdir).toHaveBeenCalledExactlyOnceWith(cwd, { recursive: true })
expect(deps.capacity).toHaveBeenCalledExactlyOnceWith({ cwd, tools: ['git'], devices: [] })
expect(deps.prepare).not.toHaveBeenCalled()
diff --git a/desktop/lib/super_tabs/machines.dart b/desktop/lib/super_tabs/machines.dart
index 6c7a78d09..b964a0276 100644
--- a/desktop/lib/super_tabs/machines.dart
+++ b/desktop/lib/super_tabs/machines.dart
@@ -33,11 +33,9 @@ import 'section_heading.dart';
export 'machine_status.dart';
-/// The owner's agent slots run 1–8 here, though the backend itself accepts up
-/// to 16: widening the UI to the backend's ceiling would only invite a number
-/// the machine cannot run.
+/// The backend's upper bound. A machine's own total RAM may set a lower one.
const _agentSlotsMin = 1;
-const _agentSlotsMax = 8;
+const _agentSlotsMax = 16;
/// What one more agent needs to start, the CLI's own figure
/// (`START_REQUIREMENTS.memoryBytes`, `cli/src/superTabs/capacity.ts`).
@@ -46,14 +44,18 @@ const _agentMemoryBytes = 2 * 1024 * 1024 * 1024;
int _clampAgentSlots(num value) =>
value.toInt().clamp(_agentSlotsMin, _agentSlotsMax);
-/// What this machine's free memory suggests, by the CLI's own arithmetic: one
-/// agent per [_agentMemoryBytes] free. Null when the reading does not say how
-/// much memory there is.
+/// The machine's total-RAM limit and its half-sized starting suggestion.
+/// The suggestion is capped separately, so 64 GiB suggests 16 of 16 slots.
+int? _maxAgentSlots(MachineResources? resources) {
+ final total = resources?.memoryTotalBytes;
+ if (total == null) return null;
+ return _clampAgentSlots((total / _agentMemoryBytes).floor());
+}
+
int? _suggestedAgentSlots(MachineResources? resources) {
final total = resources?.memoryTotalBytes;
- final used = resources?.memoryUsedBytes;
- if (total == null || used == null) return null;
- return _clampAgentSlots(((total - used) / _agentMemoryBytes).floor());
+ if (total == null) return null;
+ return _clampAgentSlots((total / (2 * _agentMemoryBytes)).floor());
}
class SuperTabMachines extends StatefulWidget {
@@ -105,8 +107,7 @@ class _MachineChoice {
}
/// "Agent slots" — how many agents this machine offers the Swarm — with the one
-/// thing the number is not: a promise. Its free memory is what it was suggested
-/// from, and what is free moves.
+/// thing the number is not: a promise. Each start still checks free memory.
///
/// A stepper rather than a number field, so no keystroke can leave the dialog
/// holding a count the backend would refuse; both buttons go dead at the bounds
@@ -114,19 +115,16 @@ class _MachineChoice {
class _AgentSlots extends StatelessWidget {
const _AgentSlots({
required this.value,
+ required this.maximum,
required this.busy,
required this.onChanged,
- this.cappedFrom,
});
final int value;
+ final int maximum;
final bool busy;
final ValueChanged<int> onChanged;
- /// The number this machine was contributed with, when it is above what this
- /// form offers: saving would lower it, and the owner is told so.
- final int? cappedFrom;
-
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
@@ -158,7 +156,8 @@ class _AgentSlots extends StatelessWidget {
tooltip: 'Fewer slots',
onPressed: busy || value <= _agentSlotsMin
? null
- : () => onChanged(value - 1),
+ : () =>
+ onChanged(value > maximum ? maximum : value - 1),
),
Text(
value.toString(),
@@ -170,7 +169,7 @@ class _AgentSlots extends StatelessWidget {
icon: AppIcons.plus,
size: 16,
tooltip: 'More slots',
- onPressed: busy || value >= _agentSlotsMax
+ onPressed: busy || value >= maximum
? null
: () => onChanged(value + 1),
),
@@ -184,14 +183,6 @@ class _AgentSlots extends StatelessWidget {
'Each new agent still needs free memory when it starts.',
style: DesktopChrome.metadata(),
),
- if (cappedFrom case final from?) ...[
- const SizedBox(height: 4),
- Text(
- 'This machine was set to $from agent slots. This form offers up to '
- '$_agentSlotsMax, and saving here lowers it.',
- style: DesktopChrome.metadata(),
- ),
- ],
],
);
}
@@ -526,7 +517,7 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
var busy = false;
String? setupId;
// The agent slots the owner is choosing. A machine already in this Swarm
- // starts at the number it has; a new one starts at what its free memory
+ // starts at the number it has; a new one starts at what its total memory
// suggests, worked out here rather than by preparation (below).
int? storedSlots(String? id) {
final row = id == null
@@ -536,16 +527,10 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
return current is num ? current.toInt() : null;
}
- /// A machine contributed before this form had a range keeps its number
- /// until the owner saves, and is told when saving would lower it.
- int? storedOverRange(String? id) {
- final stored = storedSlots(id);
- return stored != null && stored > _agentSlotsMax ? stored : null;
- }
-
// Readings this dialog has taken itself, keyed by machine. The panel's own
// samples stand in for a machine it already reads.
final suggestions = <String, int>{};
+ final maximums = <String, int>{};
/// What this machine's own memory says, once a reading has answered. Null
/// while one is still coming, or when it failed.
@@ -553,6 +538,12 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
? null
: suggestions[id] ?? _suggestedAgentSlots(_samples[id]?.$1);
+ int maximumFor(String? id) => id == null
+ ? _agentSlotsMin
+ : maximums[id] ??
+ _maxAgentSlots(_samples[id]?.$1) ??
+ _clampAgentSlots(storedSlots(id) ?? _agentSlotsMin);
+
int slotsFor(String? id) {
final stored = storedSlots(id);
if (stored != null) return _clampAgentSlots(stored);
@@ -572,14 +563,11 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
/// Start the field where this machine's own memory says, without asking
/// preparation: preparation sets the project up, probes engines and takes
/// one of its 32 setup slots, and opening a form the owner may cancel is
- /// no reason to do that. A machine with a number of its own needs no
- /// reading at all.
+ /// no reason to do that. A configured machine still needs its RAM reading
+ /// for the stepper limit, but its chosen number is never replaced.
Future<void> suggestSlots() async {
final id = machineId;
- if (id == null ||
- storedSlots(id) != null ||
- !canSelect(app.stateOf(id)) ||
- !reading.add(id)) {
+ if (id == null || !canSelect(app.stateOf(id)) || !reading.add(id)) {
return;
}
MachineResources? resources;
@@ -595,9 +583,11 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
return;
}
suggestions[id] = suggested;
- // Never over a number the owner has set meanwhile.
- if (slotsEdited) return;
- repaint?.call(() => slots = suggested);
+ maximums[id] = _maxAgentSlots(resources)!;
+ // Repaint the limit, but never replace a number the owner chose.
+ repaint?.call(() {
+ if (!slotsEdited && storedSlots(id) == null) slots = suggested;
+ });
}
await showAppDialog<void>(
@@ -666,6 +656,10 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
// preparation offered instead — the number the field would
// have shown had the reading arrived.
final offered = prepared['maxAgents'];
+ final offeredMaximum = prepared['maxAvailableAgents'];
+ if (offeredMaximum is num) {
+ maximums[selected] = _clampAgentSlots(offeredMaximum);
+ }
if (!slotsEdited &&
storedSlots(selected) == null &&
memorySuggestion(selected) == null &&
@@ -803,8 +797,8 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
const SizedBox(height: 16),
_AgentSlots(
value: slots,
+ maximum: maximumFor(machineId),
busy: busy,
- cappedFrom: storedOverRange(machineId),
onChanged: (next) => update(() {
slots = next;
slotsEdited = true;
diff --git a/desktop/test/super_tab_launch_test.dart b/desktop/test/super_tab_launch_test.dart
index 9beea1cca..5dfb993af 100644
--- a/desktop/test/super_tab_launch_test.dart
+++ b/desktop/test/super_tab_launch_test.dart
@@ -158,7 +158,8 @@ class SuperTabFixtureConnection extends WsConn {
'cwd': '/work/project',
'scope': 'swarm',
'engines': ['claude', 'codex', 'pi'],
- 'maxAgents': 4,
+ 'maxAgents': 8,
+ 'maxAvailableAgents': 16,
};
}
if (payload['action'] == 'prepareNative' ||
diff --git a/desktop/test/super_tab_machines_test.dart b/desktop/test/super_tab_machines_test.dart
index 0369c0ea8..86146c3bf 100644
--- a/desktop/test/super_tab_machines_test.dart
+++ b/desktop/test/super_tab_machines_test.dart
@@ -26,8 +26,7 @@ import 'super_tab_launch_test.dart' show SuperTabLaunchFixture, tabId;
import 'support/capture.dart';
import 'support/super_tab_fixture.dart';
-/// What a machine with this much free memory is expected to offer: the same
-/// one-agent-per-2-GiB arithmetic the CLI works the suggestion out with.
+/// Model total and free memory separately so a suggestion cannot use free RAM.
MachineResources _reading({required double freeGiB, double totalGiB = 32}) =>
MachineResources(
memoryTotalBytes: totalGiB * 1024 * 1024 * 1024,
@@ -1427,7 +1426,7 @@ void main() {
'cwd': '/work/project',
'scope': 'swarm',
'engines': ['claude', 'codex', 'pi'],
- 'maxAgents': 4,
+ 'maxAgents': 8,
});
expect(f.connection.calls.where((c) => c.$1 == 'agent_create'), isEmpty);
expect(tester.takeException(), isNull);
@@ -1914,17 +1913,15 @@ void main() {
};
final c = await f.app.superTabs.open(tabId);
await c.refresh();
- // 8 GiB free: the two-gibibyte-per-agent arithmetic both this form and
- // the CLI's own suggestion use.
+ // 16 GiB total offers eight slots and suggests four, even with eight free.
await _openAddMachineDialog(
tester,
f,
c,
- readLocal: (_) async => _reading(freeGiB: 8),
+ readLocal: (_) async => _reading(totalGiB: 16, freeGiB: 8),
);
- // This machine's free memory says four, so the field opens on four
- // instead of making the owner count it out.
+ // Total memory suggests four, so the field opens there.
expect(_agentSlots(tester), '4');
expect(
find.text('Each new agent still needs free memory when it starts.'),
@@ -1972,6 +1969,99 @@ void main() {
},
);
+ for (final (totalGiB, suggested, maximum) in [
+ (32.0, 8, 16),
+ (16.0, 4, 8),
+ (64.0, 16, 16),
+ (2.0, 1, 1),
+ ]) {
+ testWidgets(
+ 'Add machine with $totalGiB GiB total offers $suggested of $maximum slots',
+ (tester) async {
+ final f = SuperTabLaunchFixture();
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Pilot');
+ final c = await f.app.superTabs.open(tabId);
+ await c.refresh();
+ await _openAddMachineDialog(
+ tester,
+ f,
+ c,
+ readLocal: (_) async => _reading(totalGiB: totalGiB, freeGiB: 1),
+ );
+
+ expect(_agentSlots(tester), '$suggested');
+ for (var slot = suggested; slot < maximum; slot++) {
+ await tester.tap(_slotsStep('more'));
+ await tester.pumpAndSettle();
+ }
+ expect(_agentSlots(tester), '$maximum');
+ expect(_slotsButton(tester, 'more').onPressed, isNull);
+ expect(tester.takeException(), isNull);
+
+ await tester.pumpWidget(const SizedBox());
+ await c.flush();
+ f.app.superTabs.dispose();
+ await tester.pump();
+ },
+ );
+ }
+
+ testWidgets(
+ 'Configure keeps the owner’s 12 slots even when total RAM offers eight',
+ (tester) async {
+ final f = SuperTabLaunchFixture();
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Pilot');
+ f.connection.server.state['machines'] = [
+ {'machineId': 'm', 'contributorId': 'owner', 'maxAgents': 12},
+ ];
+ final c = await f.app.superTabs.open(tabId);
+ await c.refresh();
+ await _openConfigureDialog(
+ tester,
+ f,
+ c,
+ readLocal: (_) async => _reading(totalGiB: 16, freeGiB: 1),
+ );
+
+ expect(_agentSlots(tester), '12');
+ expect(_slotsButton(tester, 'more').onPressed, isNull);
+ await tester.tap(find.widgetWithText(FilledButton, 'Save'));
+ await _settleSave(tester);
+ expect(f.connection.server.posts.single['command']!['maxAgents'], 12);
+ expect(tester.takeException(), isNull);
+
+ await tester.pumpWidget(const SizedBox());
+ await c.flush();
+ f.app.superTabs.dispose();
+ await tester.pump();
+ },
+ );
+
+ testWidgets('Configure keeps the owner’s slots when RAM cannot be read', (
+ tester,
+ ) async {
+ final f = SuperTabLaunchFixture();
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Pilot');
+ f.connection.server.state['machines'] = [
+ {'machineId': 'm', 'contributorId': 'owner', 'maxAgents': 12},
+ ];
+ final c = await f.app.superTabs.open(tabId);
+ await c.refresh();
+ await _openConfigureDialog(tester, f, c, readLocal: (_) async => null);
+
+ expect(_agentSlots(tester), '12');
+ expect(_slotsButton(tester, 'more').onPressed, isNull);
+ await tester.tap(find.widgetWithText(FilledButton, 'Save'));
+ await _settleSave(tester);
+ expect(f.connection.server.posts.single['command']!['maxAgents'], 12);
+ expect(tester.takeException(), isNull);
+
+ await tester.pumpWidget(const SizedBox());
+ await c.flush();
+ f.app.superTabs.dispose();
+ await tester.pump();
+ });
+
testWidgets(
'Configure starts at the machine’s own slots and saves the new number',
(tester) async {
@@ -2038,7 +2128,7 @@ void main() {
tester,
f,
c,
- readLocal: (_) async => _reading(freeGiB: 8),
+ readLocal: (_) async => _reading(totalGiB: 16, freeGiB: 8),
);
// The first attempt reaches the server and its reply is lost, which
// leaves that attempt holding its own receipt — the state the next press
@@ -2096,7 +2186,7 @@ void main() {
await tester.tap(find.widgetWithText(FilledButton, 'Add machine'));
await _settleSave(tester);
expect(find.byType(AlertDialog), findsNothing);
- expect(f.connection.server.posts.single['command']!['maxAgents'], 4);
+ expect(f.connection.server.posts.single['command']!['maxAgents'], 8);
expect(tester.takeException(), isNull);
await tester.pumpWidget(const SizedBox());
@@ -2160,34 +2250,31 @@ void main() {
},
);
- testWidgets('a machine over the range opens at 8, and 8 is what saves', (
+ testWidgets('a machine already set to 16 keeps that number when configured', (
tester,
) async {
final f = SuperTabLaunchFixture();
f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Pilot');
- // Contributed before this form had a range: the backend accepts 16, and
- // the dialog must not hand the owner a number it would then refuse.
+ // The backend accepts 16, and opening Configure must preserve that choice.
f.connection.server.state['machines'] = [
{'machineId': 'm', 'contributorId': 'owner', 'maxAgents': 16},
];
final c = await f.app.superTabs.open(tabId);
await c.refresh();
- await _openConfigureDialog(tester, f, c);
+ await _openConfigureDialog(
+ tester,
+ f,
+ c,
+ readLocal: (_) async => _reading(totalGiB: 32, freeGiB: 1),
+ );
- expect(_agentSlots(tester), '8');
- // The top is the top: the button is dead, so no press can make it nine.
+ expect(_agentSlots(tester), '16');
expect(_slotsButton(tester, 'more').onPressed, isNull);
expect(_slotsButton(tester, 'fewer').onPressed, isNotNull);
- // Saving quietly drops a number the owner chose on a machine that still
- // has it, so the form says so instead of doing it in silence.
- expect(
- find.textContaining('This machine was set to 16 agent slots'),
- findsOneWidget,
- );
await tester.tap(find.widgetWithText(FilledButton, 'Save'));
await _settleSave(tester);
- // The 16 the machine was stored with never leaves the dialog.
+ // The owner’s chosen 16 is still sent unchanged.
expect(f.connection.server.posts.single['command'], {
'type': 'machine.contribute',
'machineId': 'm',
@@ -2195,7 +2282,7 @@ void main() {
'cwd': '/work/project',
'scope': 'swarm',
'engines': ['claude', 'codex', 'pi'],
- 'maxAgents': 8,
+ 'maxAgents': 16,
});
expect(tester.takeException(), isNull);
@@ -2205,7 +2292,9 @@ void main() {
await tester.pump();
});
- testWidgets('Agent slots stop at 1 and stop at 8', (tester) async {
+ testWidgets('Agent slots stop at 1 and the machine’s eight-slot RAM limit', (
+ tester,
+ ) async {
final f = SuperTabLaunchFixture();
f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Pilot');
f.connection.server.state['machines'] = [
@@ -2213,7 +2302,12 @@ void main() {
];
final c = await f.app.superTabs.open(tabId);
await c.refresh();
- await _openConfigureDialog(tester, f, c);
+ await _openConfigureDialog(
+ tester,
+ f,
+ c,
+ readLocal: (_) async => _reading(totalGiB: 16, freeGiB: 1),
+ );
expect(_agentSlots(tester), '3');
for (var i = 0; i < 5; i++) {