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.

desktop: draw a harness agent as its harness

dee3b22b953bf62
diff --git a/desktop/assets/engine-icons/circuit.png b/desktop/assets/engine-icons/circuit.png
new file mode 100644
index 000000000..d623ffbc2
Binary files /dev/null and b/desktop/assets/engine-icons/circuit.png differ
diff --git a/desktop/assets/engine-icons/workshop.png b/desktop/assets/engine-icons/workshop.png
new file mode 100644
index 000000000..14b553a03
Binary files /dev/null and b/desktop/assets/engine-icons/workshop.png differ
diff --git a/desktop/lib/core/models.dart b/desktop/lib/core/models.dart
index f04bba77d..084621b84 100644
--- a/desktop/lib/core/models.dart
+++ b/desktop/lib/core/models.dart
@@ -1,6 +1,8 @@
/// Data models mirroring the backend/web types.
library;
+import 'package:flutter/foundation.dart' show immutable;
+
enum MachineAuthMode { managed, remote, self, provider }
enum ConnectionStatus { disconnected, connecting, connected, reconnecting }
@@ -132,6 +134,23 @@ class Agent {
final bool terminalAvailable;
final String? terminalUnavailableReason;
+ /// The domain-specific harness this agent was created from (`autonomous/circuit`), or
+ /// null for a plain engine. [engine] stays the BASE engine the process actually runs —
+ /// a DSH is a decoration on the session, never a second engine (see the DSH spec in
+ /// `dsh/spec/README.md`). Everything a person sees keys off this when it is set.
+ final String? dsh;
+
+ /// The harness's display name as the daemon read it off the manifest. Lets a DSH this
+ /// build has never heard of still show its own name rather than its id.
+ final String? dshName;
+
+ /// The URL of the harness's viewer for this agent, served on the agent's machine, or null
+ /// when there is none (yet). A change means the viewer pane must navigate.
+ final String? viewerUrl;
+
+ /// The harness's last verdict on this workspace, or null when it has not written one.
+ final AgentVerdict? verdict;
+
const Agent({
required this.id,
this.sessionId,
@@ -148,8 +167,18 @@ class Agent {
this.launchDetail,
this.terminalAvailable = false,
this.terminalUnavailableReason,
+ this.dsh,
+ this.dshName,
+ this.viewerUrl,
+ this.verdict,
});
+ /// What to draw this agent AS: its harness when it has one, else its engine.
+ String? get identityEngine => dsh ?? engine;
+
+ /// The name that goes with [identityEngine], for an id this build has no picture of.
+ String? get identityDisplayName => dsh != null ? dshName : engineDisplayName;
+
factory Agent.fromJson(Map<String, dynamic> j) {
final terminal = j['terminal'];
final terminalMap = terminal is Map
@@ -195,6 +224,10 @@ class Agent {
? null
: _safeLabel(terminalMap['reason']) ??
'terminal unavailable (no verified terminal pane)',
+ dsh: _safeDsh(j['dsh']),
+ dshName: _safeLabel(j['dshName']),
+ viewerUrl: _safeViewerUrl(j['viewerUrl']),
+ verdict: AgentVerdict.fromJson(j['verdict']),
);
}
@@ -214,8 +247,33 @@ class Agent {
launchDetail: launchDetail,
terminalAvailable: terminalAvailable,
terminalUnavailableReason: terminalUnavailableReason,
+ dsh: dsh,
+ dshName: dshName,
+ viewerUrl: viewerUrl,
+ verdict: verdict,
);
+ /// `owner/name`, exactly the shape the DSH manifest schema allows and nothing else — the
+ /// id names an install directory on the far machine and a picker tile here.
+ static String? _safeDsh(Object? raw) {
+ if (raw is! String || raw.isEmpty || raw.length > 129) return null;
+ return RegExp(r'^[a-z0-9][a-z0-9-]{0,63}/[a-z0-9][a-z0-9-]{0,63}$').hasMatch(raw)
+ ? raw
+ : null;
+ }
+
+ /// A loopback or plain http(s) URL the viewer pane may load. Anything else — a `file:`,
+ /// a `javascript:`, a string with control characters — is dropped rather than navigated
+ /// to, since this lands straight in a webview.
+ static String? _safeViewerUrl(Object? raw) {
+ if (raw is! String || raw.isEmpty || raw.length > 2048) return null;
+ if (RegExp(r'[\x00-\x1f\x7f\s]').hasMatch(raw)) return null;
+ final uri = Uri.tryParse(raw);
+ if (uri == null || !uri.hasAuthority) return null;
+ if (uri.scheme != 'http' && uri.scheme != 'https') return null;
+ return raw;
+ }
+
static String? _safeEngine(Object? raw) {
if (raw is! String || raw.isEmpty || raw.length > 64) return null;
return RegExp(r'^[a-zA-Z0-9._-]+$').hasMatch(raw) ? raw : null;
@@ -244,6 +302,75 @@ class Agent {
}
}
+/// A domain-specific harness's verdict on an agent's workspace, as the daemon read it off
+/// `.harness/verdict.json` (see `dsh/spec/README.md`). Counts rather than the findings
+/// themselves: the pane header has room for "3 errors", and the findings live in the
+/// harness's own viewer.
+@immutable
+class AgentVerdict {
+ const AgentVerdict({
+ required this.ready,
+ this.summary,
+ this.errors = 0,
+ this.warnings = 0,
+ this.artifact,
+ this.updatedAt,
+ });
+
+ /// The one machine fact: fab-ready, all gates passed, exam passed.
+ final bool ready;
+
+ /// One line for the header's tooltip.
+ final String? summary;
+ final int errors;
+ final int warnings;
+
+ /// Workspace-relative path of the primary thing to look at, when the harness named one.
+ final String? artifact;
+ final DateTime? updatedAt;
+
+ static AgentVerdict? fromJson(Object? raw) {
+ if (raw is! Map) return null;
+ final ready = raw['ready'];
+ if (ready is! bool) return null;
+ final updated = raw['updatedAt'];
+ return AgentVerdict(
+ ready: ready,
+ summary: _safeText(raw['summary'], 200),
+ errors: _safeCount(raw['errors']),
+ warnings: _safeCount(raw['warnings']),
+ artifact: _safeText(raw['artifact'], 1024),
+ updatedAt: updated is String ? DateTime.tryParse(updated) : null,
+ );
+ }
+
+ static int _safeCount(Object? raw) {
+ if (raw is! num || raw.isNaN || raw < 0) return 0;
+ return raw > 9999 ? 9999 : raw.toInt();
+ }
+
+ static String? _safeText(Object? raw, int max) {
+ if (raw is! String) return null;
+ final clean = raw.replaceAll(RegExp(r'[\u0000-\u001f\u007f]'), ' ').trim();
+ if (clean.isEmpty) return null;
+ return clean.length <= max ? clean : clean.substring(0, max);
+ }
+
+ @override
+ bool operator ==(Object other) =>
+ other is AgentVerdict &&
+ other.ready == ready &&
+ other.summary == summary &&
+ other.errors == errors &&
+ other.warnings == warnings &&
+ other.artifact == artifact &&
+ other.updatedAt == updatedAt;
+
+ @override
+ int get hashCode =>
+ Object.hash(ready, summary, errors, warnings, artifact, updatedAt);
+}
+
/// What the daemon answered when asked where a typed task belongs (⌘B).
///
/// `candidates` is the pick followed by EVERY other agent the daemon weighed — ranked where the router
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index 254c04748..8cd903b65 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -284,7 +284,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
?.agents
.where((agent) => agent.id == pane.agentId)
.firstOrNull
- ?.engine ??
+ ?.identityEngine ??
pane.session?.engineId;
}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index fb7f75297..84925f856 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -3008,7 +3008,11 @@ class AppNotifier extends ChangeNotifier {
prev.launchDetail != agent.launchDetail ||
prev.status != agent.status ||
prev.terminalAvailable != agent.terminalAvailable ||
- prev.terminalUnavailableReason != agent.terminalUnavailableReason) {
+ prev.terminalUnavailableReason != agent.terminalUnavailableReason ||
+ prev.dsh != agent.dsh ||
+ prev.dshName != agent.dshName ||
+ prev.viewerUrl != agent.viewerUrl ||
+ prev.verdict != agent.verdict) {
return false;
}
}
@@ -5276,7 +5280,7 @@ class AppNotifier extends ChangeNotifier {
historyId: 'closed-${_nextClosedHistoryId++}',
name: agent?.name ?? pane.session?.agentName ?? pane.agentId!,
machineName: machine?.machine.displayName ?? pane.machineId,
- engine: agent?.engine ?? pane.session?.engineId,
+ engine: agent?.identityEngine ?? pane.session?.engineId,
),
);
}
diff --git a/desktop/lib/state/swarm_attention.dart b/desktop/lib/state/swarm_attention.dart
index cf8406d2c..385dd706d 100644
--- a/desktop/lib/state/swarm_attention.dart
+++ b/desktop/lib/state/swarm_attention.dart
@@ -71,7 +71,7 @@ SwarmAttentionEntry _entry(
current: view?.current ?? false,
machineId: question.machineId,
agentId: question.agentId,
- engine: view?.engine ?? agent?.engine,
+ engine: view?.engine ?? agent?.identityEngine,
searchFields: [
...?view?.fields.skip(1),
if (view == null) machine?.machine.displayName ?? question.machineId,
diff --git a/desktop/lib/state/swarm_navigation.dart b/desktop/lib/state/swarm_navigation.dart
index 360e18185..c8776ffe6 100644
--- a/desktop/lib/state/swarm_navigation.dart
+++ b/desktop/lib/state/swarm_navigation.dart
@@ -416,7 +416,7 @@ class SwarmLocationCatalog {
final machine = app.machineStates[pane.machineId];
final project = agent == null ? null : machine?.projectOf(agent);
final machineLabel = machine?.machine.displayName ?? pane.machineId;
- final engine = agent?.engine ?? pane.session?.engineId;
+ final engine = agent?.identityEngine ?? pane.session?.engineId;
final detail = _harnessDetail(
project,
machineLabel,
@@ -834,7 +834,7 @@ List<SwarmDestination> swarmDestinations(
final machine = app.machineStates[machineId];
final project = row?.$1.projectOf(row.$2);
final machineName = machine?.machine.displayName ?? machineId;
- final engine = row?.$2.engine ?? pane?.session?.engineId;
+ final engine = row?.$2.identityEngine ?? pane?.session?.engineId;
final detail = _harnessDetail(
project,
machineName,
diff --git a/desktop/lib/widgets/agent_switcher.dart b/desktop/lib/widgets/agent_switcher.dart
index aaa4ba8a5..e03e46de7 100644
--- a/desktop/lib/widgets/agent_switcher.dart
+++ b/desktop/lib/widgets/agent_switcher.dart
@@ -332,11 +332,7 @@ class _Row extends StatelessWidget {
padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 9),
child: Row(
children: [
- EngineMark(
- engine: entry.agent.engine,
- displayName: entry.agent.engineDisplayName,
- size: 15,
- ),
+ EngineMark.forAgent(entry.agent, size: 15),
const SizedBox(width: 11),
Expanded(
child: Text(
diff --git a/desktop/lib/widgets/engine_identity.dart b/desktop/lib/widgets/engine_identity.dart
index 595fde858..2ef855f23 100644
--- a/desktop/lib/widgets/engine_identity.dart
+++ b/desktop/lib/widgets/engine_identity.dart
@@ -2,6 +2,7 @@ import 'dart:math' as math;
import 'package:flutter/material.dart';
+import '../core/models.dart';
import '../theme/app_theme.dart';
class EngineIdentity {
@@ -104,19 +105,62 @@ const _engines = <String, EngineIdentity>{
),
};
+/// The domain-specific harnesses this build has a picture of, keyed by their
+/// `owner/name` id — the same id the daemon puts on the wire as `dsh`.
+///
+/// A SEPARATE map from [_engines], and deliberately not part of [allEngines]:
+/// a harness runs ON one of those engines rather than beside them, so it must
+/// never be probed as one (`engines_probe`) or offered a bypass flag of its
+/// own. It is only a face. A harness absent here still draws — the daemon
+/// sends its name, and [engineIdentity] falls back to an initial.
+const _harnesses = <String, EngineIdentity>{
+ 'autonomous/circuit': EngineIdentity(
+ id: 'autonomous/circuit',
+ label: 'Circuit',
+ color: Color(0xffd2643a),
+ asset: 'assets/engine-icons/circuit.png',
+ ),
+ 'autonomous/workshop': EngineIdentity(
+ id: 'autonomous/workshop',
+ label: 'Workshop',
+ color: Color(0xffe09a3c),
+ asset: 'assets/engine-icons/workshop.png',
+ ),
+};
+
+/// The base engine each first-party harness runs on, so the Create dialog can
+/// say "Runs on Claude Code" — and send the right `engine` — before the machine
+/// has answered `dsh_list`. The daemon's catalog is authoritative when present.
+const knownHarnessBase = <String, String>{
+ 'autonomous/circuit': 'claude',
+ 'autonomous/workshop': 'codex',
+};
+
/// All known engines, in declaration order — for the New Agent engine picker.
List<EngineIdentity> get allEngines => _engines.values.toList(growable: false);
+/// The harnesses this build ships a face for, in declaration order.
+List<EngineIdentity> get knownHarnesses =>
+ _harnesses.values.toList(growable: false);
+
+/// Whether [id] names a domain-specific harness rather than an engine. The
+/// slash is the tell: engine ids are bare words, harness ids are `owner/name`.
+bool isHarnessId(String? id) => id != null && id.contains('/');
+
EngineIdentity engineIdentity(String? engine, {String? displayName}) {
final id = engine?.trim().toLowerCase() ?? '';
- final known = _engines[id];
+ final known = _engines[id] ?? _harnesses[id];
if (known != null) return known;
final raw = displayName?.trim().isNotEmpty == true
? displayName!.trim()
+ // An unknown harness reads by its name, never its owner: `someone/robot-arm`
+ // is a "Robot-arm" tile, and the owner is a fact for the install screen.
+ : isHarnessId(id)
+ ? id.substring(id.lastIndexOf('/') + 1)
: id.isEmpty
? 'Agent'
: id;
- final label = raw[0].toUpperCase() + raw.substring(1);
+ final label = raw.isEmpty ? 'Agent' : raw[0].toUpperCase() + raw.substring(1);
return EngineIdentity(
id: id.isEmpty ? 'unknown' : id,
label: label,
@@ -124,6 +168,15 @@ EngineIdentity engineIdentity(String? engine, {String? displayName}) {
);
}
+/// What an agent is drawn AS: its harness when it was created from one, else
+/// its engine. Every mark that has an [Agent] in hand goes through here, so a
+/// Circuit agent is Circuit in the rail, the header, the switcher and the tab
+/// alike — and so a new place to draw one cannot quietly show Claude instead.
+EngineIdentity agentIdentity(Agent agent) => engineIdentity(
+ agent.identityEngine,
+ displayName: agent.identityDisplayName,
+);
+
class EngineMark extends StatelessWidget {
final String? engine;
final String? displayName;
@@ -138,6 +191,15 @@ class EngineMark extends StatelessWidget {
this.size = 16,
});
+ /// The mark for [agent] — see [agentIdentity].
+ EngineMark.forAgent(
+ Agent agent, {
+ super.key,
+ this.enabled = true,
+ this.size = 16,
+ }) : engine = agent.identityEngine,
+ displayName = agent.identityDisplayName;
+
@override
Widget build(BuildContext context) {
final identity = engineIdentity(engine, displayName: displayName);
diff --git a/desktop/lib/widgets/machine_rail.dart b/desktop/lib/widgets/machine_rail.dart
index 2dda90352..e90e79251 100644
--- a/desktop/lib/widgets/machine_rail.dart
+++ b/desktop/lib/widgets/machine_rail.dart
@@ -1057,10 +1057,7 @@ class _AgentRowState extends State<_AgentRow> {
: !state.terminalCapabilityAvailable
? state.terminalCapabilityError
: null;
- final identity = engineIdentity(
- agent.engine,
- displayName: agent.engineDisplayName,
- );
+ final identity = agentIdentity(agent);
final processing = state.processingAgentIds.contains(agent.id);
// Right-click wraps the row rather than fighting it: SidebarItem owns the
// primary tap and the press/hover states that go with it, and exposes no
@@ -1139,9 +1136,8 @@ class _AgentRowState extends State<_AgentRow> {
child: Semantics(
label: '${identity.label} engine',
image: true,
- child: EngineMark(
- engine: agent.engine,
- displayName: agent.engineDisplayName,
+ child: EngineMark.forAgent(
+ agent,
enabled: visuallyEnabled,
size: 15,
),
@@ -1253,7 +1249,7 @@ class _AgentRowState extends State<_AgentRow> {
),
onDragEnd: (_) => agentDrag.value = null,
onDraggableCanceled: (_, _) => agentDrag.value = null,
- feedback: _DragChip(name: agent.name, engine: agent.engine),
+ feedback: _DragChip(name: agent.name, engine: agent.identityEngine),
// The row stays put and dims. Removing it would reflow the list under the
// pointer mid-drag, moving every other row out from under the place the
// hand had already aimed at.
diff --git a/desktop/lib/widgets/terminal_panel.dart b/desktop/lib/widgets/terminal_panel.dart
index c84bfef6a..a34dee92b 100644
--- a/desktop/lib/widgets/terminal_panel.dart
+++ b/desktop/lib/widgets/terminal_panel.dart
@@ -1513,7 +1513,28 @@ class _TerminalHeader extends StatelessWidget {
child: LayoutBuilder(
builder: (context, constraints) => Row(
children: [
- EngineMark(engine: session.engineId, size: 17),
+ if (agent != null)
+ EngineMark.forAgent(agent, size: 17)
+ else
+ EngineMark(engine: session.engineId, size: 17),
+ // A harness agent is drawn as its harness, but the process in the pane is still
+ // Claude or Codex — and that is the account being spent, so it stays visible: a
+ // small base-engine mark tucked against the harness's own.
+ if (agent?.dsh != null) ...[
+ const SizedBox(width: 3),
+ Tooltip(
+ message:
+ 'Runs on ${engineIdentity(session.engineId).label}',
+ child: Opacity(
+ opacity: .75,
+ child: EngineMark(
+ key: const ValueKey('pane-header-base-engine'),
+ engine: session.engineId,
+ size: 11,
+ ),
+ ),
+ ),
+ ],
const SizedBox(width: 10),
Expanded(
child: Row(
diff --git a/desktop/test/agent_model_test.dart b/desktop/test/agent_model_test.dart
index 2639120d4..5a75fadda 100644
--- a/desktop/test/agent_model_test.dart
+++ b/desktop/test/agent_model_test.dart
@@ -2,6 +2,7 @@ import 'package:flutter_test/flutter_test.dart';
import 'package:harness/core/models.dart';
void main() {
+ _dshTests();
test('uses explicit terminal availability from a new CLI', () {
final dormantPane = Agent.fromJson({
'id': 'agent-1',
@@ -60,3 +61,87 @@ void main() {
expect(agent.launchDetail, 'Engine exited see terminal');
});
}
+
+// ── domain-specific harness fields ────────────────────────────────────────────
+
+void _dshTests() {
+ test('parses the harness, viewer and verdict off an agent frame', () {
+ final agent = Agent.fromJson({
+ 'id': 'agent-1',
+ 'name': 'Board',
+ 'engine': 'claude',
+ 'dsh': 'autonomous/circuit',
+ 'dshName': 'Circuit',
+ 'viewerUrl': 'http://127.0.0.1:4179/?workspace=1',
+ 'verdict': {
+ 'ready': false,
+ 'summary': '2 errors, 1 warning',
+ 'errors': 2,
+ 'warnings': 1,
+ 'artifact': 'boards/main.board.json',
+ 'updatedAt': '2026-09-14T20:00:00Z',
+ },
+ });
+ expect(agent.engine, 'claude');
+ expect(agent.dsh, 'autonomous/circuit');
+ expect(agent.dshName, 'Circuit');
+ expect(agent.identityEngine, 'autonomous/circuit');
+ expect(agent.identityDisplayName, 'Circuit');
+ expect(agent.viewerUrl, 'http://127.0.0.1:4179/?workspace=1');
+ final verdict = agent.verdict!;
+ expect(verdict.ready, isFalse);
+ expect(verdict.summary, '2 errors, 1 warning');
+ expect(verdict.errors, 2);
+ expect(verdict.warnings, 1);
+ expect(verdict.artifact, 'boards/main.board.json');
+ expect(verdict.updatedAt, DateTime.utc(2026, 9, 14, 20));
+ expect(agent.copyWith(name: 'Renamed').verdict, verdict);
+ expect(agent.copyWith(name: 'Renamed').dsh, 'autonomous/circuit');
+ });
+
+ test('a plain engine agent has none of them and draws as its engine', () {
+ final agent = Agent.fromJson({
+ 'id': 'agent-1',
+ 'name': 'a',
+ 'engine': 'codex',
+ });
+ expect(agent.dsh, isNull);
+ expect(agent.viewerUrl, isNull);
+ expect(agent.verdict, isNull);
+ expect(agent.identityEngine, 'codex');
+ });
+
+ test('refuses a harness id, viewer URL or verdict outside the spec shape', () {
+ Agent parse(Map<String, dynamic> extra) =>
+ Agent.fromJson({'id': 'agent-1', 'name': 'a', ...extra});
+ // The id is owner/name; a bare word, a deeper path, or an upper-case one is not.
+ expect(parse({'dsh': 'circuit'}).dsh, isNull);
+ expect(parse({'dsh': 'a/b/c'}).dsh, isNull);
+ expect(parse({'dsh': 'Autonomous/Circuit'}).dsh, isNull);
+ expect(parse({'dsh': 'autonomous/../etc'}).dsh, isNull);
+ // The viewer URL lands in a webview: http(s) with a host, no whitespace, no control bytes.
+ expect(parse({'viewerUrl': 'file:///etc/passwd'}).viewerUrl, isNull);
+ expect(parse({'viewerUrl': 'javascript:alert(1)'}).viewerUrl, isNull);
+ expect(parse({'viewerUrl': 'http://127.0.0.1:4179/a b'}).viewerUrl, isNull);
+ expect(parse({'viewerUrl': 'http://\n127.0.0.1/'}).viewerUrl, isNull);
+ expect(
+ parse({'viewerUrl': 'https://viewer.local/x'}).viewerUrl,
+ 'https://viewer.local/x',
+ );
+ // A verdict without the one required fact is no verdict; counts never go negative or absurd.
+ expect(parse({'verdict': {'summary': 'x'}}).verdict, isNull);
+ expect(parse({'verdict': 'ready'}).verdict, isNull);
+ final odd = parse({
+ 'verdict': {
+ 'ready': true,
+ 'errors': -3,
+ 'warnings': 1e9,
+ 'summary': 'ok\u0000\u0001',
+ },
+ }).verdict!;
+ expect(odd.errors, 0);
+ expect(odd.warnings, 9999);
+ expect(odd.summary, 'ok');
+ expect(odd.updatedAt, isNull);
+ });
+}