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.

Local model manager: the door reads as a conversation, the skill asks in plain words

Tima0f7c8f98026
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 193bff08e..3459f7872 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -3402,9 +3402,9 @@ class AppNotifier extends ChangeNotifier {
/// What the pane is called before, and if never, the engine names its
/// session.
- static const localModelAgentName = 'Local models manager';
+ static const localModelAgentName = 'Local model manager';
- /// The one action behind every "Run a local model" entry: explain once,
+ /// The one action behind every "Talk to Local model manager" entry: explain once,
/// then open opencode as the agent that starts one.
///
/// Runs on the computer the app is on ([MachineState.isLocalMachine]) — a
diff --git a/desktop/lib/widgets/grid_model_picker.dart b/desktop/lib/widgets/grid_model_picker.dart
index 771eb9834..8871b6031 100644
--- a/desktop/lib/widgets/grid_model_picker.dart
+++ b/desktop/lib/widgets/grid_model_picker.dart
@@ -36,7 +36,7 @@ class GridModelPicker extends StatefulWidget {
/// have to know a command for.
final VoidCallback? onUseOwnLogin;
- /// Called when the last row under Local — "Run a local model" — is chosen. An action, not a
+ /// Called when the last row under Local — "Talk to Local model manager" — is chosen. An action, not a
/// destination: it opens the flow that puts a model on the user's own computer, which is the
/// answer to the empty section this menu otherwise stops at. Always offered, whether or not
/// anything is being served yet: a person with no Local models is exactly who needs the door.
@@ -100,6 +100,14 @@ class _GridModelPickerState extends State<GridModelPicker> {
/// Closes the menu this control has open, if any. Set while one is showing.
void Function()? _close;
+ /// The answer the OPEN menu is drawing, and the overlay entry drawing it. Both set only while a
+ /// menu is showing. A refresh that lands while the menu is open swaps the first and rebuilds
+ /// the second, so a model that came up since the last open appears in THIS one rather than the
+ /// next — a person who just started a model and opened the picker is looking for exactly that
+ /// row, and a menu that showed it only on a second click read as the model not being there.
+ GridModels? _shown;
+ OverlayEntry? _entry;
+
@override
void dispose() {
// A pane can go away under an open menu — closed, moved, or its swarm switched — and an overlay
@@ -141,7 +149,8 @@ class _GridModelPickerState extends State<GridModelPicker> {
final GridModels answer;
if (_last != null) {
answer = _last!;
- unawaited(_prefetch());
+ // The refresh lands INTO the open menu, not only into the memo for the next one.
+ unawaited(_prefetch().then((_) => _refreshOpenMenu()));
await _show(answer);
return;
}
@@ -167,6 +176,7 @@ class _GridModelPickerState extends State<GridModelPicker> {
/// the same menu as a cold one rather than a second copy of it.
Future<void> _show(GridModels answer) async {
if (!mounted) return;
+ _shown = answer;
final box = context.findRenderObject() as RenderBox?;
final overlay =
@@ -205,19 +215,19 @@ class _GridModelPickerState extends State<GridModelPicker> {
// refuses the move) is told so here, instead of being offered rows whose click would do
// nothing. The daemon names the capable engines beside the list; an older daemon names
// none, and then every row is offered as before.
- if (!answer.canRunLocally(widget.engineLabel))
+ if (!_shown!.canRunLocally(widget.engineLabel))
_empty(
'${engineIdentity(widget.engineLabel).label} can only run on its own login.',
)
// Two different facts, two sentences. "We could not ask" and "this account has no grid"
// send a person to two different places, and the one that used to cover both told a
// signed-in user to sign in again. "The grid is serving nothing" is NOT a sentence here:
- // the "Run a local model" row that ends this section is the answer, and a line saying the
+ // the "Talk to Local model manager" row that ends this section is the answer, and a line saying the
// list is empty above an empty list is noise.
- else if (answer.models.isEmpty && _emptySentence(answer) != null)
- _empty(_emptySentence(answer)!),
- if (answer.canRunLocally(widget.engineLabel))
- for (final model in answer.models)
+ else if (_shown!.models.isEmpty && _emptySentence(_shown!) != null)
+ _empty(_emptySentence(_shown!)!),
+ if (_shown!.canRunLocally(widget.engineLabel))
+ for (final model in _shown!.models)
_item(
onTap: () => close(_Choice.model(model)),
child: _Row(
@@ -235,7 +245,7 @@ class _GridModelPickerState extends State<GridModelPicker> {
// Offered whatever THIS pane's engine can do: it opens a new pane, on an engine that can.
_item(
onTap: () => close(const _Choice.runLocalModel()),
- child: const _Row(selected: false, title: 'Run a local model'),
+ child: const _Row(selected: false, title: 'Talk to Local model manager'),
),
],
);
@@ -259,7 +269,7 @@ class _GridModelPickerState extends State<GridModelPicker> {
/// account. Folding them together is what put "sign in again to set them up" in front of a
/// signed-in user whose daemon happened to be offline — advice that was wrong, and that would
/// not have helped even if the diagnosis had been right. A reachable grid serving nothing says
- /// nothing (null): the "Run a local model" row under it is what a person does about that.
+ /// nothing (null): the "Talk to Local model manager" row under it is what a person does about that.
String? _emptySentence(GridModels answer) {
if (!answer.reachable) return 'Could not reach this machine.';
if (answer.gridName == null) return 'No local models on this account yet.';
@@ -292,6 +302,8 @@ class _GridModelPickerState extends State<GridModelPicker> {
closed = true;
deregister();
entry.remove();
+ _entry = null;
+ _shown = null;
if (!completer.isCompleted) completer.complete(choice);
}
@@ -345,13 +357,49 @@ class _GridModelPickerState extends State<GridModelPicker> {
],
),
);
+ _entry = entry;
overlayState.insert(entry);
return completer.future.whenComplete(() => _close = null);
}
+ /// Redraw the open menu from the fresh memo, if the list changed under it. Nothing to do when
+ /// no menu is open, or when the refresh said what the menu already shows — a rebuild for an
+ /// identical list would only flicker the hover.
+ void _refreshOpenMenu() {
+ final entry = _entry;
+ final fresh = _last;
+ final shown = _shown;
+ if (!mounted || entry == null || fresh == null || shown == null) return;
+ if (_sameAnswer(fresh, shown)) return;
+ _shown = fresh;
+ entry.markNeedsBuild();
+ }
+
+ static bool _sameAnswer(GridModels a, GridModels b) {
+ if (a.reachable != b.reachable || a.gridName != b.gridName) return false;
+ if (a.models.length != b.models.length) return false;
+ for (var i = 0; i < a.models.length; i += 1) {
+ if (a.models[i].id != b.models[i].id ||
+ a.models[i].node != b.models[i].node)
+ return false;
+ }
+ return true;
+ }
+
/// One selectable row.
- Widget _item({required VoidCallback onTap, required Widget child}) =>
- InkWell(onTap: onTap, child: child);
+ ///
+ /// The hover is the SAME rectangle as the selected fill — inset by [_menuInset] and rounded the
+ /// same — so a row looks like one thing whether the pointer is on it or the agent is. An InkWell
+ /// around the whole item painted edge to edge and square, over a selected fill that was neither,
+ /// and the two reading as different shapes made the current row look like the odd one out.
+ Widget _item({required VoidCallback onTap, required Widget child}) => Padding(
+ padding: const EdgeInsets.symmetric(horizontal: _menuInset),
+ child: InkWell(
+ onTap: onTap,
+ borderRadius: BorderRadius.circular(_rowRadius),
+ child: child,
+ ),
+ );
/// A line that states something rather than offering it — no hover, no tap.
Widget _empty(String text) => Padding(
@@ -506,16 +554,15 @@ class _Row extends StatelessWidget {
],
);
return Container(
- // The highlight is the row, so it needs the row's own inset rather than the item's padding —
- // which is why the `PopupMenuItem`s around these set `padding: EdgeInsets.zero`.
- margin: const EdgeInsets.symmetric(horizontal: _menuInset),
+ // No margin of its own: the inset is the item's (see `_item`), so that the hover the item
+ // paints and the fill this row paints are one and the same rectangle.
padding: const EdgeInsets.symmetric(horizontal: _rowPadding, vertical: 5),
decoration: selected
// Subtle on purpose: one row in the menu is already the current one, and a mark loud
// enough to announce that would compete with the thing a person opened the menu to read.
? BoxDecoration(
color: AppColors.selected,
- borderRadius: BorderRadius.circular(5),
+ borderRadius: BorderRadius.circular(_rowRadius),
)
: null,
// The subtitle sits INSIDE the fill, under the title: it is about this row, and a sentence
@@ -546,6 +593,9 @@ class _Row extends StatelessWidget {
const double _menuInset = 6;
const double _rowPadding = 8;
+/// One radius for the hover and the selected fill: they are the same shape.
+const double _rowRadius = 5;
+
/// One row's meaning: a grid model, the engine's own login, or the action that starts a local
/// model. A sealed set rather than a nullable `GridModel`, because `null` already means "the menu
/// was dismissed" in `showMenu`'s own result — and the action is neither a model nor a login, so
diff --git a/desktop/lib/widgets/run_local_model_dialog.dart b/desktop/lib/widgets/run_local_model_dialog.dart
index 9f03ad7ed..2d75d68ee 100644
--- a/desktop/lib/widgets/run_local_model_dialog.dart
+++ b/desktop/lib/widgets/run_local_model_dialog.dart
@@ -24,6 +24,11 @@ Future<({bool skipNextTime})?> showRunLocalModelDialog(
String machineId,
) => showAppDialog<({bool skipNextTime})>(
context: context,
+ // Lighter than the app's default veil: this is a two-second yes/no in front
+ // of the swarm the person was just looking at, not a screen of its own, and
+ // the 90% default read as the window going dark. The blur stays, so what is
+ // behind is felt rather than read. Same weight the swarm rename uses.
+ veilTint: const Color(0x99000000),
builder: (_) =>
_RunLocalModelDialog(notifier: notifier, machineId: machineId),
);
@@ -105,18 +110,30 @@ class _RunLocalModelDialogState extends State<_RunLocalModelDialog> {
null => null,
};
return AlertDialog(
- title: const Text('A model that lives on your machine'),
+ title: const Text('Models that live on your machine'),
content: SizedBox(
width: 440,
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
children: [
- Text(
- "Say what you'll use it for. Harness picks one that fits "
- "this computer, brings it down, and starts it. Once it's "
- "running, switch to it in any agent you want, right from "
- "that agent's model picker.",
+ Text.rich(
+ TextSpan(
+ children: [
+ const TextSpan(
+ text: 'Local model manager',
+ style: TextStyle(fontWeight: FontWeight.w600),
+ ),
+ const TextSpan(
+ text:
+ " is an agent that looks after the models on this "
+ "computer. Say what you need and it helps you pick "
+ "one that fits both this machine and the work, then "
+ "sets it up for you. Once one is up, pick it in any "
+ "agent's model picker.",
+ ),
+ ],
+ ),
style: TextStyle(
fontFamily: grid.AppFont.sans,
fontSize: 13.5,
diff --git a/desktop/macos/Runner/SwarmTitlebar.swift b/desktop/macos/Runner/SwarmTitlebar.swift
index ca126f614..71e3f684c 100644
--- a/desktop/macos/Runner/SwarmTitlebar.swift
+++ b/desktop/macos/Runner/SwarmTitlebar.swift
@@ -434,7 +434,7 @@ final class SwarmTitlebar: NSObject, NSMenuItemValidation, NSMenuDelegate {
// section returns when there is a real source for it, not before.
modelsMenu.addItem(.separator())
section("Local")
- // Nothing served is not said: the "Run a local model" row that ends this section is the
+ // Nothing served is not said: the "Talk to Local model manager" row that ends this section is the
// answer, and an empty-list sentence above an empty list is noise.
do {
for (id, node) in localModels {
@@ -458,7 +458,7 @@ final class SwarmTitlebar: NSObject, NSMenuItemValidation, NSMenuDelegate {
// they want is not there yet, so it sits in the same list rather than in a section of its own.
// It replaces the `Add Model` placeholder that dispatched nothing, and is wired like Link
// Machine…, through the guarded channel handler. Present whether or not anything is served.
- let run = NSMenuItem(title: "Run a local model", action: #selector(menuAction(_:)), keyEquivalent: "")
+ let run = NSMenuItem(title: "Talk to Local model manager", action: #selector(menuAction(_:)), keyEquivalent: "")
run.target = self
run.representedObject = "runLocalModel"
run.identifier = NSUserInterfaceItemIdentifier(HarnessKeymapMenu.actionPrefix + "runLocalModel")
diff --git a/desktop/test/grid_model_picker_test.dart b/desktop/test/grid_model_picker_test.dart
index e75f9a223..cc2d54860 100644
--- a/desktop/test/grid_model_picker_test.dart
+++ b/desktop/test/grid_model_picker_test.dart
@@ -141,7 +141,7 @@ void main() {
// it already has. Only the middle one is about the ACCOUNT, and folding the first two together is
// what told a signed-in user to "sign in again" when the real problem was a daemon that had not
// answered: advice that was wrong, and useless even if the diagnosis had been right. The third
- // says nothing: the "Run a local model" row under Local is what a person does about it.
+ // says nothing: the "Talk to Local model manager" row under Local is what a person does about it.
testWidgets(
'a machine that did not answer says so, and does not blame the account',
(tester) async {
@@ -169,7 +169,7 @@ void main() {
await open(tester);
expect(find.text('Nothing is being served yet.'), findsNothing);
expect(find.text('Could not reach this machine.'), findsNothing);
- expect(find.text('Run a local model'), findsOneWidget);
+ expect(find.text('Talk to Local model manager'), findsOneWidget);
},
);
@@ -177,6 +177,39 @@ void main() {
// allow — a two-line menu wore the width of the longest model id it could ever hold. The minimum is
// what keeps a status off a model id; the maximum is a CEILING, not a target. One test each, because
// re-pumping reuses the State and the second open would answer from the first one's memo.
+ testWidgets('a model that came up since the last open appears in THIS open', (
+ tester,
+ ) async {
+ // A warm open draws the memo at once — that is what makes the click free — and used to leave
+ // the refresh for the NEXT open. A person who has just started a model and opens the picker is
+ // looking for exactly that row, so the refresh has to land in the menu that is showing.
+ final served = <Map<String, Object?>>[
+ {'id': 'Qwen3.5-4B', 'node': 'macbook'},
+ ];
+ notifier.dispose();
+ notifier = AppNotifier(
+ config: AppConfig.dev,
+ authSession: AuthSession(),
+ configStore: null,
+ connectionForTest: (_) => _Conn(served),
+ );
+ await open(tester);
+ expect(find.text('Qwen3.5-4B'), findsOneWidget);
+ expect(find.text('LFM2.5-8B'), findsNothing);
+
+ // Close, start another model on the grid, open again: the memo still says one model.
+ await tester.tapAt(const Offset(5, 5));
+ await tester.pumpAndSettle();
+ served.add({'id': 'LFM2.5-8B', 'node': 'macbook'});
+ await tester.tap(find.text('Model'));
+ await tester.pumpAndSettle();
+
+ expect(find.text('Qwen3.5-4B'), findsOneWidget);
+ expect(find.text('LFM2.5-8B'), findsOneWidget);
+ // Still one menu, redrawn — not a second one over the first.
+ expect(find.text('Local'), findsOneWidget);
+ });
+
testWidgets('a short menu is not as wide as the widest menu could be', (
tester,
) async {
@@ -424,10 +457,10 @@ void main() {
testWidgets('is there after the served models', (tester) async {
build(models: served);
await open(tester);
- expect(find.text('Run a local model'), findsOneWidget);
+ expect(find.text('Talk to Local model manager'), findsOneWidget);
// After the models, not among them: it is the way to get another one, and a row that
// started something sitting between two places the agent could go would read as a third.
- final row = tester.getTopLeft(find.text('Run a local model'));
+ final row = tester.getTopLeft(find.text('Talk to Local model manager'));
final model = tester.getTopLeft(find.text('Qwen-Test'));
expect(row.dy, greaterThan(model.dy));
});
@@ -438,8 +471,8 @@ void main() {
// The empty-state sentence is the sentence this row answers, so the row is under it — and it
// is there even with no grid, because a person with no Local models is exactly who needs it.
await open(tester);
- expect(find.text('Run a local model'), findsOneWidget);
- final row = tester.getTopLeft(find.text('Run a local model'));
+ expect(find.text('Talk to Local model manager'), findsOneWidget);
+ final row = tester.getTopLeft(find.text('Talk to Local model manager'));
final sentence = tester.getTopLeft(
find.text('No local models on this account yet.'),
);
@@ -464,7 +497,7 @@ void main() {
(rowFor('Qwen-Test').decoration as BoxDecoration?)?.color,
isNotNull,
);
- expect(rowFor('Run a local model').decoration, isNull);
+ expect(rowFor('Talk to Local model manager').decoration, isNull);
},
);
@@ -480,7 +513,7 @@ void main() {
onOwnLogin: () => logins++,
onSelected: (m) => picked = m,
);
- await tester.tap(find.text('Run a local model'));
+ await tester.tap(find.text('Talk to Local model manager'));
await tester.pumpAndSettle();
expect(runs, 1);
// Not a move: the agent stays where it was. `currentModel` is set so a stray own-login call
@@ -488,7 +521,7 @@ void main() {
expect(logins, 0);
expect(picked, isNull);
// The menu closed on the choice, like any other row.
- expect(find.text('Run a local model'), findsNothing);
+ expect(find.text('Talk to Local model manager'), findsNothing);
});
});
diff --git a/desktop/test/models_menu_test.dart b/desktop/test/models_menu_test.dart
index 7f781e2f8..6f8409392 100644
--- a/desktop/test/models_menu_test.dart
+++ b/desktop/test/models_menu_test.dart
@@ -15,7 +15,7 @@ import 'package:harness/ws/ws_conn.dart';
import 'swarm_state_test.dart' show createApp;
-/// Answers what the Run a local model dialog reads on opening and records the
+/// Answers what the Talk to Local model manager dialog reads on opening and records the
/// create it sends on Start. Anything else asked (the terminal the new pane
/// opens, say) is left pending, which is what a machine that has not answered
/// yet looks like — the same shape as the dialog's own test.
@@ -61,7 +61,7 @@ class _LocalModelConn extends WsConn {
'state': 'created',
'agent': {
'id': 'lm1',
- 'name': 'Local models manager',
+ 'name': 'Local model manager',
'engine': 'opencode',
},
});
@@ -353,7 +353,7 @@ void main() {
(_) => reply.complete(),
);
await tester.pumpAndSettle();
- expect(find.text('A model that lives on your machine'), findsOneWidget);
+ expect(find.text('Models that live on your machine'), findsOneWidget);
// Nothing is missing on this machine, so nothing about it is said.
expect(find.byKey(const Key('run-local-model-status')), findsNothing);
expect(conn.creates, isEmpty);
@@ -363,7 +363,7 @@ void main() {
// The handler answers only once the dialog is done, the way every
// dialog door does, so native focus is not handed back mid-dialog.
await reply.future;
- expect(find.text('A model that lives on your machine'), findsNothing);
+ expect(find.text('Models that live on your machine'), findsNothing);
final create = conn.creates.single;
expect(create['engine'], 'opencode');
expect(create['agent'], AppNotifier.localModelAgent);
diff --git a/desktop/test/run_local_model_dialog_test.dart b/desktop/test/run_local_model_dialog_test.dart
index f404ffb3d..a544688b1 100644
--- a/desktop/test/run_local_model_dialog_test.dart
+++ b/desktop/test/run_local_model_dialog_test.dart
@@ -1,4 +1,4 @@
-// The Run a local model dialog and the one action behind it: the copy, the machine line, the
+// The Talk to Local model manager dialog and the one action behind it: the copy, the machine line, the
// prerequisites that replace it, and what Start actually sends.
import 'dart:async';
import 'dart:io' show Platform;
@@ -74,7 +74,7 @@ class _Conn extends WsConn {
'state': 'created',
'agent': {
'id': 'lm1',
- 'name': 'Local models manager',
+ 'name': 'Local model manager',
'engine': 'opencode',
},
});
@@ -133,7 +133,7 @@ void main() {
child: TextButton(
key: const Key('door'),
onPressed: () => notifier.runLocalModel(context),
- child: const Text('Run a local model'),
+ child: const Text('Talk to Local model manager'),
),
),
),
@@ -153,12 +153,12 @@ void main() {
testWidgets('the copy is the plan\'s, and names no plumbing', (tester) async {
await open(tester);
- expect(find.text('A model that lives on your machine'), findsOneWidget);
+ expect(find.text('Models that live on your machine'), findsOneWidget);
expect(
find.text(
- "Say what you'll use it for. Harness picks one that fits this computer, brings it down, "
- "and starts it. Once it's running, switch to it in any agent you want, right from that "
- "agent's model picker.",
+ "Local model manager is an agent that looks after the models on this computer. Say what "
+ "you need and it helps you pick one that fits both this machine and the work, then sets "
+ "it up for you. Once one is up, pick it in any agent's model picker.",
),
findsOneWidget,
);
@@ -169,6 +169,9 @@ void main() {
// a computer. The app runs on Linux too.
expect(find.textContaining('grid'), findsNothing);
expect(find.textContaining('this Mac'), findsNothing);
+ // The body introduces the agent by name and never says the product's: the person is meeting
+ // Local model manager, not being told to go talk to Harness.
+ expect(find.textContaining('Harness'), findsNothing);
expect(find.textContaining('!'), findsNothing);
// No dashes of any kind in the copy: the owner's rule for this dialog.
expect(find.textContaining('—'), findsNothing);
@@ -212,7 +215,7 @@ void main() {
await tester.tap(find.byKey(const Key('run-local-model-not-now')));
await tester.pumpAndSettle();
- expect(find.text('A model that lives on your machine'), findsNothing);
+ expect(find.text('Models that live on your machine'), findsNothing);
expect(conn.creates, isEmpty);
expect(notifier.panes, isEmpty);
});
@@ -224,13 +227,13 @@ void main() {
await tester.tap(start);
await tester.pumpAndSettle();
- expect(find.text('A model that lives on your machine'), findsNothing);
+ expect(find.text('Models that live on your machine'), findsNothing);
final payload = conn.creates.single;
expect(payload['engine'], 'opencode');
// The pane IS the agent (`opencode --agent harness-compute`), and is titled before opencode
// reports a session title.
expect(payload['agent'], 'harness-compute');
- expect(payload['name'], 'Local models manager');
+ expect(payload['name'], 'Local model manager');
// No first message: the person opens the conversation, and the dialog says so.
expect(payload.containsKey('prompt'), isFalse);
// Home, not a project: a local model is not about any one repo.
@@ -275,7 +278,7 @@ void main() {
await tester.tap(find.byKey(const Key('door')));
await tester.pumpAndSettle();
- expect(find.text('A model that lives on your machine'), findsNothing);
+ expect(find.text('Models that live on your machine'), findsNothing);
expect(conn.creates, hasLength(2));
expect(conn.creates.last['agent'], 'harness-compute');
expect(conn.creates.last.containsKey('prompt'), isFalse);
@@ -291,7 +294,7 @@ void main() {
await tester.tap(find.byKey(const Key('door')));
await tester.pumpAndSettle();
- expect(find.text('A model that lives on your machine'), findsOneWidget);
+ expect(find.text('Models that live on your machine'), findsOneWidget);
});
testWidgets(
diff --git a/desktop/tool/swarm_titlebar_checks.swift b/desktop/tool/swarm_titlebar_checks.swift
index 8947862ce..b64caa472 100644
--- a/desktop/tool/swarm_titlebar_checks.swift
+++ b/desktop/tool/swarm_titlebar_checks.swift
@@ -781,7 +781,7 @@ private extension SwarmTitlebar {
let models = main.item(withTitle: "Models")!.submenu!
try checkTitlebar(models.items.filter { !$0.isSeparatorItem }.map(\.title) == [
"Subscription", "Anthropic, aabbcc, 12% remaining", "OpenAI, Not signed in",
- "Local", "Run a local model"
+ "Local", "Talk to Local model manager"
], "Models carries the two sections with something behind them, ending on the row that starts a model")
try checkTitlebar(models.items.filter(\.isSeparatorItem).count == 1,
"One native separator, between the sections — the run row is a Local row, not a section")
@@ -793,20 +793,20 @@ private extension SwarmTitlebar {
// last row of Local, in the same list as the models, enabled with nothing served, and dispatched
// through the same guarded handler as Link Machine… so a modal still swallows it.
let runLocal = models.items.last!
- try checkTitlebar(runLocal.title == "Run a local model",
+ try checkTitlebar(runLocal.title == "Talk to Local model manager",
"the last item in Models is the row that runs a local model")
try checkTitlebar(!models.items[models.items.count - 2].isSeparatorItem,
"the run row sits directly under the Local rows, with no separator of its own")
try checkTitlebar(runLocal.isEnabled && runLocal.submenu == nil,
- "Run a local model is enabled even when nothing is served, and opens no submenu")
+ "Talk to Local model manager is enabled even when nothing is served, and opens no submenu")
try checkTitlebar(runLocal.target === self && runLocal.action == #selector(menuAction(_:))
&& runLocal.representedObject as? String == "runLocalModel",
- "Run a local model dispatches runLocalModel through the guarded channel handler")
+ "Talk to Local model manager dispatches runLocalModel through the guarded channel handler")
try checkTitlebar(runLocal.identifier?.rawValue == HarnessKeymapMenu.actionPrefix + "runLocalModel",
- "Run a local model is identified for the keymap like every other Harness command")
- try checkTitlebar(validateMenuItem(runLocal), "Run a local model validates with the workspace live")
+ "Talk to Local model manager is identified for the keymap like every other Harness command")
+ try checkTitlebar(validateMenuItem(runLocal), "Talk to Local model manager validates with the workspace live")
actionsEnabled = false
- try checkTitlebar(!validateMenuItem(runLocal), "Run a local model cannot run behind a modal")
+ try checkTitlebar(!validateMenuItem(runLocal), "Talk to Local model manager cannot run behind a modal")
actionsEnabled = true
try checkTitlebar(!runLocal.title.lowercased().contains("grid") && !runLocal.title.contains("Mac"),
"the command names neither the plumbing nor one vendor's computer")
@@ -822,7 +822,7 @@ private extension SwarmTitlebar {
"a served model names the machine answering it")
try checkTitlebar(served.item(withTitle: "DeepSeek-V4-Flash") != nil,
"a model with no node named is listed on its own")
- try checkTitlebar(served.items.last?.title == "Run a local model"
+ try checkTitlebar(served.items.last?.title == "Talk to Local model manager"
&& !served.items[served.items.count - 2].isSeparatorItem
&& served.items.filter(\.isSeparatorItem).count == 1,
"the run row stays last in Local, directly under the served models, once models are served")
diff --git a/docs/plans/2026-09-16-001-run-local-model-entry-plan.md b/docs/plans/2026-09-16-001-run-local-model-entry-plan.md
index bb9c499d5..f5837020e 100644
--- a/docs/plans/2026-09-16-001-run-local-model-entry-plan.md
+++ b/docs/plans/2026-09-16-001-run-local-model-entry-plan.md
@@ -1,4 +1,4 @@
-# Run a local model: one button, one dialog, one agent that starts it
+# Talk to Local model manager: one button, one dialog, one agent that starts it
Status: proposed · 2026-09-16
Builds on: `2026-09-14-004-harness-grid-plan.md` (the private grid), `docs/skills/harness-compute.md`
@@ -160,11 +160,11 @@ says which.
### Change 4 — Desktop: the two doors
- **Pane picker** (`lib/widgets/grid_model_picker.dart`): a last row under Local, always present,
- after the models or after the empty-state sentence: **Run a local model** — drawn as a row, not a
+ after the models or after the empty-state sentence: **Talk to Local model manager** — drawn as a row, not a
header, and not tickable. Calls `onRunLocalModel`, a new callback `terminal_panel.dart` wires to
`notifier.runLocalModel()`.
- **Native Models menu** (`desktop/macos/Runner/SwarmTitlebar.swift`, `lib/screens/swarm_screen.dart`):
- after the Local section, a separator and an enabled item **Run a local model** dispatching
+ after the Local section, a separator and an enabled item **Talk to Local model manager** dispatching
`menuAction` `runLocalModel`; Dart maps it to `notifier.runLocalModel()` beside `newAgent`. The
macOS check script (`desktop/tool/swarm_titlebar_checks.swift`) asserts the item exists, is enabled,
and carries that action.
diff --git a/docs/skills/harness-compute.agent.md b/docs/skills/harness-compute.agent.md
index b2b1b06c6..77b1bbac1 100644
--- a/docs/skills/harness-compute.agent.md
+++ b/docs/skills/harness-compute.agent.md
@@ -7,7 +7,7 @@ permission:
question: allow
---
-You are **Local models manager** — the agent that gets a model running on this computer, under the user's Harness account, so every coding agent can switch to it from its model picker.
+You are **Local model manager** — the agent that gets a model running on this computer, under the user's Harness account, so every coding agent can switch to it from its model picker.
Everything you know about doing that is in the `harness-compute` skill. Load it before you do anything else, and follow it exactly: its ground rules (talk the way Harness talks; never say "grid" or hand the user a command; ask through a tool, not prose), its section 1 (start a local model, ending with where to pick it), and its section 2 (show what's running) when asked. You never edit this agent's config or add a provider: once the model answers, the picker is the hand-off.
diff --git a/docs/skills/harness-compute.md b/docs/skills/harness-compute.md
index cf15fb412..f4647917c 100644
--- a/docs/skills/harness-compute.md
+++ b/docs/skills/harness-compute.md
@@ -99,23 +99,43 @@ engine install` or `grid pull`. The one exception is `grid engine install` when
status` already shows the engine installed — that's a no-op, not a step, so it never needs
confirmation.
-**Step 1 — two questions, through a tool, before naming any model.** Skip either one the user
-already answered in the same breath.
-
- "What's it for?"
- - Coding
- - Chat and writing
- - Reading images
- - Just something fast
-
- "How much context do you want?"
- - 32K
- - 64K
- - 128K
- - As much as fits
-
-Suggest a default on the second based on the first — coding wants 128K (an agent burns context as
-a session grows), chat is fine at 32K. Both answers are what step 4 filters on.
+**Step 1 — three questions, through a tool, before naming any model.** Skip any the user already
+answered in the same breath. The person answering has never heard "context window" or "slot":
+every question carries one plain sentence saying what the answer changes for them, and every
+option says what it means in their terms, not in the engine's. Ask them as written — the
+explanation is part of the question, not an optional gloss.
+
+ "What will you mostly use it for?"
+ The kind of work decides which model is worth downloading.
+ - Coding — writing and editing code with an agent
+ - Chat and writing — questions, drafts, summaries
+ - Reading images — screenshots, photos, diagrams
+ - Just something fast — quick answers, speed over depth
+
+ "How much can it hold in its head at once?"
+ Its working memory for one conversation: your messages, files it has read, its own
+ replies. When that fills up, it starts forgetting the beginning. More costs memory on
+ this machine and makes it a little slower to answer.
+ - Short — around 20 pages of text. Fine for chat and quick questions. [32K]
+ - Medium — around 40 pages. Enough for most coding sessions. [64K]
+ - Long — around 80 pages. For big codebases and long agent sessions. [128K]
+ - As much as this machine can give it
+
+ "How many things will talk to it at the same time?"
+ Each one needs its own share of memory, reserved up front whether or not it is in use.
+ One is you in one agent; more is several agents, or people, hitting it together. When
+ every share is taken, the next request waits its turn.
+ - Just me, one agent at a time [1]
+ - Two agents at once [2]
+ - A few agents or people at once [4]
+
+The bracketed values are what the answers mean to the commands below; they are never shown.
+Suggest defaults from the first answer — coding wants Long (an agent burns context as a session
+grows), chat is fine at Short. Recommend "just me" on a laptop someone is also working on, two
+when they will run two agents on it. Every answer is used: purpose and context filter step 4,
+context and concurrency size step 5 — and together they decide whether the model fits at all.
+Whether the model can see is not asked here: it is a fact about the model, checked in step 4
+before anything is downloaded.
**Step 2 — know this machine's hardware before recommending anything.**
@@ -138,24 +158,83 @@ flag it downloads a prebuilt release, which is faster. Present both as the quest
recommend `--from-source` as the default, and stop — the command runs only after the answer comes
back, never in the message that asks.
-**Step 4 — the weights.**
+**Step 4 — the weights.** What is already on this disk comes first: a model downloaded last
+month is a model that needs no download today.
+
+ ls ~/.grid/models/*.gguf | grep -v '\.mmproj\.gguf$' # what is here already
+ grid ctx <file> --json # its context length
+
+Anything listed is usable as-is (`grid ctx` says how much it can hold; a `<stem>.mmproj.gguf`
+beside it means it reads images). If one or more fit what step 1 asked for, offer them through a
+tool FIRST — each as "already on this computer, no download", with what it is good at, how much
+it can hold and whether it reads images — alongside one option to fetch something new. The user
+picks; only a pick of "something new" goes on to the catalog. An empty folder skips this
+silently.
grid catalog --json # sized for THIS machine; the table isn't
grid pull unsloth/Qwen3.8-27B-GGUF:Qwen3.8-27B-UD-Q4_K_XL.gguf
-The JSON has what the pick is made from: `runnable`, `task`, `params_b`, and a `fit` block
-computed for this machine — `fit.version` (the quant that fits), `fit.size`, `fit.ctx` (the
-context it can serve with), `fit.est_tok_s`. Keep entries that are `runnable`, whose `fit.ctx`
-covers the context asked in step 1, and that suit the purpose (`task` for images; `fit.est_tok_s`
-for "fast"). Offer 2–3, through a tool, each with size, context and speed. Pull `fit.version`'s
-`pull_spec` unless the user named a quant. The download runs in the next turn, after the answer.
-
-**Step 5 — join.**
+The JSON has what the pick is made from: `runnable`, `params_b`, and a `fit` block computed for
+this machine — `fit.version` (the quant that fits), `fit.size`, `fit.ctx` (the context it can
+serve with), `fit.est_tok_s`. Keep entries that are `runnable`, whose `fit.ctx` covers the
+context asked in step 1, and that suit the purpose (`fit.est_tok_s` orders the shortlist for
+"fast"; it is never shown). Offer 2–3, through a tool, in the same plain terms step 1 used: what
+it is good at, the download size in GB, how much it can hold (pages, as step 1 put it), and
+whether it reads images. No speed figure, no quant name, no token count as the whole answer.
+Pull `fit.version`'s `pull_spec` unless the user named a quant. The download runs in the next
+turn, after the answer.
+
+**Vision is not in the catalog, so ask the repo before pulling.** Every catalog entry's
+`task` is `text-generation`; there is no field that says whether a model can see. The answer
+lives on Hugging Face: a vision repo ships its projector (`mmproj-*.gguf`) beside the weights,
+and that is exactly what `grid pull` looks for. Run this for each shortlisted `repo_id`, before
+offering it:
+
+ curl -sf "https://huggingface.co/api/models/<repo_id>" | python3 -c '
+ import json,sys
+ try: files=json.load(sys.stdin).get("siblings",[])
+ except Exception: print("unknown"); sys.exit()
+ n=[s["rfilename"] for s in files if s["rfilename"].endswith(".gguf") and "mmproj" in s["rfilename"].lower() and "/" not in s["rfilename"]]
+ print("mmproj: " + ", ".join(n) if n else "no mmproj")'
+
+The test is the FILE, not a word: `mmproj: mmproj-F16.gguf …` means the repo ships a projector
+and the model can see once it is served with it; `no mmproj` means text-only, whatever the
+model card says. Put that on each option ("reads images" / "text only") so the pick is made
+knowing it, and for a purpose of "Reading images" offer only repos with an mmproj. `unknown`
+means the site could not be asked (offline, rate-limited) — say so on the option rather than
+calling the model blind or sighted. On the pull itself, a vision model prints `Supports vision. Downloading
+<repo>/<projector> ...` and the projector lands beside the weights as `<model-stem>.mmproj.gguf`
+in `~/.grid/models`; that file is what step 5 checks.
+
+**Step 5 — join.** Two checks first, then the command.
+
+*Does it fit?* The engine reserves context × slots up front, before the first request:
+`--ctx-size` is per request, grid passes `ctx × slots` to the engine, and llama.cpp carves that
+pool into slots. 4 slots at 64K is 256K tokens of KV cache reserved on top of the weights, and
+an N this machine cannot hold fails to start instead of shrinking. Check the asked context ×
+concurrency against step 2's usable memory before joining. If it doesn't fit, say so and offer a
+smaller context or fewer slots, through a tool. That is why concurrency was a question and not a
+default.
+
+*Vision on?* Check it, don't remember it — one command, run every time, on the file step 4
+saved (`<stem>` is that filename without `.gguf`):
+
+ test -f ~/.grid/models/<stem>.mmproj.gguf && echo vision || echo text-only
+
+That file is the projector `grid pull` fetched beside the weights, and it is the exact thing the
+join looks for: present, the join enables vision on its own, and there is no flag to turn it off
+short of the file not being there. `vision` → ask, through a tool: "This model can read images.
+Serve it with vision on?" Recommend yes; the projector costs some extra memory. If the user says
+no, delete nothing — say in one line that vision rides on the projector file beside the model,
+and ask whether to move that file aside for this run. On yes, rename it yourself
+(`<stem>.mmproj.gguf.off`) and put it back when asked. `text-only` → say nothing about vision
+and go on. This is the on-disk half of step 4's check: the repo said vision, the pull fetched
+the projector, the file proves it — `grid ctx` reads only the context length and cannot.
grid join <grid> --serve Qwen3.8-27B-UD-Q4_K_XL.gguf \
--advertise-as Qwen3.8-27B \
--name this-machines-display-name \
- --max-concurrency 2 \
+ --max-concurrency 1 \
--ctx-size 128000
What each flag means, because two of them are easy to confuse:
@@ -165,17 +244,24 @@ What each flag means, because two of them are easy to confuse:
filename shows up instead, which nobody wants to read.
- `--name` is **this machine's** display name. A different thing from `--advertise-as`: one
names the model, the other names the computer.
- - `--max-concurrency` is how many requests this box takes at once. Keep it low (2) on a shared
- machine; higher on a dedicated GPU box.
+ - `--max-concurrency` is the step 1 answer: how many requests this machine takes at once.
+ `--parallel` is the engine's slot count; grid derives it from `--max-concurrency` when it
+ isn't given, so don't pass it. A request that arrives while every slot is busy waits — that
+ is what a user sees as "no answer" while another agent is mid-turn on the same model.
- `--ctx-size` is the context the user asked for in step 1 ("as much as fits" = that file's
`fit.ctx`), never above its `fit.max_ctx`. Always pass it: left off, the engine takes a 16K
default, and an agent's own prompt is bigger than that.
+ - Nothing for vision or chat templates: the projector is found on its own (`--mmproj FILE`
+ exists only to override with one fetched by hand), and the join turns the engine's chat
+ template support on itself.
-Ask before picking values not given — steps 1 and 2 already established intent and hardware, so
-there's no excuse to guess here.
+Ask before picking values not given — steps 1 and 2 already established intent, load and
+hardware, so there's no excuse to guess here.
-This returns as soon as the model is up; it keeps serving in the background. **Prove it answers
-before saying it's ready** — the join's exit code and `grid stats` only show it is listed:
+This returns as soon as the model is up; it keeps serving in the background. Its output says
+whether vision is on (`Vision: serving with projector <file>`) — report on or off from that
+line, not from what was intended. **Prove it answers before saying it's ready** — the join's
+exit code and `grid stats` only show it is listed:
grid chat --grid <grid> -m Qwen3.8-27B "say ok"
@@ -183,11 +269,12 @@ The `-m` is the `--advertise-as` name. A reply means the whole path works. No re
about context size, means it is not ready — fix it (see "When something fails") before telling
the user anything succeeded.
-Once the chat check passes, say it's ready and where to find it — the `--advertise-as` name is
-what the picker shows: "Qwen3.8-27B is running on this machine. Pick it from the model dropdown
-at the top of any agent's pane, or from the Models menu, and that agent switches to it." That's
-the end of this section. Don't offer to wire it into this agent, edit its config, or add a
-provider — Harness has already done the connecting, and the picker is the only step left.
+Once the chat check passes, say it's ready, whether it reads images, and where to find it — the
+`--advertise-as` name is what the picker shows: "Qwen3.8-27B is running on this machine, one
+request at a time, with vision on. Pick it from the model dropdown at the top of any agent's
+pane, or from the Models menu, and that agent switches to it." That's the end of this section.
+Don't offer to wire it into this agent, edit its config, or add a provider — Harness has already
+done the connecting, and the picker is the only step left.
**To stop it, don't name the command — offer to do it.** Say something like "tell me when you
want it stopped and I'll turn it off," never "stop it with `grid leave`." The user asking you to
@@ -232,6 +319,11 @@ repeat a raw line that names the underlying CLI.
`choices`") → the model was served with too small a window, usually `--ctx-size` left off.
Stop it and join again with the context the user asked for. The model is fine; only its
window was too small.
+ - **`Jinja Exception: System message must be at the beginning`** → some models' chat
+ templates refuse a system message after the first turn. Harness Compute's relay now hoists
+ system and developer messages to the front, so this means the relay this machine talks to
+ predates that fix. Say the model is fine and the path needs updating — nothing to change on
+ this machine.
- **The user says it isn't in the picker** → it is only there while it is being served. Run
`grid stats <grid> --verbose`; if this machine no longer lists it, start it again (section 1,
step 5 — the weights are still on disk, nothing to pull). If it is listed, tell them to open