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.

fix(desktop): say why an agent cannot move to a Local model instead of doing nothing

Kelvin755f98c61874
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 3fb9df6fa..ed22effc3 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -27,7 +27,7 @@ import { registry, projectDisplayName, type RegisteredSession } from './lib/regi
import { ENGINES, type AgentEngine } from './engines/types.js'
import { listDir } from './lib/fsBrowse.js'
import { linkCodexProfile, listCodexProfiles } from './lib/codexProfiles.js'
-import { parseGridLaunchOverride, type GridLaunchOverride } from './lib/gridLaunch.js'
+import { gridCapableEngines, parseGridLaunchOverride, type GridLaunchOverride } from './lib/gridLaunch.js'
import { listGridModels, resolveGridTarget } from './lib/gridModels.js'
import { readAccountUsage, type AccountUsageReading } from './lib/accountUsage.js'
import { probeEngines } from './lib/engineProbe.js'
@@ -1423,6 +1423,12 @@ export class BackendSocket {
reply(type, requestId, {
gridName: this.harnessGridName,
models: await listGridModels(this.harnessGridName),
+ // Which engines a Local model can be offered to at all. Static per CLI version — it is
+ // the set of launch contracts in `gridLaunch.ts` — and answered here, beside the list,
+ // so the picker can say "Cursor runs only on its own login" instead of offering a row
+ // whose retarget the daemon would refuse. An older app ignores the field; an older
+ // daemon omits it, which the app reads as "offer everything", as before.
+ localModelEngines: gridCapableEngines(),
})
return
}
diff --git a/desktop/lib/core/models.dart b/desktop/lib/core/models.dart
index bb4528d97..d94cc5893 100644
--- a/desktop/lib/core/models.dart
+++ b/desktop/lib/core/models.dart
@@ -493,5 +493,23 @@ class GridModels {
final String? gridName;
final List<GridModel> models;
- const GridModels({required this.gridName, required this.models});
+ /// The engines a Local model can be offered to at all, as the daemon on that machine names them
+ /// (`localModelEngines`; the set of launch contracts in its `gridLaunch.ts`). Null when the
+ /// daemon is older and sends no such list — read as "offer everything", the behaviour before.
+ final Set<String>? localModelEngines;
+
+ const GridModels({
+ required this.gridName,
+ required this.models,
+ this.localModelEngines,
+ });
+
+ /// Whether [engine] may be pointed at one of [models]: unknown engines are refused only when the
+ /// daemon gave a list — a picker that guessed would refuse the wrong ones on an older daemon.
+ bool canRunLocally(String? engine) {
+ final capable = localModelEngines;
+ if (capable == null) return true;
+ final id = engine?.trim().toLowerCase();
+ return id != null && capable.contains(id);
+ }
}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 8763eda67..22dd459c0 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -25,7 +25,7 @@ import '../settings/config_store.dart';
import '../stats/harness_stats.dart';
import '../terminal/terminal_session.dart';
import '../terminal/remote_media_download.dart';
-import '../widgets/engine_identity.dart' show allEngines;
+import '../widgets/engine_identity.dart' show allEngines, engineIdentity;
import 'dial_status.dart';
import 'pane_layout_store.dart';
import 'terminal_pane.dart';
@@ -34,6 +34,7 @@ import '../terminal/terminal_binary.dart';
import '../update/desktop_updater.dart';
import '../update/manual_update_check.dart';
import '../ws/ws_conn.dart';
+import 'retarget_refusal.dart';
import '../ws/local_cli_discovery.dart';
import '../ws/ws_pool.dart';
import 'pane_preset.dart';
@@ -3063,12 +3064,28 @@ class AppNotifier extends ChangeNotifier {
payload: {'agentId': agentId, 'clearGrid': true},
timeout: const Duration(seconds: 30),
);
+ } on WsRequestFailure catch (failure) {
+ _reportRetargetRefusal(machineId, agentId, failure.code);
} catch (_) {
- // The daemon owns the refusal (a busy pane, a launch that would not start) and the pane shows
- // it; a second error surface here would tell one story twice.
+ // A transport failure or a timeout: the daemon may well have done the move, and the frame
+ // that follows says where the agent is. A guess here would tell a story the pane contradicts.
}
}
+ /// A refusal happens BEFORE the daemon touches the pane — an engine with no way onto a Local
+ /// model, a busy agent, a machine that cannot resolve its Local models — so nothing in the
+ /// terminal ever says why, and until this existed the click simply did nothing. One sentence, in
+ /// the app's own words (`retargetRefusalMessage`); the daemon's detail names the grid.
+ void _reportRetargetRefusal(String machineId, String agentId, String code) {
+ final agent = machineStates[machineId]?.agents
+ .where((a) => a.id == agentId)
+ .firstOrNull;
+ final label = engineIdentity(agent?.engine).label;
+ _lastError = retargetRefusalMessage(code, engineLabel: label);
+ _lastErrorRetryable = false;
+ notifyListeners();
+ }
+
/// Point one agent at a model on the account's private grid.
///
/// Sends the model id and nothing else: the daemon on that machine resolves the endpoint and the
@@ -3086,9 +3103,10 @@ class AppNotifier extends ChangeNotifier {
payload: {'agentId': agentId, 'gridModel': modelId},
timeout: const Duration(seconds: 30),
);
+ } on WsRequestFailure catch (failure) {
+ _reportRetargetRefusal(machineId, agentId, failure.code);
} catch (_) {
- // The daemon answers its own refusals (a busy pane, an unreachable grid) and the pane shows
- // what actually happened; a second error surface here would be a second story about one act.
+ // See `clearAgentGrid`: a transport failure is not a refusal, and the next frame is the truth.
}
}
@@ -3114,7 +3132,14 @@ class AppNotifier extends ChangeNotifier {
))
.where((m) => m.id.isNotEmpty)
.toList();
- return GridModels(gridName: response['gridName'] as String?, models: models);
+ final capable = response['localModelEngines'];
+ return GridModels(
+ gridName: response['gridName'] as String?,
+ models: models,
+ localModelEngines: capable is List
+ ? capable.whereType<String>().map((e) => e.toLowerCase()).toSet()
+ : null,
+ );
} catch (_) {
return const GridModels(gridName: null, models: []);
}
diff --git a/desktop/lib/state/retarget_refusal.dart b/desktop/lib/state/retarget_refusal.dart
new file mode 100644
index 000000000..d2960c446
--- /dev/null
+++ b/desktop/lib/state/retarget_refusal.dart
@@ -0,0 +1,42 @@
+/// What the app says when the daemon refuses to move an agent to another model.
+///
+/// One sentence per refusal, in the app's own words. The daemon's `detail` is not shown: it is
+/// written for its log and names the grid, and the user's vocabulary is "Subscription" and "Local".
+/// Every code the daemon's `agent_retarget` can answer with is here, and an unknown one still gets a
+/// sentence rather than the code — a new refusal in a newer daemon must not surface as `SOME_CODE`.
+///
+/// These refusals happen BEFORE the pane is touched (an engine with no way onto a Local model, a
+/// busy agent, a machine that cannot resolve its Local models), so nothing in the terminal ever
+/// says why. Until this existed, picking a Local model for a Cursor agent simply did nothing.
+library;
+
+String retargetRefusalMessage(String code, {required String engineLabel}) {
+ return switch (code) {
+ 'GRID_ENGINE_UNSUPPORTED' =>
+ '$engineLabel can only run on its own login, not a Local model.',
+ 'GRID_MODEL_REQUIRED' =>
+ '$engineLabel needs a model named to run on a Local model.',
+ 'GRID_UNAVAILABLE' =>
+ "Couldn't reach this machine's Local models. Try again in a moment.",
+ 'GRID_CONFIG_FAILED' =>
+ "Couldn't write $engineLabel's Local-model configuration on this machine.",
+ 'GRID_CLEAR_FAILED' =>
+ "Couldn't clear the Local-model settings from this agent's terminal.",
+ 'TMUX_TOO_OLD_FOR_GRID' => "This machine's tmux is too old to move an agent to a Local model. Update tmux there.",
+ 'TMUX_UNAVAILABLE' || 'TMUX_FAILED' =>
+ "This machine's tmux did not answer. Try again in a moment.",
+ 'AGENT_BUSY' =>
+ 'This agent is mid-turn. Let it finish, then choose the model again.',
+ 'AGENT_NOT_FOUND' ||
+ 'MISSING_AGENT_ID' => 'This agent is no longer on the machine.',
+ 'NO_ACTIVE_PROCESS' || 'RETARGET_UNSUPPORTED_BACKEND' =>
+ 'This agent cannot change model right now.',
+ 'RESPAWN_FAILED' =>
+ "$engineLabel did not start on the new model. The terminal shows what happened.",
+ 'INVALID_GRID' =>
+ "This machine's Local models could not be resolved. Sign in again on it.",
+ 'UNSUPPORTED_ON_REMOTE' ||
+ 'UNSUPPORTED' => 'Update the harness CLI on this machine to change models.',
+ _ => "Couldn't change this agent's model.",
+ };
+}
diff --git a/desktop/lib/widgets/grid_model_picker.dart b/desktop/lib/widgets/grid_model_picker.dart
index 224b8b9cf..734f6c8fc 100644
--- a/desktop/lib/widgets/grid_model_picker.dart
+++ b/desktop/lib/widgets/grid_model_picker.dart
@@ -191,10 +191,24 @@ class _GridModelPickerState extends State<GridModelPicker> {
),
const PopupMenuDivider(),
_header('Local'),
+ // An engine with no way onto a Local model (Cursor talks only to its own API; the daemon
+ // 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))
+ PopupMenuItem<_Choice>(
+ enabled: false,
+ height: 30,
+ padding: const EdgeInsets.only(left: _menuInset + _rowPadding),
+ child: Text(
+ '${engineIdentity(widget.engineLabel).label} can only run on its own login.',
+ style: TextStyle(fontSize: 11, color: AppColors.textSoft),
+ ),
+ )
// An empty grid and no grid at all are different facts, and each gets its own sentence: one
// is "nobody is serving yet", the other "there is nothing to serve on". A single "no models"
// would send a person looking in the wrong place.
- if (answer.models.isEmpty)
+ else if (answer.models.isEmpty)
PopupMenuItem<_Choice>(
enabled: false,
height: 30,
@@ -208,22 +222,23 @@ class _GridModelPickerState extends State<GridModelPicker> {
style: TextStyle(fontSize: 11, color: AppColors.textSoft),
),
),
- for (final model in answer.models)
- PopupMenuItem<_Choice>(
- value: _Choice.model(model),
- // Taller only for the current row carrying a sentence; every other row keeps its height
- // so the menu does not grow for a fact about one agent.
- height: _subtitleFor(model) != null ? 46 : 32,
- padding: EdgeInsets.zero,
- child: _Row(
- selected: widget.currentModel == model.id,
- title: model.id,
- // Which of the user's machines answers it — the part that makes a private grid
- // legible, and the reason `node` is carried through at all.
- status: model.node.isEmpty ? null : model.node,
- subtitle: _subtitleFor(model),
+ if (answer.canRunLocally(widget.engineLabel))
+ for (final model in answer.models)
+ PopupMenuItem<_Choice>(
+ value: _Choice.model(model),
+ // Taller only for the current row carrying a sentence; every other row keeps its
+ // height so the menu does not grow for a fact about one agent.
+ height: _subtitleFor(model) != null ? 46 : 32,
+ padding: EdgeInsets.zero,
+ child: _Row(
+ selected: widget.currentModel == model.id,
+ title: model.id,
+ // Which of the user's machines answers it — the part that makes a private grid
+ // legible, and the reason `node` is carried through at all.
+ status: model.node.isEmpty ? null : model.node,
+ subtitle: _subtitleFor(model),
+ ),
),
- ),
],
);
if (chosen == null) return;
diff --git a/desktop/test/grid_model_picker_test.dart b/desktop/test/grid_model_picker_test.dart
index 632fd6555..a8029f54c 100644
--- a/desktop/test/grid_model_picker_test.dart
+++ b/desktop/test/grid_model_picker_test.dart
@@ -13,7 +13,7 @@ import 'package:harness/ws/ws_conn.dart';
/// request's own 12-second timeout, and a spinner that never stops means `pumpAndSettle` never
/// returns — the test would be measuring the timeout rather than the menu.
class _Conn extends WsConn {
- _Conn(this.models)
+ _Conn(this.models, {this.localModelEngines})
: super(
wsBaseUrl: 'ws://fixture.invalid',
autonomousEnv: 'test',
@@ -26,23 +26,35 @@ class _Conn extends WsConn {
final List<Map<String, Object?>> models;
+ /// The daemon's list of engines a Local model can be offered to; null = an older daemon that
+ /// sends no such field.
+ final List<String>? localModelEngines;
+
@override
Future<Map<String, dynamic>> request(
String type, {
Map<String, dynamic> payload = const {},
Duration timeout = const Duration(seconds: 20),
- }) async => {'gridName': models.isEmpty ? null : 'someone-7f3a91c4', 'models': models};
+ }) async => {
+ 'gridName': models.isEmpty ? null : 'someone-7f3a91c4',
+ 'models': models,
+ if (localModelEngines != null) 'localModelEngines': localModelEngines,
+ };
}
void main() {
late AppNotifier notifier;
- void build({List<Map<String, Object?>> models = const []}) {
+ void build({
+ List<Map<String, Object?>> models = const [],
+ List<String>? localModelEngines,
+ }) {
notifier = AppNotifier(
config: AppConfig.dev,
authSession: AuthSession(),
configStore: null,
- connectionForTest: (_) => _Conn(models),
+ connectionForTest: (_) =>
+ _Conn(models, localModelEngines: localModelEngines),
);
}
@@ -53,6 +65,7 @@ void main() {
WidgetTester tester, {
String? currentModel,
GridWebSearch? webSearch,
+ String engine = 'claude',
VoidCallback? onOwnLogin,
ValueChanged<GridModel>? onSelected,
}) async {
@@ -65,7 +78,7 @@ void main() {
child: GridModelPicker(
notifier: notifier,
machineId: 'local',
- engineLabel: 'claude',
+ engineLabel: engine,
currentModel: currentModel,
webSearch: webSearch,
onUseOwnLogin: onOwnLogin,
@@ -231,4 +244,35 @@ void main() {
expect(find.textContaining('Web search'), findsNothing);
});
});
+
+ group('an engine that cannot run on a Local model', () {
+ const served = [
+ {'id': 'qwen/qwen3.6-35b-a3b', 'node': 'macbook-m1max'},
+ ];
+ const capable = ['claude', 'codex', 'opencode', 'hermes', 'grok', 'pi', 'copilot'];
+
+ testWidgets('is told so under Local, and offered no rows', (tester) async {
+ // The daemon refuses a Cursor retarget (`GRID_ENGINE_UNSUPPORTED`): Cursor Agent can only be
+ // re-pointed at another Cursor API. Offering the row anyway was a dead end that said nothing.
+ build(models: served, localModelEngines: capable);
+ GridModel? picked;
+ await open(tester, engine: 'cursor', onSelected: (m) => picked = m);
+ expect(find.text('Cursor can only run on its own login.'), findsOneWidget);
+ expect(find.text('qwen/qwen3.6-35b-a3b'), findsNothing);
+ expect(picked, isNull);
+ });
+
+ testWidgets('a capable engine still gets the rows', (tester) async {
+ build(models: served, localModelEngines: capable);
+ await open(tester, engine: 'codex');
+ expect(find.text('qwen/qwen3.6-35b-a3b'), findsOneWidget);
+ expect(find.textContaining('own login'), findsNothing);
+ });
+
+ testWidgets('an older daemon that names no engines offers everything, as before', (tester) async {
+ build(models: served);
+ await open(tester, engine: 'cursor');
+ expect(find.text('qwen/qwen3.6-35b-a3b'), findsOneWidget);
+ });
+ });
}
diff --git a/desktop/test/retarget_refusal_test.dart b/desktop/test/retarget_refusal_test.dart
new file mode 100644
index 000000000..12874f5c7
--- /dev/null
+++ b/desktop/test/retarget_refusal_test.dart
@@ -0,0 +1,122 @@
+// What the app says when the daemon refuses to move an agent to another model — one sentence per
+// refusal, in the app's own words: the daemon's `detail` is written for its log and names the grid.
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/state/retarget_refusal.dart';
+import 'package:harness/ws/ws_conn.dart';
+
+import 'swarm_state_test.dart' show createApp;
+
+/// A connection whose daemon refuses every `agent_retarget` with [code].
+class _Refusing extends WsConn {
+ _Refusing(this.code)
+ : super(
+ wsBaseUrl: 'ws://fixture.invalid',
+ autonomousEnv: 'test',
+ machineId: 'm',
+ accessTokenProvider: (_, _) async => '',
+ onAuthFailure: (_) {},
+ onEvent: (_) {},
+ onStatus: (_) {},
+ );
+ final String code;
+
+ @override
+ Future<Map<String, dynamic>> request(
+ String type, {
+ Map<String, dynamic> payload = const {},
+ Duration timeout = const Duration(seconds: 20),
+ }) async {
+ if (type == 'agent_retarget') {
+ throw WsRequestFailure(
+ responseType: 'agent_retarget_result',
+ code: code,
+ detail: 'cursor cannot run on grid kelvin-e2e: …', // the daemon's words, never shown
+ );
+ }
+ return {};
+ }
+}
+
+void main() {
+ test(
+ 'a refused retarget reaches the user as a sentence, naming the engine',
+ () async {
+ // The daemon refuses before touching the pane, so the pane says nothing; the app used to
+ // swallow the refusal too, and a click on a Local model for a Cursor agent did nothing at all.
+ final app = createApp(
+ connectionForTest: (_) => _Refusing('GRID_ENGINE_UNSUPPORTED'),
+ );
+ addTearDown(app.dispose);
+ app.machineStates['m']!.agents = const [
+ Agent(
+ id: 'c1',
+ name: 'BTC Price Search',
+ engine: 'cursor',
+ terminalAvailable: true,
+ ),
+ ];
+
+ await app.retargetAgentToGridModel('m', 'c1', 'qwen/qwen3.6-35b-a3b');
+
+ expect(
+ app.lastError,
+ 'Cursor can only run on its own login, not a Local model.',
+ );
+ expect(app.lastError, isNot(contains('grid')));
+ },
+ );
+
+ test('moving home is reported the same way', () async {
+ final app = createApp(connectionForTest: (_) => _Refusing('AGENT_BUSY'));
+ addTearDown(app.dispose);
+ await app.clearAgentGrid('m', 'a1');
+ expect(app.lastError, contains('mid-turn'));
+ });
+
+ test('names the engine that can only run on its own login', () {
+ expect(
+ retargetRefusalMessage('GRID_ENGINE_UNSUPPORTED', engineLabel: 'Cursor'),
+ 'Cursor can only run on its own login, not a Local model.',
+ );
+ });
+
+ test('a busy agent is asked to finish first', () {
+ expect(
+ retargetRefusalMessage('AGENT_BUSY', engineLabel: 'Claude Code'),
+ contains('finish'),
+ );
+ });
+
+ test(
+ 'every refusal the daemon can raise has a sentence, and none says "grid"',
+ () {
+ const codes = [
+ 'GRID_ENGINE_UNSUPPORTED',
+ 'GRID_MODEL_REQUIRED',
+ 'GRID_UNAVAILABLE',
+ 'GRID_CONFIG_FAILED',
+ 'GRID_CLEAR_FAILED',
+ 'TMUX_TOO_OLD_FOR_GRID',
+ 'TMUX_UNAVAILABLE',
+ 'TMUX_FAILED',
+ 'AGENT_BUSY',
+ 'AGENT_NOT_FOUND',
+ 'NO_ACTIVE_PROCESS',
+ 'RETARGET_UNSUPPORTED_BACKEND',
+ 'RESPAWN_FAILED',
+ 'INVALID_GRID',
+ 'MISSING_AGENT_ID',
+ 'UNSUPPORTED_ON_REMOTE',
+ 'UNSUPPORTED',
+ 'SOMETHING_NEW',
+ ];
+ for (final code in codes) {
+ final message = retargetRefusalMessage(code, engineLabel: 'Codex');
+ expect(message, isNotEmpty, reason: code);
+ expect(message.toLowerCase(), isNot(contains('grid')), reason: code);
+ expect(message, isNot(contains(code)), reason: code);
+ }
+ },
+ );
+}