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 'dart:convert';
import 'dart:math';
import 'package:flutter/foundation.dart';
import 'package:harness_mobile/core/models.dart';
import 'package:harness_mobile/notify/agent_notice.dart' show NoticeKind;
import 'package:harness_mobile/phone/voice_input_controller.dart';
import 'package:harness_mobile/state/app_state.dart';
import 'package:harness_mobile/state/pending_question.dart';
import 'package:harness_mobile/terminal/terminal_binary.dart';
import 'package:harness_mobile/terminal/terminal_session.dart';
import 'package:harness_mobile/ws/ws_conn.dart';
import 'sample_harness.dart';
import 'sample_notifier.dart';
import 'sample_screen.dart';
import 'sample_scripts.dart';
import 'sample_text.dart';
import 'sample_voice.dart';
/// Everything sample mode runs: its app state, the two computers answering it, the harnesses on
/// them, and every timer any of it holds.
///
/// It plays the part of the harness daemon on each computer. A terminal opened on a sample
/// harness is answered with a stream — `terminal_ready`, then a keyframe of what that harness has
/// on screen, then its output as it happens — through the same [TerminalSession] a real machine
/// would reach, so the phone draws it with the same code. What is typed comes back the same way,
/// as input frames, and becomes keystrokes in the harness.
///
/// [dispose] ends all of it at once: every timer the sample started is on [_timers], so leaving
/// cannot leave one running.
class SampleRuntime implements SampleHarnessHost {
SampleRuntime({DateTime? now}) {
notifier = SampleNotifier(
connections: _connectionFor,
machinesOnFile: () => machines,
transcribe: () => transcriber.transcribe(),
);
_seed(now ?? DateTime.now());
}
late final SampleNotifier notifier;
late final SampleTranscriber transcriber = SampleTranscriber(
after: schedule,
answering: _focusedIsAsking,
);
final Map<String, SampleConnection> _connections = {};
final Map<String, SampleHarness> _harnesses = {};
final Map<String, _Stream> _streams = {};
final Map<String, Map<String, dynamic>> _creations = {};
final Set<Timer> _timers = {};
final Random _random = Random();
int _created = 0;
int _questions = 0;
bool _disposed = false;
/// The sample's computers, as the account lists them.
List<Machine> get machines => [
for (final computer in sampleComputers)
Machine(
machineId: computer.id,
authMode: MachineAuthMode.remote,
name: computer.name,
hostname: computer.name,
status: 'online',
),
];
/// Every harness in the sample, keyed `machineId/agentId`.
@visibleForTesting
Map<String, SampleHarness> get harnesses => Map.unmodifiable(_harnesses);
SampleHarness? harnessOf(String machineId, String agentId) =>
_harnesses['$machineId/$agentId'];
/// The connection to one sample computer — what the notifier dials.
SampleConnection connectionFor(String machineId) => _connectionFor(machineId);
/// Voice input for the sample's pager: a microphone that records nothing, heard as
/// [transcriber] says.
VoiceInputController voiceController() => VoiceInputController(
transcriber: (_, _) => transcriber.transcribe(),
recorder: SampleVoiceRecorder(every: every),
);
// ── the clock ──────────────────────────────────────────────────────────────────────────────
@override
Timer schedule(Duration delay, void Function() run) {
late final Timer timer;
timer = Timer(delay, () {
_timers.remove(timer);
if (!_disposed) run();
});
_track(timer);
return timer;
}
@override
Timer every(Duration period, void Function() run) {
final timer = Timer.periodic(period, (_) {
if (!_disposed) run();
});
_track(timer);
return timer;
}
void _track(Timer timer) {
if (_disposed) {
timer.cancel();
return;
}
_timers
..removeWhere((held) => !held.isActive)
..add(timer);
}
// ── the starting state ─────────────────────────────────────────────────────────────────────
void _seed(DateTime now) {
notifier.machines = machines;
for (final machine in notifier.machines) {
notifier.machineStates[machine.machineId] = MachineState(machine)
..nodeOnline = true
..connectionStatus = ConnectionStatus.connected
..agentLoadStatus = AgentLoadStatus.loaded
..terminalCapabilityLoaded = true
..terminalCapabilityAvailable = true
..terminalNoTakeoverAvailable = true
..projectFolderAvailable = true;
}
final seeds = sampleSeeds(now);
for (final seed in seeds) {
final harness = SampleHarness(
machineId: seed.computer.id,
agent: seed.agent,
host: this,
transcript: seed.transcript,
loop: seed.loop,
);
_harnesses['${harness.machineId}/${harness.agentId}'] = harness;
_publish(harness);
for (final entry in seed.transcript) {
if (entry is UserEntry) harness.asks.insert(0, entry.text);
}
if (seed.finished case final reply?) {
harness.replies.insert(0, reply);
// News nobody has read: marked without the chime a live turn ending would make.
notifier.agentNotices.unread.mark((
machineId: harness.machineId,
agentId: harness.agentId,
), NoticeKind.done);
}
}
for (final seed in seeds) {
final harness = harnessOf(seed.computer.id, seed.agent['id'] as String)!;
if (seed.ask != null) {
harness.begin(ask: seed.ask, then: seed.then);
} else if (seed.loop != null) {
harness.begin(verb: 'Tracing');
}
}
}
// ── what the harnesses report ─────────────────────────────────────────────────────────────
@override
void appended(SampleHarness harness, List<SampleEntry> entries) {
for (final stream in _streamsOf(harness)) {
_write(stream, entries);
}
}
@override
void liveChanged(SampleHarness harness) {
for (final stream in _streamsOf(harness)) {
_write(stream, const []);
}
}
@override
void workingChanged(SampleHarness harness, bool working) {
final machine = notifier.stateOf(harness.machineId);
if (machine == null) return;
if (working) {
machine.processingAgentIds.add(harness.agentId);
} else {
machine.processingAgentIds.remove(harness.agentId);
}
machine.agentActivityAt[harness.agentId] = DateTime.now();
_publish(harness);
notifier.changed();
}
@override
void askChanged(SampleHarness harness, SampleAsk? ask) {
final machine = notifier.stateOf(harness.machineId);
if (machine == null) return;
final ref = (machineId: harness.machineId, agentId: harness.agentId);
if (ask == null) {
machine.blockedAgents.remove(harness.agentId);
notifier.agentNotices.unread.clear(ref, kind: NoticeKind.question);
} else {
machine.blockedAgents[harness.agentId] = PendingQuestion(
machineId: harness.machineId,
agentId: harness.agentId,
requestId: 'sample-question-${++_questions}',
answerKey: ask.announced,
prompt: ask.announced,
options: ask.options,
multi: false,
since: DateTime.now(),
);
if (!_watching(ref)) {
notifier.agentNotices.unread.mark(ref, NoticeKind.question);
}
}
notifier.changed();
}
@override
void turnEnded(SampleHarness harness, String? reply) {
_publish(harness);
final machine = notifier.stateOf(harness.machineId);
if (reply != null && machine != null) {
final ref = (machineId: harness.machineId, agentId: harness.agentId);
notifier.agentNotices.turnEnded(
(
ref: ref,
name: harness.agent['name'] as String? ?? 'harness',
machine: machine.machine.displayName,
),
(
aborted: false,
replay: false,
subagent: false,
reply: reply,
tier: null,
),
watching: () => _watching(ref),
);
}
notifier.changed();
}
@override
List<SampleStep> replyTo(SampleHarness harness, String text) =>
sampleReply(harness, text);
bool _watching(({String machineId, String agentId}) ref) {
final pane = notifier.focusedPane;
return pane != null &&
pane.machineId == ref.machineId &&
pane.agentId == ref.agentId;
}
bool _focusedIsAsking() {
final pane = notifier.focusedPane;
final agentId = pane?.agentId;
if (pane == null || agentId == null) return false;
return harnessOf(pane.machineId, agentId)?.asking ?? false;
}
/// [harness]'s agent, as its machine now describes it, into the notifier's list.
void _publish(SampleHarness harness) {
final machine = notifier.stateOf(harness.machineId);
if (machine == null) return;
final agent = Agent.fromJson(Map<String, dynamic>.from(harness.agent));
final agents = [...machine.agents];
final at = agents.indexWhere((known) => known.id == agent.id);
if (at < 0) {
agents.add(agent);
} else {
agents[at] = agent;
}
machine.agents = agents;
}
// ── the machines' side of the wire ────────────────────────────────────────────────────────
SampleConnection _connectionFor(String machineId) => _connections.putIfAbsent(
machineId,
() => SampleConnection._(this, machineId),
);
Future<Map<String, dynamic>> _request(
String machineId,
String type,
Map<String, dynamic> payload,
) async {
if (_disposed) {
throw WsRequestFailure(responseType: '${type}_result', code: 'CLOSED');
}
final agentId = payload['agentId'] as String?;
final harness = agentId == null ? null : harnessOf(machineId, agentId);
switch (type) {
case 'agents_list':
return {
'agents': [
for (final harness in _harnesses.values)
if (harness.machineId == machineId) {...harness.agent},
],
};
case 'terminal_capabilities':
return {
'protocolVersion': TerminalSession.protocolVersion,
'backend': 'tmux',
'available': true,
'features': {'noTakeover': true, 'projectFolder': true},
};
case 'engines_probe':
final asked = payload['engines'];
return {
'engines': [
for (final engine
in asked is List ? asked : const ['claude', 'codex'])
{
'engine': engine,
'installed': engine == 'claude' || engine == 'codex',
// Both signed in, Claude Code used last: New Harness opens on it, as the sample's
// harnesses show.
if (engine == 'claude' || engine == 'codex') 'signedIn': true,
if (engine == 'claude') 'lastUsedAt': 2,
if (engine == 'codex') 'lastUsedAt': 1,
'installable': true,
'command': engine,
if (engine == 'codex') 'supportsCodexHome': true,
},
],
};
case 'codex_profiles_list':
return {'profiles': const []};
case 'fs_list_dir':
return _listDir(payload['path']);
case 'git_project_info':
return _gitInfo(payload['path']);
case 'agent_create':
return _create(machineId, payload);
case 'agent_create_status':
return _creations[payload['creationId']] ??
{'creationId': payload['creationId'], 'state': 'missing'};
case 'agent_update':
if (harness == null) break;
if (payload['name'] case final String name
when name.trim().isNotEmpty) {
harness.agent['name'] = name.trim();
}
if (payload['opened'] == true) {
harness.agent['lastOpenedAt'] = DateTime.now()
.toUtc()
.toIso8601String();
}
_publish(harness);
notifier.changed();
return {};
case 'agent_delete':
if (harness == null) break;
_forget(harness);
return {};
case 'agent_restart':
case 'agent_resume':
if (harness == null) break;
harness.restart();
return {
'agent': {...harness.agent},
'resumed': true,
};
case 'agent_recent':
if (harness == null) break;
return {
'agentId': harness.agentId,
'asks': [...harness.asks],
'events': [
for (final reply in harness.replies)
{'kind': 'summary', 'text': reply},
],
};
case 'usage_read':
return {};
case 'grid_models_list':
// Find's `:` — the models a sample harness could run on: this computer's own, as a
// real machine lists them.
return {
'supportsModelLaunch': true,
'gridName': 'home',
'localModelEngines': ['claude', 'codex', 'opencode'],
'grids': [
{
'name': 'home',
'own': true,
'models': [
// A node by the name the computer goes by, as a real one reports it — the
// sample's machine ids (`sample-studio`) are fixture plumbing, not names.
{
'id': 'qwen3-coder-30b',
'node': machineId.replaceFirst('sample-', ''),
},
{
'id': 'gpt-oss-20b',
'node': machineId.replaceFirst('sample-', ''),
},
{'id': 'devstral-small', 'node': 'laptop'},
],
},
],
};
}
throw WsRequestFailure(
responseType: '${type}_result',
code: harness == null && agentId != null
? 'AGENT_NOT_FOUND'
: 'UNSUPPORTED',
detail: 'Not part of the sample.',
);
}
/// `agent_create`: a new harness on [machineId], started on its first task when it was given one.
Map<String, dynamic> _create(String machineId, Map<String, dynamic> payload) {
final creationId = payload['creationId'];
final engine = payload['engine'] as String? ?? 'claude';
if (engine != 'claude' && engine != 'codex') {
throw const WsRequestFailure(
responseType: 'agent_create_result',
code: 'INVALID_ENGINE',
detail: 'The sample runs Claude Code and Codex.',
);
}
final number = ++_created;
final cwd = _cwdFor(payload, number);
final project = cwd.split('/').where((part) => part.isNotEmpty).last;
final branchRef = payload['branchRef'] as String?;
final branch =
payload['branchName'] as String? ??
branchRef?.replaceFirst(RegExp(r'^refs/(heads|remotes/[^/]+)/'), '') ??
'main';
final task = (payload['prompt'] as String?)?.trim();
final agent = sampleAgentJson(
id: 'sample-new-$number',
// Named for its task the way the others are named — `dark-mode-toggle` — or numbered.
name: (task == null ? null : sampleSlug(task)) ?? 'harness-${number + 5}',
engine: engine,
project: project,
branch: branch,
updatedAt: DateTime.now(),
);
(agent['project'] as Map)['cwd'] = cwd;
(agent['project'] as Map)['root'] = cwd;
if (payload['gridModel'] case final String model) {
agent['grid'] = {'model': model, 'gridName': payload['gridName']};
}
final harness = SampleHarness(
machineId: machineId,
agent: agent,
host: this,
transcript: [BannerEntry(cwd)],
);
_harnesses['$machineId/${harness.agentId}'] = harness;
// Every app hears about a new harness, not only the one that asked for it.
_publish(harness);
notifier.changed();
if (task != null && task.isNotEmpty) {
// The engine starts, and the task is typed into it.
schedule(const Duration(milliseconds: 900), () => harness.submit(task));
}
final reply = {
'creationId': creationId,
'state': 'created',
'agent': {...agent},
};
if (creationId is String) _creations[creationId] = reply;
return reply;
}
String _cwdFor(Map<String, dynamic> payload, int number) {
final cwd = payload['cwd'];
if (cwd is String && cwd.trim().isNotEmpty) return cwd.trim();
final source = payload['gitSource'];
if (source is String && source.isNotEmpty) return source;
final url = payload['repositoryUrl'];
if (url is String && url.isNotEmpty) {
final name = url
.split(RegExp(r'[/:]'))
.where((part) => part.isNotEmpty)
.last
.replaceFirst(RegExp(r'\.git$'), '');
return '~/code/$name';
}
return '~/code/new-project-$number';
}
void _forget(SampleHarness harness) {
harness.dispose();
_harnesses.remove('${harness.machineId}/${harness.agentId}');
_streams.removeWhere((_, stream) => identical(stream.harness, harness));
final machine = notifier.stateOf(harness.machineId);
machine?.processingAgentIds.remove(harness.agentId);
machine?.blockedAgents.remove(harness.agentId);
}
static const _folders = <String, List<String>>{
'~': ['code', 'Desktop', 'Documents', 'Downloads'],
'~/code': ['api', 'docs', 'mobile', 'web', 'scratch'],
'~/code/api': ['db', 'src', 'tests'],
'~/code/docs': ['public', 'src'],
'~/code/mobile': ['android', 'ios', 'lib', 'test'],
'~/code/web': ['public', 'src', 'test'],
'~/code/scratch': [],
};
Map<String, dynamic> _listDir(Object? raw) {
var path = raw is String ? raw.trim() : '';
if (path.endsWith('/') && path.length > 1) {
path = path.substring(0, path.length - 1);
}
// Somewhere the sample has no folder for is the home folder — including `.`, which is
// where going up from `~` leads.
if (!_folders.containsKey(path) && !path.startsWith('~/code/')) path = '~';
return {
'path': path,
'entries': [
for (final name in _folders[path] ?? const <String>[])
{'name': name, 'isDir': true},
],
'truncated': false,
};
}
Map<String, dynamic> _gitInfo(Object? raw) {
final path = raw is String ? raw : '';
final project = RegExp(r'^~/code/([^/]+)$').firstMatch(path)?.group(1);
if (project == null || project == 'scratch') return {'isGit': false};
return {
'isGit': true,
'branch': 'main',
'defaultRef': 'refs/remotes/origin/main',
'branches': [
{'ref': 'refs/heads/main', 'name': 'main'},
{'ref': 'refs/heads/dev', 'name': 'dev'},
{
'ref': 'refs/remotes/origin/main',
'name': 'origin/main',
'remote': true,
},
],
};
}
// ── terminals ─────────────────────────────────────────────────────────────────────────────
bool _terminalFrame(
String machineId,
String type,
Map<String, dynamic> payload,
) {
if (_disposed) return false;
final stream = _streams[payload['streamId']];
switch (type) {
case 'terminal_open':
_open(machineId, payload);
case 'terminal_resize':
if (stream == null) break;
stream
..cols = (payload['cols'] as num?)?.toInt() ?? stream.cols
..rows = (payload['rows'] as num?)?.toInt() ?? stream.rows;
_keyframe(stream);
case 'terminal_resync':
if (stream != null) _keyframe(stream);
case 'terminal_close':
_streams.remove(payload['streamId']);
case 'message':
final agentId = payload['agentId'];
final content = payload['content'];
if (agentId is String && content is String) {
harnessOf(machineId, agentId)?.submit(content);
}
}
return true;
}
bool _terminalBinary(Uint8List bytes) {
if (_disposed) return false;
final frame = decodeTerminalLocal(bytes);
if (frame == null) return true;
final stream = _streams[frame.streamId];
if (stream == null) return true;
if (frame.kind == TerminalBinaryKind.input ||
frame.kind == TerminalBinaryKind.paste) {
stream.harness.keys(utf8.decode(frame.bytes, allowMalformed: true));
}
return true;
}
void _open(String machineId, Map<String, dynamic> payload) {
final agentId = payload['agentId'];
final requestId = payload['requestId'];
final harness = agentId is String ? harnessOf(machineId, agentId) : null;
// A beat, as a real attach takes one — and after `send` has returned, as a reply would.
schedule(const Duration(milliseconds: 160), () {
if (harness == null) {
_toSessions(machineId, 'terminal_error', {
'requestId': requestId,
'code': 'AGENT_NOT_FOUND',
'message': 'That harness is not in the sample.',
});
return;
}
final stream = _Stream(
id: _streamId(),
harness: harness,
cols: (payload['cols'] as num?)?.toInt() ?? 80,
rows: (payload['rows'] as num?)?.toInt() ?? 24,
);
_streams[stream.id] = stream;
_toSessions(machineId, 'terminal_ready', {
'protocolVersion': TerminalSession.protocolVersion,
'requestId': requestId,
'agentId': agentId,
'streamId': stream.id,
});
_keyframe(stream);
});
}
/// A JSON frame, to every session on [machineId] — each one matches its own request, as it does
/// with a real machine's.
void _toSessions(
String machineId,
String type,
Map<String, dynamic> payload,
) {
for (final pane in notifier.panesFor(machineId).toList()) {
final session = pane.session;
if (session != null) unawaited(session.handleFrame(type, payload));
}
}
Iterable<_Stream> _streamsOf(SampleHarness harness) => _streams.values
.where((stream) => identical(stream.harness, harness))
.toList();
/// Everything [stream]'s harness has on screen, at [stream]'s width — after the modes both
/// CLIs set: the cursor hidden (they draw their own caret) and bracketed paste on, so a paste
/// arrives as one piece rather than as lines that each press Return.
void _keyframe(_Stream stream) {
final width = SampleText.fit(stream.cols);
final harness = stream.harness;
final live = harness.look.live(harness.live, width);
final lines = [
...harness.look.transcript(harness.transcript, width),
...live,
];
stream.live = live.length;
_send(
stream,
TerminalBinaryKind.keyframe,
'\x1b[?25l\x1b[?2004h${lines.join('\r\n')}',
);
}
/// [entries] added above the live region, and the live region drawn again under them — the
/// cursor walks back up to where the live region starts, clears to the end of the screen, and
/// writes.
void _write(_Stream stream, List<SampleEntry> entries) {
final width = SampleText.fit(stream.cols);
final harness = stream.harness;
final live = harness.look.live(harness.live, width);
// A live region taller than the pane cannot be walked back over: the top of it has scrolled
// off. A keyframe says the same thing in one go.
if (stream.live >= stream.rows || live.length >= stream.rows) {
_keyframe(stream);
return;
}
final lines = [
for (final entry in entries) ...[...harness.look.entry(entry, width), ''],
...live,
];
final back = stream.live > 1 ? '\x1b[${stream.live - 1}A' : '';
stream.live = live.length;
_send(
stream,
TerminalBinaryKind.output,
'\r$back\x1b[J${lines.join('\r\n')}',
);
}
void _send(_Stream stream, TerminalBinaryKind kind, String text) {
final holders = [
for (final pane in notifier.panesFor(stream.harness.machineId))
if (pane.session case final session? when session.streamId == stream.id)
session,
];
if (holders.isEmpty) {
// Nobody reads it any more — the page reopened, or went.
_streams.remove(stream.id);
return;
}
final keyframe = kind == TerminalBinaryKind.keyframe;
final frame = TerminalBinaryFrame(
kind: kind,
streamId: stream.id,
seq: stream.seq++,
bytes: utf8.encode(text),
compressed: false,
cols: keyframe ? stream.cols : null,
rows: keyframe ? stream.rows : null,
);
for (final session in holders) {
unawaited(session.handleBinary(frame));
}
}
/// Stream ids are UUIDs: the binary frames carry them as 16 bytes.
String _streamId() {
final hex = [
for (var i = 0; i < 16; i++)
_random.nextInt(256).toRadixString(16).padLeft(2, '0'),
].join();
return '${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-'
'${hex.substring(16, 20)}-${hex.substring(20)}';
}
void dispose() {
if (_disposed) return;
_disposed = true;
for (final timer in _timers) {
timer.cancel();
}
_timers.clear();
for (final harness in _harnesses.values) {
harness.dispose();
}
_streams.clear();
notifier.dispose();
}
}
class _Stream {
_Stream({
required this.id,
required this.harness,
required this.cols,
required this.rows,
});
final String id;
final SampleHarness harness;
int cols;
int rows;
int seq = 0;
/// How many lines of live region the pane is showing — how far a redraw walks back up.
int live = 0;
}
/// One sample computer's end of the wire: everything the app sends a machine is answered here,
/// in-process, and nothing is sent anywhere.
class SampleConnection extends WsConn {
SampleConnection._(this._runtime, String machineId)
: super(
wsBaseUrl: 'wss://sample.invalid',
autonomousEnv: 'sample',
machineId: machineId,
accessTokenProvider: (_, _) async => '',
onAuthFailure: (_) {},
onEvent: (_) {},
onStatus: (_) {},
);
final SampleRuntime _runtime;
@override
bool get isReady => !_runtime._disposed;
@override
Future<void> connect() async {}
@override
void reconnectNow() {}
@override
Future<void> forceReconnect() async {}
@override
Future<void> close() async {}
// ⚠️ Every answer comes back on a LATER microtask, never inside the call. A machine's reply
// always arrives after the send returns, and the app is written for that: an answer given
// synchronously lands in the middle of whatever asked — a widget's `initState`, a build — and
// its notification rebuilds a tree that is still being built.
@override
Future<Map<String, dynamic>> request(
String type, {
Map<String, dynamic> payload = const {},
Duration timeout = const Duration(seconds: 20),
}) async {
await Future<void>.value();
return _runtime._request(machineId, type, payload);
}
@override
void sendRaw(String type, Map<String, dynamic> payload) =>
unawaited(sendTerminalFrame(type, payload));
@override
Future<void> sendFrame(Map<String, dynamic> frame) async {
await Future<void>.value();
final type = frame['type'];
final payload = frame['payload'];
if (type is String && payload is Map<String, dynamic>) {
_runtime._terminalFrame(machineId, type, payload);
}
}
@override
Future<bool> sendTerminalFrame(
String type,
Map<String, dynamic> payload,
) async {
await Future<void>.value();
return _runtime._terminalFrame(machineId, type, payload);
}
@override
Future<bool> sendTerminalBinary(Uint8List bytes) async {
await Future<void>.value();
return _runtime._terminalBinary(bytes);
}
}