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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import 'dart:async';
import 'package:fake_async/fake_async.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/agent_messages/agent_messages.dart';
import 'package:harness/auth/auth_session.dart';
import 'package:harness/core/config.dart';
import 'package:harness/core/models.dart';
import 'package:harness/state/app_state.dart';
import 'package:harness/terminal/terminal_session.dart';
import 'support/agent_messages_api.dart';
/// Agent Messages as the window keeps it (docs/design/2026-10-10-agent-messages.md):
/// whether the account has them, the traffic `messages_changed` reports, the
/// pane marks it leaves, and a tab's log merged from every daemon that holds
/// part of it. A tab has no flag here: whether agents may message is the
/// account's, in Settings ▸ Experimental (owner, 2026-10-12).
class _Backend {
/// Each tab's old flag, which a backend still answers and nothing reads.
Map<String, bool> tabs = {};
int reads = 0;
Object? readError;
bool readNull = false;
Future<Map<String, dynamic>?> read() async {
reads++;
if (readError case final error?) throw error;
if (readNull) return null;
return {
'revision': 3,
'machines': const [],
'tabs': [
for (final MapEntry(:key, :value) in tabs.entries)
{'id': key, 'name': key, 'enabled': value, 'panes': const []},
],
};
}
}
Map<String, dynamic> _sent({
String tabId = 'tab',
String id = 'm0000001',
String to = 'api',
String state = 'queued',
}) => {
'tabId': tabId,
'messageId': id,
'at': 1,
'from': {'machineId': 'studio', 'agentId': 'lead'},
'to': [
{'machineId': 'laptop', 'agentId': to, 'state': state},
],
};
Map<String, dynamic> _row(
String id, {
required int at,
List<Map<String, Object?>> statuses = const [],
String text = 'Review of 3f2a9c1\nthe cleanup leaves workers running',
}) => {
'id': id,
'tabId': 'tab',
'from': {
'machineId': 'studio',
'agentId': 'lead',
'name': 'lead',
'engine': 'codex',
'machine': 'studio',
},
'to': [
{'machineId': 'laptop', 'agentId': 'api', 'name': 'api'},
],
'text': text,
'at': at,
'statuses': statuses,
};
void main() {
late _Backend backend;
final names = {'lead': 'Lead', 'api': 'API worker'};
AgentMessagesController controller({
AgentMessagesRequest? request,
AgentNameOf? nameOf,
}) => AgentMessagesController(
read: backend.read,
request: request ?? (_, _) async => throw StateError('offline'),
nameOf: nameOf ?? (_, agentId) => names[agentId],
);
setUp(() {
backend = _Backend();
});
group('whether the account has Agent Messages', () {
test('an answer says so, whatever a tab\'s old flag says', () async {
backend.tabs = {'on': true, 'off': false};
final messages = controller();
addTearDown(messages.dispose);
expect(messages.loaded, isFalse, reason: 'unknown until read');
var notified = 0;
messages.addListener(() => notified++);
await messages.refresh();
expect(messages.loaded, isTrue);
expect(notified, 1);
await messages.refresh();
expect(notified, 1, reason: 'the same answer again changes nothing');
});
test('an older daemon or backend (404) offers nothing, for good', () async {
final messages = controller();
addTearDown(messages.dispose);
backend.readNull = true;
await messages.refresh();
expect(messages.loaded, isFalse);
backend.readNull = false;
await messages.refresh();
expect(messages.loaded, isTrue);
// The daemon was replaced by one without Agent Messages.
backend.readNull = true;
var notified = 0;
messages.addListener(() => notified++);
await messages.refresh();
expect(messages.loaded, isFalse);
expect(notified, 1);
});
test('a failure before any answer stays unanswered', () async {
final messages = controller();
addTearDown(messages.dispose);
backend.readError = StateError('daemon down');
await messages.refresh();
expect(messages.loaded, isFalse);
});
test('a failed read keeps what was known', () async {
final messages = controller();
addTearDown(messages.dispose);
await messages.refresh();
backend.readError = StateError('one dropped request');
await messages.refresh();
expect(messages.loaded, isTrue);
});
test('signing out forgets the account', () async {
final messages = controller();
addTearDown(messages.dispose);
await messages.refresh();
messages.handleEvent(_sent());
messages.reset();
expect(messages.trafficFor('tab'), 0);
expect(messages.markFor('studio', 'lead'), isNull);
expect(messages.loaded, isFalse);
});
});
group('traffic', () {
test('a message counts as traffic, so an open log reads again', () {
fakeAsync((async) {
final messages = controller();
unawaited(messages.refresh());
async.flushMicrotasks();
var notified = 0;
messages.addListener(() => notified++);
messages.handleEvent(_sent());
expect(messages.trafficFor('tab'), 1);
expect(notified, 1, reason: 'an open log reads again');
messages.handleEvent(_sent(state: 'delivered'));
expect(messages.trafficFor('tab'), 2);
messages.dispose();
expect(async.pendingTimers, isEmpty);
});
});
test('marks the sender and each recipient once per message', () {
fakeAsync((async) {
final messages = controller();
messages.handleEvent(_sent());
expect(messages.markFor('studio', 'lead')?.label, '→ API worker');
expect(messages.markFor('laptop', 'api')?.label, '← Lead');
expect(messages.markFor('studio', 'lead')?.warning, isFalse);
// The next status of the same message is not a new message.
messages.seen('laptop', 'api');
messages.handleEvent(_sent(state: 'delivered'));
expect(messages.markFor('laptop', 'api'), isNull);
async.elapse(const Duration(seconds: 5));
expect(messages.markFor('studio', 'lead'), isNull);
messages.handleEvent(_sent(id: 'm0000002', to: 'web'));
expect(
messages.markFor('studio', 'lead')?.label,
'→ web',
reason: 'an unknown name falls back to the start of its id',
);
messages.dispose();
expect(async.pendingTimers, isEmpty);
});
});
test('focusing a pane clears its mark', () {
fakeAsync((async) {
final messages = controller();
messages.handleEvent(_sent());
var notified = 0;
messages.addListener(() => notified++);
messages.seen('studio', 'lead');
expect(messages.markFor('studio', 'lead'), isNull);
expect(messages.markFor('laptop', 'api'), isNotNull);
expect(notified, 1);
messages.seen('studio', 'lead');
expect(notified, 1);
messages.dispose();
});
});
test('a sender stopped by the rate limit is the one alert', () {
fakeAsync((async) {
final messages = controller();
messages.handleEvent({
'limited': {'machineId': 'studio', 'agentId': 'lead'},
});
final mark = messages.markFor('studio', 'lead')!;
expect(mark.warning, isTrue);
expect(mark.label, '→ rate limited');
expect(messages.trafficFor('tab'), 0);
messages.dispose();
});
});
test('frames without a tab or parties change nothing', () {
final messages = controller();
addTearDown(messages.dispose);
messages.handleEvent({'messageId': 'm0000001'});
messages.handleEvent({'tabId': '', 'messageId': 'm0000001'});
messages.handleEvent({'limited': 'nobody'});
expect(messages.trafficFor(''), 0);
messages.handleEvent({'tabId': 'tab', 'messageId': 'm0000003'});
expect(messages.trafficFor('tab'), 1);
expect(messages.markFor('studio', 'lead'), isNull);
});
});
group('the log', () {
test('merges every daemon by message id, oldest first', () async {
final asked = <(String, Map<String, dynamic>)>[];
final messages = controller(
request: (machineId, payload) async {
asked.add((machineId, payload));
return switch (machineId) {
// The sender's daemon still says queued for the remote recipient.
'studio' => {
'messages': [
_row(
'm0000002',
at: 2000,
statuses: [
{
'machineId': 'laptop',
'agentId': 'api',
'state': 'queued',
'at': 2000,
},
],
),
_row('m0000001', at: 1000),
],
},
// The recipient's daemon delivered it.
'laptop' => {
'messages': [
_row(
'm0000002',
at: 2000,
statuses: [
{
'machineId': 'laptop',
'agentId': 'api',
'state': 'delivered',
'via': 'hook',
'at': 2500,
},
],
),
{..._row('m0000009', at: 9), 'tabId': 'another'},
'not a message',
],
},
_ => throw StateError('offline'),
};
},
);
addTearDown(messages.dispose);
final log = await messages.history('tab', [
'studio',
'laptop',
'laptop',
'gone',
]);
expect(log.reached, isTrue);
expect(asked, hasLength(3));
expect(asked.first.$2, {'action': 'history', 'tabId': 'tab'});
expect(log.messages.map((m) => m.id), ['m0000001', 'm0000002']);
final merged = log.messages.last;
expect(merged.stateOf(merged.to.single), AgentMessageState.delivered);
expect(merged.statusOf(merged.to.single)?.via, 'hook');
expect(merged.firstLine, 'Review of 3f2a9c1');
expect(
log.messages.first.stateOf(log.messages.first.to.single),
AgentMessageState.queued,
);
});
test('no daemon answering is not an empty log', () async {
final messages = controller(
request: (_, _) async => {'error': 'UNKNOWN_ACTION'},
);
addTearDown(messages.dispose);
final unreachable = await messages.history('tab', ['studio']);
expect(unreachable.reached, isFalse);
expect(unreachable.messages, isEmpty);
final empty = await controller(request: (_, _) async => {'messages': []})
.history('tab', ['studio']);
expect(empty.reached, isTrue);
expect(empty.complete, isTrue);
});
test(
'a member machine that did not answer leaves the log incomplete',
() async {
final messages = controller(
request: (machineId, _) async => machineId == 'studio'
? {
'messages': [_row('m0000001', at: 1)],
}
: throw StateError('offline'),
);
addTearDown(messages.dispose);
final partial = await messages.history(
'tab',
['studio', 'laptop'],
expected: {'studio', 'laptop'},
);
expect(partial.reached, isTrue);
expect(partial.complete, isFalse);
final unasked = await messages.history(
'tab',
['studio'],
expected: {'studio', 'gone-offline'},
);
expect(unasked.complete, isFalse, reason: 'offline, so never asked');
final whole = await messages.history(
'tab',
['studio'],
expected: {'studio'},
);
expect(whole.complete, isTrue);
},
);
test('a later final state wins, and failed says why', () {
AgentMessage message(String state, int at, {String? reason}) =>
AgentMessage.fromJson(
_row(
'm0000001',
at: 1,
statuses: [
{
'machineId': 'laptop',
'agentId': 'api',
'state': state,
'at': at,
'reason': ?reason,
},
],
),
)!;
final failed = message('failed', 5, reason: 'left the tab');
final queued = message('queued', 9);
final merged = queued.merge(failed);
expect(merged.stateOf(merged.to.single), AgentMessageState.failed);
expect(merged.statusOf(merged.to.single)?.reason, 'left the tab');
expect(
failed.merge(message('delivered', 7)).stateOf(failed.to.single),
AgentMessageState.delivered,
);
});
});
group('other machines', () {
// A daemon tells `messages_changed` only to its own computer's windows:
// traffic between harnesses elsewhere is read from their logs.
final now = DateTime(2026, 10, 10, 12);
Map<String, dynamic> recent(String id, {required Duration ago}) =>
_row(id, at: now.subtract(ago).millisecondsSinceEpoch);
test('a message that just moved is traffic and marks its panes', () async {
final asked = <(String, Map<String, dynamic>)>[];
final messages = AgentMessagesController(
read: backend.read,
request: (machineId, payload) async {
asked.add((machineId, payload));
return {
'messages': [
recent('m0000001', ago: const Duration(minutes: 5)),
// Within a round of the remote watch's: still news when a
// round first sees it.
recent('m0000002', ago: const Duration(seconds: 30)),
],
};
},
nameOf: (_, agentId) => names[agentId],
now: () => now,
);
addTearDown(messages.dispose);
await messages.pollRemote([
(tabId: 'tab', machineIds: ['laptop']),
]);
expect(asked.single.$1, 'laptop');
expect(asked.single.$2, {
'action': 'history',
'tabId': 'tab',
'limit': 20,
});
expect(messages.trafficFor('tab'), 1);
expect(messages.markFor('studio', 'lead')?.label, '→ API worker');
expect(messages.markFor('laptop', 'api')?.label, '← Lead');
// Already seen: the next round changes nothing, and neither does the
// same message's own frame.
messages.seen('studio', 'lead');
await messages.pollRemote([
(tabId: 'tab', machineIds: ['laptop']),
]);
expect(messages.trafficFor('tab'), 1);
expect(messages.markFor('studio', 'lead'), isNull);
messages.handleEvent(_sent(id: 'm0000002', state: 'delivered'));
expect(messages.markFor('studio', 'lead'), isNull);
});
test('older messages are remembered, not announced', () async {
final messages = AgentMessagesController(
read: backend.read,
request: (_, _) async => {
'messages': [recent('m0000003', ago: const Duration(minutes: 2))],
},
nameOf: (_, _) => null,
now: () => now,
);
addTearDown(messages.dispose);
await messages.pollRemote([
(tabId: 'tab', machineIds: ['laptop']),
]);
expect(messages.trafficFor('tab'), 0);
expect(messages.markFor('studio', 'lead'), isNull);
messages.handleEvent(_sent(id: 'm0000003', state: 'delivered'));
expect(
messages.markFor('studio', 'lead'),
isNull,
reason: 'its marks were due when it moved, not now',
);
});
test('one request at a time per machine', () async {
final answer = Completer<Map<String, dynamic>>();
final asked = <String>[];
final messages = AgentMessagesController(
read: backend.read,
request: (machineId, payload) {
asked.add('$machineId/${payload['tabId']}');
return machineId == 'laptop'
? answer.future
: Future.value({'messages': const []});
},
nameOf: (_, _) => null,
now: () => now,
);
addTearDown(messages.dispose);
final tabs = <AgentMessagesRemoteTab>[
(tabId: 'one', machineIds: ['laptop', 'mini']),
(tabId: 'two', machineIds: ['laptop']),
];
final first = messages.pollRemote(tabs);
await pumpEventQueue();
final second = messages.pollRemote(tabs);
await pumpEventQueue();
expect(asked, ['laptop/one', 'mini/one', 'mini/one']);
answer.complete({'messages': const []});
await Future.wait([first, second]);
expect(asked, ['laptop/one', 'mini/one', 'mini/one', 'laptop/two']);
});
test('a watch asks while the window is in front, every 15 seconds', () {
fakeAsync((async) {
final foreground = ValueNotifier(false);
var rounds = 0;
final messages = AgentMessagesController(
read: backend.read,
request: (_, _) async {
rounds++;
return {'messages': const []};
},
nameOf: (_, _) => null,
now: () => now,
);
var tabs = <AgentMessagesRemoteTab>[
(tabId: 'tab', machineIds: ['laptop']),
];
final watch = AgentMessagesRemoteWatch(
controller: messages,
foreground: foreground,
tabs: () => tabs,
)..start();
async.flushMicrotasks();
expect(rounds, 0, reason: 'a background window asks nothing');
foreground.value = true;
async.flushMicrotasks();
expect(rounds, 1, reason: 'once on coming to the front');
async.elapse(const Duration(seconds: 15));
expect(rounds, 2);
async.elapse(const Duration(seconds: 15));
expect(rounds, 3);
tabs = [];
async.elapse(const Duration(seconds: 15));
expect(rounds, 3, reason: 'no tab has remote harnesses to message');
tabs = [
(tabId: 'tab', machineIds: ['laptop']),
];
foreground.value = false;
async.elapse(const Duration(minutes: 1));
expect(rounds, 3);
expect(async.pendingTimers, isEmpty);
watch.dispose();
messages.dispose();
foreground.dispose();
});
});
});
group('the app', () {
late AppNotifier app;
setUp(() {
app = AppNotifier(
config: AppConfig.dev,
authSession: AuthSession(),
configStore: null,
);
const machine = Machine(
machineId: 'studio',
authMode: MachineAuthMode.remote,
name: 'Studio',
);
app.machines = [machine];
app.machineStates['studio'] = MachineState(machine)
..nodeOnline = true
..connectionStatus = ConnectionStatus.connected
..agentLoadStatus = AgentLoadStatus.loaded
..agents = [
const Agent(id: 'lead', name: 'Lead', terminalAvailable: true),
const Agent(id: 'api', name: 'API worker', terminalAvailable: true),
];
});
tearDown(() => app.dispose());
test(
'messages_changed reaches Agent Messages, never turn activity',
() async {
await app.handleEventForTest('studio', {
'type': 'messages_changed',
'payload': {
'tabId': app.activeSwarmId,
'messageId': 'm0000001',
'at': 1,
'from': {'machineId': 'studio', 'agentId': 'lead'},
'to': [
{'machineId': 'studio', 'agentId': 'api', 'state': 'queued'},
],
},
});
expect(app.agentMessages.trafficFor(app.activeSwarmId), 1);
expect(
app.agentMessages.markFor('studio', 'lead')?.label,
'→ API worker',
);
expect(app.agentMessages.markFor('studio', 'api')?.label, '← Lead');
final state = app.machineStates['studio']!;
expect(state.unknownActivityAgentIds, isEmpty);
expect(state.processingAgentIds, isEmpty);
app.agentMessages.reset();
},
);
test('Agent Messages is asked about once the desk is joined, and '
'forgotten on sign-out', () async {
final api = await joinAgentMessagesDesk(app);
expect(api.reads, 1);
expect(app.agentMessages.loaded, isTrue);
// desk_changed may have moved a tab's leader: the settings are read again.
await app.handleEventForTest('studio', {
'type': 'desk_changed',
'payload': {'revision': 0},
});
await pumpEventQueue();
expect(api.reads, 2);
app.expireSessionForTest('Signed out');
expect(app.agentMessages.loaded, isFalse);
});
test('only desk tabs, once answered, have Agent Messages', () async {
final desk = app.activeSwarmId;
expect(
app.agentMessagesOffered(desk),
isFalse,
reason: 'before the desk',
);
final api = await joinAgentMessagesDesk(app);
final joined = app.activeSwarmId;
expect(app.agentMessagesOffered(joined), isTrue);
app.openStore();
expect(app.activeSwarm.isStore, isTrue);
expect(app.agentMessagesOffered(app.activeSwarmId), isFalse);
app.newSwarm(draft: true, newTabPage: true);
expect(app.isDraftSwarm(app.activeSwarmId), isTrue);
expect(app.agentMessagesOffered(app.activeSwarmId), isFalse);
api.unsupported = true;
await app.agentMessages.refresh();
expect(
app.agentMessagesOffered(joined),
isFalse,
reason: 'an older CLI or backend',
);
});
test('a desk tab with two harnesses polls those on other machines, '
'with no flag to turn on', () async {
const laptop = Machine(
machineId: 'laptop',
authMode: MachineAuthMode.remote,
name: 'Laptop',
);
app.machineStates['laptop'] = MachineState(laptop)
..nodeOnline = true
..connectionStatus = ConnectionStatus.connected
..agentLoadStatus = AgentLoadStatus.loaded
..agents = [
const Agent(id: 'web', name: 'Web', terminalAvailable: true),
];
await joinAgentMessagesDesk(app);
void adopt(String machineId, String agentId) => app.adoptSessionForTest(
TerminalSession(
machineId: machineId,
agentId: agentId,
agentName: agentId,
engineId: 'codex',
send: (_, _) async => true,
sendBinary: (_) async => true,
),
);
final tab = app.activeSwarmId;
adopt('studio', 'lead');
expect(
app.agentMessagesRemoteTabs(),
isEmpty,
reason: 'one harness has nobody to message',
);
adopt('laptop', 'web');
final remote = app.agentMessagesRemoteTabs().single;
expect(remote.tabId, tab);
// No daemon of this computer in this fixture: every machine is remote.
expect(remote.machineIds, ['studio', 'laptop']);
app.machineStates['laptop']!.connectionStatus =
ConnectionStatus.disconnected;
expect(app.agentMessagesRemoteTabs().single.machineIds, ['studio']);
});
test('a tab asks this computer and its connected machines', () {
expect(
app.agentMessageMachines(app.activeSwarmId),
isEmpty,
reason: 'no local daemon and no panes',
);
app.adoptSessionForTest(
TerminalSession(
machineId: 'studio',
agentId: 'lead',
agentName: 'Lead',
engineId: 'codex',
send: (_, _) async => true,
sendBinary: (_) async => true,
),
);
expect(app.agentMessageMachines(app.activeSwarmId), ['studio']);
app.machineStates['studio']!.connectionStatus =
ConnectionStatus.disconnected;
expect(app.agentMessageMachines(app.activeSwarmId), isEmpty);
});
});
}