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.

feat(mobile): open the agents either side before they are swiped to

Dev jacob76167c5f96a9
diff --git a/mobile/lib/phone/agent_neighbour_warmer.dart b/mobile/lib/phone/agent_neighbour_warmer.dart
new file mode 100644
index 000000000..9c3280b0a
--- /dev/null
+++ b/mobile/lib/phone/agent_neighbour_warmer.dart
@@ -0,0 +1,112 @@
+import 'dart:async';
+
+import 'package:harness_mobile/state/app_state.dart';
+import 'package:harness_mobile/terminal/terminal_session.dart';
+
+import 'agent_swipe.dart';
+
+typedef AgentRef = ({String machineId, String agentId});
+
+/// Opens the agents one swipe either side of the one on screen, and closes the ones further out.
+///
+/// ⚠️ **Why a swipe needs this.** A page is not built until the finger drags it in, and an agent
+/// nobody has opened yet had no stream at all until the swipe passed halfway: the page slid in as
+/// "Attaching…", the stream opened, and the agent's screen arrived as a keyframe a network round
+/// trip later — well after the swipe had finished. Opened in advance, the keyframe has long landed
+/// and the page slides in already showing its output.
+///
+/// ⚠️ **Only once the agent on screen is live, and a beat after.** Two reasons. Its size is the size
+/// the neighbours open at — every page of the pager shares it — and there is no size until its own
+/// keyframe has come back. And the home screen closes every pane but the one it opened as it builds
+/// a pager (`AgentHome._attachOnly`); by the time the agent on screen is live that has happened, so
+/// it cannot close what this opens. The beat keeps the neighbours' keyframes, parsed on the UI
+/// thread, off the frames where the landed page is still settling.
+///
+/// ⚠️ **A window of three, not everything ever swiped past.** The pager used to keep every agent it
+/// visited attached until it was thrown away; with neighbours opened on top of that, a lap of the
+/// list would leave a live stream per agent. Agents outside the window are closed as it moves.
+class AgentNeighbourWarmer {
+ AgentNeighbourWarmer({
+ required this.notifier,
+ required this.list,
+ required this.attached,
+ });
+
+ final AppNotifier notifier;
+ final AgentSwipeList list;
+
+ /// The pager's own record of what it opened — shared, so what this opens is closed with the rest
+ /// when the pager goes, and what this closes is no longer on it.
+ final Set<AgentRef> attached;
+
+ /// How long the page on screen has been live before its neighbours are opened.
+ static const delay = Duration(milliseconds: 600);
+
+ Timer? _timer;
+
+ /// The page whose neighbours are open, so every notifier change afterwards costs one comparison.
+ int? _warmedPage;
+
+ /// Warms [page]'s neighbours if [current] — the agent on it — is live and they are not warm yet.
+ ///
+ /// Cheap enough to call on every notifier change, which is how the pager calls it: that is the only
+ /// signal that the agent on screen has gone live.
+ void check({required int page, required AgentRef current}) {
+ if (!list.wraps || _warmedPage == page || _timer != null) return;
+ final session = notifier
+ .paneOfAgent(current.machineId, current.agentId)
+ ?.session;
+ if (session == null ||
+ session.status != TerminalSessionStatus.controlling) {
+ return;
+ }
+ _timer = Timer(delay, () {
+ _timer = null;
+ _warmedPage = page;
+ _warm(page, current, cols: session.cols, rows: session.rows);
+ });
+ }
+
+ /// Forgets the page it was warming for — the pager has moved.
+ void cancel() {
+ _timer?.cancel();
+ _timer = null;
+ _warmedPage = null;
+ }
+
+ void dispose() => cancel();
+
+ AgentRef _at(int page) {
+ final entry = list.entries[page % list.entries.length];
+ return (machineId: entry.machineId, agentId: entry.agent.id);
+ }
+
+ void _warm(
+ int page,
+ AgentRef current, {
+ required int cols,
+ required int rows,
+ }) {
+ // A set, so a two-agent pager — whose page before and page after are the same agent — opens it
+ // once.
+ final window = {current, _at(page - 1), _at(page + 1)};
+ for (final agent in [...attached]) {
+ if (window.contains(agent)) continue;
+ attached.remove(agent);
+ final pane = notifier.paneOfAgent(agent.machineId, agent.agentId);
+ if (pane != null) unawaited(notifier.closePane(pane.id));
+ }
+ for (final agent in window) {
+ if (agent == current) continue;
+ attached.add(agent);
+ unawaited(
+ notifier.preattachAgent(
+ agent.machineId,
+ agent.agentId,
+ cols: cols,
+ rows: rows,
+ ),
+ );
+ }
+ }
+}
diff --git a/mobile/lib/phone/agent_swipe.dart b/mobile/lib/phone/agent_swipe.dart
index 618c911c5..2219d9f7e 100644
--- a/mobile/lib/phone/agent_swipe.dart
+++ b/mobile/lib/phone/agent_swipe.dart
@@ -5,6 +5,7 @@ import 'package:flutter/material.dart';
import 'package:harness_mobile/state/app_state.dart';
import 'agent_index.dart';
+import 'agent_neighbour_warmer.dart';
import 'terminal_page.dart';
import 'voice_input_controller.dart';
@@ -126,13 +127,26 @@ class _AgentSwipeHostState extends State<AgentSwipeHost> {
/// ⚠️ **Without this the pager leaks terminals.** The phone's old rule was one pane, enforced by
/// closing every other one on the way in; a pager has to keep its neighbours attached, so nothing
/// would ever close them. Each pane left behind is a remote stream with a 10,000-line scrollback
- /// and a heartbeat, held for a screen that is gone — and swiping through ten agents and going back
- /// would leave ten of them.
+ /// and a heartbeat, held for a screen that is gone.
///
/// Recorded rather than recomputed: by the time this page is disposed the list may have moved on,
/// and the panes to close are the ones actually opened, not the ones a fresh list would name.
+ /// [_warmer] adds to it and prunes it as the pager moves — see [AgentNeighbourWarmer].
final Set<({String machineId, String agentId})> _attached = {};
+ /// Opens the agents either side of the one on screen once it is live. Null for a pager with nothing
+ /// to swipe to.
+ late final AgentNeighbourWarmer? _warmer = widget.neighbours?.wraps == true
+ ? AgentNeighbourWarmer(
+ notifier: widget.notifier,
+ list: widget.neighbours!,
+ attached: _attached,
+ )
+ : null;
+
+ /// The only signal that the agent on screen has gone live — see [AgentNeighbourWarmer.check].
+ void _checkNeighbours() => _warmer?.check(page: _page, current: _current);
+
/// Voice input for every page of this pager: a take in progress, and what has been heard so far,
/// survive a swipe the way a keyboard that is up does. Disposed with the pager, which is what
/// turns the microphone off on the way out.
@@ -169,10 +183,14 @@ class _AgentSwipeHostState extends State<AgentSwipeHost> {
? _origin * neighbours.entries.length + start
: start;
_controller = PageController(initialPage: _page);
+ widget.notifier.addListener(_checkNeighbours);
+ _checkNeighbours();
}
@override
void dispose() {
+ widget.notifier.removeListener(_checkNeighbours);
+ _warmer?.dispose();
_voice.dispose();
_controller?.dispose();
_detachAll();
@@ -292,10 +310,13 @@ class _AgentSwipeHostState extends State<AgentSwipeHost> {
// Before the setState, so a host that rebuilds this pager in response already names the agent
// swiped to — told afterwards, it would rebuild still pointing at the previous one.
widget.onAgentChanged?.call(arrived);
+ // Warm-up for the page just left is abandoned; the page arrived at is warmed once it is live.
+ _warmer?.cancel();
setState(() {
_page = index;
_current = arrived;
});
+ _checkNeighbours();
// Attaching is what makes the terminal live, and it only happens once the page has SETTLED —
// `onPageChanged` fires at the halfway point of a settled swipe, not on every dragged pixel, so
// flicking across five agents attaches the ones passed through rather than all of them at once.
diff --git a/mobile/lib/state/app_state.dart b/mobile/lib/state/app_state.dart
index b0efefee8..8bbf45721 100644
--- a/mobile/lib/state/app_state.dart
+++ b/mobile/lib/state/app_state.dart
@@ -4483,6 +4483,43 @@ class AppNotifier extends ChangeNotifier {
await addAgentToSwarm(machineId, agentId);
}
+ /// Opens an agent's terminal WITHOUT selecting it — the phone's pager warming the agents one
+ /// swipe either side of the one on screen, so a swipe lands on output rather than on
+ /// "Attaching…" while a stream opens and its keyframe crosses the network.
+ ///
+ /// ⚠️ **Nothing about the selection moves, and that is the difference from [selectAgent].** Not
+ /// the focused pane, the selected machine, the machine's active agent, the focus announced to the
+ /// dial, nor the persisted layout: every one of those still names the agent being read, and a
+ /// warm-up that moved them would have the dial and a relaunch follow an agent nobody opened.
+ ///
+ /// The stream opens at [cols]×[rows] rather than waiting for a view to measure it, because there
+ /// IS no view — the page is not built until it is swiped to. The pager's pages all share one
+ /// size, so the size of the page on screen is the right one, and the keyframe that comes back is
+ /// already laid out for the page it will be drawn on.
+ ///
+ /// A pane that already holds a session is left alone. An agent that cannot be attached now — its
+ /// machine offline or unlinked, its terminal unverified — gets no pane at all: an empty one would
+ /// sit in the layout waiting for nothing.
+ Future<void> preattachAgent(
+ String machineId,
+ String agentId, {
+ required int cols,
+ required int rows,
+ }) async {
+ if (_disposed || !_canAttachAgent(machineId, agentId)) return;
+ var pane = paneOfAgent(machineId, agentId);
+ if (pane == null) {
+ if (panes.length >= maxPanes) return;
+ pane = TerminalPane(
+ id: _nextPaneId++,
+ machineId: machineId,
+ agentId: agentId,
+ );
+ panes.add(pane);
+ }
+ await _attachSession(pane, openAt: (cols: cols, rows: rows));
+ }
+
/// Show a MACHINE in the grid, for the states that belong to the machine
/// rather than to any agent on it.
///
@@ -4659,7 +4696,13 @@ class AppNotifier extends ChangeNotifier {
/// Separate from [assignAgentToPane] because a restored tile takes this path
/// on its own, later, when its machine finally answers — the intent was
/// settled at launch, and nothing about the selection should move again then.
- Future<void> _attachSession(TerminalPane pane) async {
+ ///
+ /// [openAt] opens the stream at a size already known instead of waiting for a
+ /// view to measure one — see [preattachAgent], whose pane has no view yet.
+ Future<void> _attachSession(
+ TerminalPane pane, {
+ ({int cols, int rows})? openAt,
+ }) async {
if (_disposed || !allPanes.contains(pane) || pane.session != null) return;
final wantedAgentId = pane.agentId;
if (wantedAgentId == null) return;
@@ -4697,6 +4740,13 @@ class AppNotifier extends ChangeNotifier {
// blank "Attaching…" placeholder already covers this measurement, which lands within a frame or
// two of the panel mounting; `waitForViewportSize`'s own 2s timeout falls back to 80x24 only if
// the pane genuinely never gets laid out.
+ //
+ // ⚠️ Which is exactly the pane [preattachAgent] opens: it has no view until it is swiped to, so
+ // waiting would sit out the whole 2s and then open at 80x24. It hands over the size instead.
+ if (openAt != null) {
+ await terminal.open(initialCols: openAt.cols, initialRows: openAt.rows);
+ return;
+ }
await terminal.open(waitForViewportSize: true);
}
@@ -5322,15 +5372,20 @@ class AppNotifier extends ChangeNotifier {
}
}
- bool _canAttachPane(TerminalPane pane) {
- if (_disposed || !allPanes.contains(pane)) return false;
- final machine = machineStates[pane.machineId];
+ bool _canAttachPane(TerminalPane pane) =>
+ !_disposed &&
+ allPanes.contains(pane) &&
+ _canAttachAgent(pane.machineId, pane.agentId);
+
+ /// Whether a terminal for this agent could be opened right now, whether or not a pane holds it.
+ bool _canAttachAgent(String machineId, String? agentId) {
+ final machine = machineStates[machineId];
return machine != null &&
machine.nodeOnline != false &&
machine.terminalCapabilityAvailable &&
!(machine.isRemote && !machine.isLocalMachine && machine.needsLink) &&
(!machine.isLocalMachine || machine.usesLocalTransport) &&
- machine.agents.any((a) => a.id == pane.agentId && a.terminalAvailable);
+ machine.agents.any((a) => a.id == agentId && a.terminalAvailable);
}
/// Resolve a dial agent to the machine that owns it.
diff --git a/mobile/test/agent_preattach_test.dart b/mobile/test/agent_preattach_test.dart
new file mode 100644
index 000000000..574c4216f
--- /dev/null
+++ b/mobile/test/agent_preattach_test.dart
@@ -0,0 +1,217 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness_mobile/auth/auth_session.dart';
+import 'package:harness_mobile/core/config.dart';
+import 'package:harness_mobile/core/models.dart';
+import 'package:harness_mobile/phone/agent_index.dart';
+import 'package:harness_mobile/phone/agent_neighbour_warmer.dart';
+import 'package:harness_mobile/phone/agent_swipe.dart';
+import 'package:harness_mobile/state/app_state.dart';
+import 'package:harness_mobile/terminal/terminal_session.dart';
+import 'package:harness_mobile/ws/ws_conn.dart';
+
+/// A machine that accepts every terminal frame and remembers what it was sent.
+class _Conn extends WsConn {
+ _Conn()
+ : super(
+ wsBaseUrl: 'ws://fixture.invalid',
+ autonomousEnv: 'test',
+ machineId: 'm',
+ accessTokenProvider: (_, _) async => '',
+ onAuthFailure: (_) {},
+ onEvent: (_) {},
+ onStatus: (_) {},
+ );
+
+ final List<(String, Map<String, dynamic>)> frames = [];
+
+ List<Map<String, dynamic>> get opens => [
+ for (final (type, payload) in frames)
+ if (type == 'terminal_open') payload,
+ ];
+
+ @override
+ Future<bool> sendTerminalFrame(
+ String type,
+ Map<String, dynamic> payload,
+ ) async {
+ frames.add((type, payload));
+ return true;
+ }
+
+ @override
+ Future<Map<String, dynamic>> request(
+ String type, {
+ Map<String, dynamic> payload = const {},
+ Duration timeout = const Duration(seconds: 20),
+ }) async => {};
+}
+
+const _agentIds = ['a', 'b', 'c', 'd'];
+
+AppNotifier _app(_Conn conn, {bool online = true}) {
+ final app = AppNotifier(
+ config: AppConfig.dev,
+ authSession: AuthSession(),
+ configStore: null,
+ connectionForTest: (_) => conn,
+ );
+ const machine = Machine(
+ machineId: 'm',
+ authMode: MachineAuthMode.remote,
+ name: 'Test host',
+ );
+ app.machines = [machine];
+ app.machineStates['m'] = MachineState(machine)
+ ..nodeOnline = online
+ ..connectionStatus = ConnectionStatus.connected
+ ..agentLoadStatus = AgentLoadStatus.loaded
+ ..terminalCapabilityAvailable = true
+ ..activeAgentId = 'a'
+ ..agents = [
+ for (final id in _agentIds)
+ Agent(
+ id: id,
+ name: id,
+ engine: 'claude',
+ project: const AgentProject(name: 'work', cwd: '/work'),
+ terminalAvailable: true,
+ ),
+ ];
+ return app;
+}
+
+/// The agent on screen, live at a phone's size.
+TerminalSession _live(AppNotifier app, String agentId) {
+ final session = TerminalSession(
+ machineId: 'm',
+ agentId: agentId,
+ agentName: agentId,
+ engineId: 'claude',
+ send: (_, _) async => true,
+ sendBinary: (_) async => true,
+ );
+ app.adoptSessionForTest(session);
+ _goLive(session);
+ return session;
+}
+
+/// What a keyframe arriving does to a session, without a machine to send one: controlling, at the
+/// phone's size, and the notifier told — which is the signal the pager waits on.
+void _goLive(TerminalSession session) {
+ session
+ ..status = TerminalSessionStatus.controlling
+ ..streamId = 'stream-${session.agentId}'
+ ..cols = 46
+ ..rows = 38
+ ..renameAgent('${session.agentName} (live)');
+}
+
+void main() {
+ group('preattachAgent', () {
+ test('opens the stream at the size given, and selects nothing', () async {
+ final conn = _Conn();
+ final app = _app(conn);
+ addTearDown(app.dispose);
+ _live(app, 'a');
+ final focused = app.focusedPaneId;
+
+ await app.preattachAgent('m', 'b', cols: 46, rows: 38);
+
+ expect(conn.opens.single['agentId'], 'b');
+ expect(conn.opens.single['cols'], 46);
+ expect(conn.opens.single['rows'], 38);
+ expect(app.paneOfAgent('m', 'b')?.session, isNotNull);
+ expect(
+ app.focusedPaneId,
+ focused,
+ reason: 'focus stays on the agent read',
+ );
+ expect(app.stateOf('m')?.activeAgentId, 'a');
+ });
+
+ test('a pane already streaming is left alone', () async {
+ final conn = _Conn();
+ final app = _app(conn);
+ addTearDown(app.dispose);
+
+ await app.preattachAgent('m', 'b', cols: 46, rows: 38);
+ await app.preattachAgent('m', 'b', cols: 46, rows: 38);
+
+ expect(conn.opens, hasLength(1));
+ });
+
+ test('an agent that cannot be attached gets no pane', () async {
+ final conn = _Conn();
+ final app = _app(conn, online: false);
+ addTearDown(app.dispose);
+
+ await app.preattachAgent('m', 'b', cols: 46, rows: 38);
+
+ expect(app.paneOfAgent('m', 'b'), isNull);
+ expect(conn.opens, isEmpty);
+ });
+ });
+
+ group('the pager', () {
+ Future<(AppNotifier, _Conn)> pumpPager(WidgetTester tester) async {
+ final conn = _Conn();
+ final app = _app(conn);
+ addTearDown(app.dispose);
+ final list = AgentSwipeList([
+ for (final agent in app.stateOf('m')!.agents)
+ AgentEntry(machine: app.stateOf('m')!, agent: agent),
+ ]);
+ _live(app, 'b');
+ await tester.pumpWidget(
+ MaterialApp(
+ home: AgentSwipeHost(
+ notifier: app,
+ machineId: 'm',
+ agentId: 'b',
+ neighbours: list,
+ ),
+ ),
+ );
+ await tester.pump();
+ return (app, conn);
+ }
+
+ testWidgets('opens the agents either side once the one on screen is live', (
+ tester,
+ ) async {
+ final (app, conn) = await pumpPager(tester);
+ expect(conn.opens, isEmpty, reason: 'not before the landed page settles');
+
+ await tester.pump(AgentNeighbourWarmer.delay);
+ await tester.pump();
+
+ expect(
+ {for (final open in conn.opens) open['agentId']},
+ {'a', 'c'},
+ reason: 'the pages one swipe left and one swipe right',
+ );
+ expect(app.stateOf('m')?.activeAgentId, 'a', reason: 'nothing selected');
+ });
+
+ testWidgets('closes what falls out of the window as the pager moves', (
+ tester,
+ ) async {
+ final (app, _) = await pumpPager(tester);
+ await tester.pump(AgentNeighbourWarmer.delay);
+ await tester.pump();
+ expect(app.paneOfAgent('m', 'a'), isNotNull);
+
+ // One swipe right: from b to c, whose neighbours are b and d.
+ await tester.fling(find.byType(PageView), const Offset(-400, 0), 1000);
+ await tester.pumpAndSettle();
+ // c was warmed; its keyframe lands.
+ _goLive(app.paneOfAgent('m', 'c')!.session!);
+ await tester.pump(AgentNeighbourWarmer.delay);
+ await tester.pump();
+
+ expect(app.paneOfAgent('m', 'a'), isNull, reason: 'two swipes away now');
+ expect(app.paneOfAgent('m', 'd')?.session, isNotNull);
+ });
+ });
+}