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:io';
import 'package:fake_async/fake_async.dart';
import 'package:harness/logging/app_log.dart';
import 'package:harness/terminal/terminal_session.dart';
import 'package:harness/terminal/terminal_binary.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter/foundation.dart';
import 'package:xterm/xterm.dart' show Terminal, TerminalTargetPlatform;
void main() {
const streamId = '00112233-4455-6677-8899-aabbccddeeff';
late List<({String type, Map<String, dynamic> payload})> sent;
late List<TerminalBinaryFrame> binarySent;
late TerminalSession session;
DateTime? controlledNow;
setUp(() {
controlledNow = null;
sent = [];
binarySent = [];
session = TerminalSession(
machineId: 'machine-1',
agentId: 'agent-1',
agentName: 'backend-api',
engineId: 'codex',
now: () => controlledNow ?? DateTime.now(),
send: (type, payload) async {
sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
return true;
},
sendBinary: (frame) async {
binarySent.add(frame);
return true;
},
);
});
tearDown(() => session.dispose());
Future<void> ready() async {
await session.open(initialCols: 100, initialRows: 30);
final requestId = sent.single.payload['requestId'];
await session.handleFrame('terminal_ready', {
'requestId': requestId,
'protocolVersion': 3,
'streamId': streamId,
'agentId': 'agent-1',
});
}
TerminalBinaryFrame output(
int seq,
List<int> bytes, {
bool compress = false,
bool keyframe = false,
int? cols,
int? rows,
}) {
final body = compress ? ZLibEncoder(level: 1).convert(bytes) : bytes;
return TerminalBinaryFrame(
kind: keyframe ? TerminalBinaryKind.keyframe : TerminalBinaryKind.output,
streamId: streamId,
seq: seq,
bytes: Uint8List.fromList(body),
compressed: compress,
cols: cols,
rows: rows,
);
}
test('a renderer fault resyncs instead of freezing the pane', () async {
await ready();
await session.handleBinary(
output(0, 'hello'.codeUnits, keyframe: true, cols: 100, rows: 30),
);
expect(session.status, TerminalSessionStatus.controlling);
final before = session.terminal;
// The exception itself comes from deep inside the emulator on some specific
// content — what matters here is that the ANSWER to one is recovery, not a
// frozen tile demanding a manual reattach.
await session.onRendererFailure();
expect(session.status, TerminalSessionStatus.resyncing);
expect(sent.any((frame) => frame.type == 'terminal_resync'), isTrue);
expect(session.errorCode, 'TERMINAL_RENDERER_FAILED');
// The damaged emulator is not written to again: the keyframe that answers
// the resync builds a fresh one, and output frames are dropped until then.
await session.handleBinary(output(1, 'more'.codeUnits));
expect(identical(session.terminal, before), isTrue);
});
test('changing input context withholds typing until the new stream is ready and preserves its terminal', () async {
await ready();
await session.handleBinary(
output(
0,
'retained screen'.codeUnits,
keyframe: true,
cols: 100,
rows: 30,
),
);
final terminal = session.terminal;
expect(session.acceptsInput, isTrue);
session.stageInputContext('context_alpha_123456');
expect(session.acceptsInput, isFalse);
await session.setInputContext('context_alpha_123456');
final opening = sent
.lastWhere((frame) => frame.type == 'terminal_open')
.payload;
expect(opening['inputContext'], 'context_alpha_123456');
expect(identical(session.terminal, terminal), isTrue);
await session.handleFrame('terminal_ready', {
'requestId': opening['requestId'],
'protocolVersion': 3,
'streamId': streamId,
'agentId': 'agent-1',
});
await session.handleBinary(
output(
0,
'retained screen'.codeUnits,
keyframe: true,
cols: 100,
rows: 30,
),
);
expect(session.acceptsInput, isTrue);
final latestTerminal = session.terminal;
expect(await session.sendComposerText('Scoped composed input'), isTrue);
expect(
sent
.lastWhere((frame) => frame.type == 'message')
.payload['inputContext'],
'context_alpha_123456',
);
session.stageInputContext(null);
expect(session.acceptsInput, isFalse);
await session.setInputContext(null);
expect(
sent
.lastWhere((frame) => frame.type == 'terminal_open')
.payload
.containsKey('inputContext'),
isFalse,
);
expect(identical(session.terminal, latestTerminal), isTrue);
});
test(
'a renderer that keeps failing still gives up rather than looping',
() async {
await ready();
await session.handleBinary(
output(0, 'hello'.codeUnits, keyframe: true, cols: 100, rows: 30),
);
for (var attempt = 0; attempt < 8; attempt++) {
await session.onRendererFailure();
}
// Bounded by the existing ladder: three resyncs, then a reopen.
final resyncs = sent.where((f) => f.type == 'terminal_resync').length;
expect(resyncs, lessThanOrEqualTo(3));
},
);
test('a watch-only scope cannot take control or submit text', () async {
await ready();
await session.handleBinary(
output(0, 'screen'.codeUnits, keyframe: true, cols: 100, rows: 30),
);
session.stageInputContext(null, watchOnly: true);
expect(session.readOnly, isTrue);
expect(session.acceptsInput, isFalse);
expect(await session.sendComposerText('Do not send'), isFalse);
await session.setInputContext(null, watchOnly: true);
expect(
sent
.lastWhere((frame) => frame.type == 'terminal_open')
.payload['watchOnly'],
isTrue,
);
expect(sent.where((frame) => frame.type == 'message'), isEmpty);
});
test('a tmux passthrough sequence is swallowed, not painted', () async {
await ready();
// Verbatim shape of what Claude Code emits inside tmux to ask the OUTER
// terminal for its background colour: OSC 11 wrapped in tmux's DCS
// passthrough, which doubles every ESC in the body.
//
// ESC P tmux; ESC ESC ] 11 ; ? BEL ESC \
//
// Untreated it reached the screen as `tmux;]11;?` in the middle of Claude's
// theme picker, because ESC P was an unknown escape and the body then fell
// through to the text path one fragment at a time.
await session.handleBinary(
output(
0,
utf8.encode('1. \x1bPtmux;\x1b\x1b]11;?\x07\x1b\\(match terminal)'),
keyframe: true,
cols: 80,
rows: 24,
),
);
final text = session.terminal.buffer.getText();
expect(text, startsWith('1. (match terminal)'));
expect(text, isNot(contains('tmux;')));
expect(text, isNot(contains(']11;?')));
});
test('an unterminated string sequence never leaks its body', () async {
await ready();
// Split across two writes with no ST in sight: the parser must hold the body
// back rather than print what it has, the same contract OSC keeps.
await session.handleBinary(
output(
0,
utf8.encode('A\x1bPtmux;partial'),
keyframe: true,
cols: 80,
rows: 24,
),
);
expect(session.terminal.buffer.getText(), isNot(contains('partial')));
await session.handleBinary(output(1, utf8.encode('\x1b\\B')));
final text = session.terminal.buffer.getText();
expect(text, startsWith('AB'));
expect(text, isNot(contains('tmux;')));
});
test('CSI erase-left at column zero renders without a resync', () async {
await ready();
await session.handleBinary(
output(
0,
utf8.encode('abc\x1b[1G\x1b[1K'),
keyframe: true,
cols: 80,
rows: 24,
),
);
expect(session.status, TerminalSessionStatus.controlling);
// Cell 0 is now blank (erased), not gone — it copies as a literal leading space, the same as
// any other blank cell with real content after it. See the getText() whitespace test below.
expect(session.terminal.buffer.getText(), startsWith(' bc'));
expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
});
test('copied text keeps cursor-positioned gaps as spaces instead of gluing words together', () async {
await ready();
// TUI-style output (Claude Code, Codex, …) lays out text with cursor-forward moves (CSI C)
// rather than printing literal space bytes — those cells are never written to, so their
// stored codePoint is 0, the same value an erased cell has. Line 1: 3-column indent before
// "indented". Line 2: a 5-column gap between two words.
await session.handleBinary(
output(
0,
utf8.encode('\x1b[3Cindented\r\nfirst\x1b[5Csecond'),
keyframe: true,
cols: 80,
rows: 24,
),
);
final lines = session.terminal.buffer.getText().split('\n');
expect(lines[0], ' indented');
expect(lines[1], 'first second');
// A line with no real content anywhere must still copy as empty, not as columns of padding —
// only the gap BEFORE real content becomes spaces, not blank cells with nothing after them.
expect(lines[2], isEmpty);
});
test(
'uses measured viewport geometry for the initial terminal_open',
() async {
final opening = session.open(
initialCols: 80,
initialRows: 24,
waitForViewportSize: true,
);
await Future<void>.delayed(Duration.zero);
expect(sent, isEmpty);
session.reportViewport(168, 54);
await opening;
expect(sent.single.type, 'terminal_open');
expect(sent.single.payload['cols'], 168);
expect(sent.single.payload['rows'], 54);
expect(session.cols, 168);
expect(session.rows, 54);
},
);
test('opens immediately at fallback size and flushes measured resize after first keyframe', () async {
await session.open();
expect(sent.single.type, 'terminal_open');
expect(sent.single.payload, containsPair('cols', 80));
final requestId = sent.single.payload['requestId'];
session.reportViewport(120, 40);
expect(sent.where((frame) => frame.type == 'terminal_resize'), isEmpty);
await session.handleFrame('terminal_ready', {
'requestId': requestId,
'protocolVersion': 3,
'streamId': streamId,
'agentId': 'agent-1',
});
await session.handleBinary(
output(0, const [], keyframe: true, cols: 80, rows: 24),
);
await Future<void>.delayed(Duration.zero);
expect(
sent.where((frame) => frame.type == 'terminal_resize').single.payload,
containsPair('cols', 120),
);
});
test(
'keyframe + split UTF-8 output render in FIFO order and ACK quickly',
() async {
await ready();
final before = session.terminal;
await session.handleBinary(
output(
0,
utf8.encode('hello '),
compress: true,
keyframe: true,
cols: 100,
rows: 30,
),
);
expect(session.status, TerminalSessionStatus.controlling);
expect(identical(before, session.terminal), isFalse);
final emoji = utf8.encode('😀');
await session.handleBinary(output(1, emoji.sublist(0, 2)));
await session.handleBinary(
output(2, [...emoji.sublist(2), ...utf8.encode(' world')]),
);
expect(session.terminal.buffer.getText(), startsWith('hello 😀 world'));
await Future<void>.delayed(const Duration(milliseconds: 70));
final ack = sent.lastWhere((frame) => frame.type == 'terminal_ack');
expect(ack.payload['lastSeq'], 2);
},
);
test('standalone terminal keeps query replies on its output callback', () {
final emitted = <String>[];
final terminal = Terminal(onOutput: emitted.add)..resize(80, 24);
terminal.write('\x1b[6n\x1b[5n\x1b[c\x1b[>c\x1b[=c\x1b[18t');
expect(emitted, hasLength(6));
expect(emitted.first, '\x1b[0;0R');
});
test(
'remote cursor queries do not inject replies before the first key',
() async {
await ready();
await session.handleBinary(
output(0, utf8.encode('PS> '), keyframe: true, cols: 80, rows: 24),
);
// The host emulator has already answered these. A second cursor reply
// makes Windows PowerShell/PSReadLine swallow the first printable key.
await session.handleBinary(output(1, utf8.encode('\x1b[6n')));
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent, isEmpty);
session.terminal.textInput('a');
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent, hasLength(1));
expect(utf8.decode(binarySent.single.bytes), 'a');
expect(binarySent.single.seq, 0);
},
);
test('remote terminals preserve other query responses', () async {
await ready();
await session.handleBinary(
output(0, utf8.encode('PS> '), keyframe: true, cols: 80, rows: 24),
);
// DA3 is not answered by every host emulator; keep its existing behavior.
await session.handleBinary(output(1, utf8.encode('\x1b[=c')));
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent, hasLength(1));
expect(utf8.decode(binarySent.single.bytes), '\x1bP!|00000000\x1b\\');
});
test(
'terminal input batches, preserves Enter boundary and is never retried',
() async {
// Keep all typed characters inside the 4 ms logical batching window,
// even when a loaded CI host takes longer to schedule the test itself.
controlledNow = DateTime(2026, 9, 18);
await ready();
await session.handleBinary(
output(0, utf8.encode(r'prompt> '), keyframe: true, cols: 80, rows: 24),
);
// Leading edge: the first keystroke after a pause is not held for the batching window.
session.terminal.onOutput?.call('abc');
await Future<void>.delayed(const Duration(milliseconds: 1));
expect(binarySent, hasLength(1));
expect(utf8.decode(binarySent.single.bytes), 'abc');
// Anything arriving inside the window is batched behind the trailing timer instead.
session.terminal.onOutput?.call('d');
session.terminal.onOutput?.call('ef');
expect(binarySent, hasLength(1));
await Future<void>.delayed(const Duration(milliseconds: 12));
session.terminal.onOutput?.call('\r');
await Future<void>.delayed(const Duration(milliseconds: 12));
final inputs = binarySent;
expect(inputs, hasLength(3));
expect(utf8.decode(inputs[0].bytes), 'abc');
expect(utf8.decode(inputs[1].bytes), 'def');
expect(utf8.decode(inputs[2].bytes), '\r');
expect(inputs.map((frame) => frame.seq), [0, 1, 2]);
expect(
inputs.every((frame) => frame.kind == TerminalBinaryKind.input),
isTrue,
);
final paste = '\x1b[200~${'x' * 20000}\x1b[201~';
session.terminal.onOutput?.call(paste);
await Future<void>.delayed(const Duration(milliseconds: 12));
final pasteFrames = binarySent.skip(3).toList();
expect(pasteFrames, hasLength(3));
final pasteBytes = <int>[for (final frame in pasteFrames) ...frame.bytes];
expect(
pasteFrames.every((frame) => frame.bytes.length <= 8 * 1024),
isTrue,
);
expect(utf8.decode(pasteBytes), paste);
session.transportLost();
session.terminal.onOutput?.call('must-not-send');
await Future<void>.delayed(const Duration(milliseconds: 8));
expect(binarySent, hasLength(6));
expect(session.status, TerminalSessionStatus.error);
},
);
test(
'terminal input preserves committed IME Unicode as UTF-8 bytes',
() async {
await ready();
await session.handleBinary(
output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
);
const committed = 'Tiếng Việt 日本語 中文';
session.terminal.onOutput?.call(committed);
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent, hasLength(1));
expect(binarySent.single.bytes, orderedEquals(utf8.encode(committed)));
expect(utf8.decode(binarySent.single.bytes), committed);
},
);
test('malformed PTY UTF-8 renders replacement text without resync', () async {
await ready();
await session.handleBinary(
output(0, utf8.encode('screen '), keyframe: true, cols: 80, rows: 24),
);
await session.handleBinary(output(1, [0x80, ...utf8.encode('tail')]));
expect(session.status, TerminalSessionStatus.controlling);
expect(session.terminal.buffer.getText(), contains('\uFFFDtail'));
expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
});
test(
'local cursor blink preserves the remote cursor visibility state',
() async {
await ready();
await session.handleBinary(
output(
0,
utf8.encode('prompt\x1b[?25h'),
keyframe: true,
cols: 80,
rows: 24,
),
);
session.setCursorBlinkPhase(false);
expect(session.terminal.cursorVisibleMode, isFalse);
// Ordinary output while the paint phase is dark must not become a remote
// cursor-hide command. The next bright phase restores the cursor.
await session.handleBinary(output(1, utf8.encode('x')));
expect(session.terminal.cursorVisibleMode, isFalse);
session.setCursorBlinkPhase(true);
expect(session.terminal.cursorVisibleMode, isTrue);
// An explicit remote hide stays hidden through later blink phases.
await session.handleBinary(output(2, utf8.encode('\x1b[?25l')));
session.setCursorBlinkPhase(false);
session.setCursorBlinkPhase(true);
expect(session.terminal.cursorVisibleMode, isFalse);
},
);
test(
'cursor visibility notifications ignore local blinks and ordinary output',
() async {
await ready();
await session.handleBinary(
output(
0,
utf8.encode('prompt\x1b[?25h'),
keyframe: true,
cols: 100,
rows: 30,
),
);
final visibility = <bool>[];
var sessionChanges = 0;
session.remoteCursorVisibility.addListener(() {
visibility.add(session.remoteCursorVisibility.value);
});
session.addListener(() => sessionChanges++);
expect(session.setCursorBlinkPhase(false), isTrue);
expect(session.setCursorBlinkPhase(false), isFalse);
expect(session.remoteCursorVisibility.value, isTrue);
await session.handleBinary(output(1, utf8.encode('output')));
expect(session.terminal.cursorVisibleMode, isFalse);
expect(visibility, isEmpty);
expect(session.setCursorBlinkPhase(true), isTrue);
await session.handleBinary(output(2, utf8.encode('\x1b[?25l')));
expect(visibility, [false]);
expect(session.setCursorBlinkPhase(false), isFalse);
expect(session.setCursorBlinkPhase(true), isFalse);
// Transient hide/show within one packet does not change the final state.
await session.handleBinary(output(3, utf8.encode('\x1b[?25h\x1b[?25l')));
expect(visibility, [false]);
await session.handleBinary(output(4, utf8.encode('\x1b[?25h')));
expect(visibility, [false, true]);
expect(
sessionChanges,
0,
reason: 'cursor changes must not rebuild the workspace',
);
},
);
test('remote history keyframe survives viewport resize without circular-buffer reflow', () async {
await ready();
final oldStyleHistory = List.generate(
1000,
(index) => '\x1b[3${index % 8}mremote-history-$index\x1b[0m\r\n',
).join();
final keyframe = utf8.encode(
'\x1bc\x1b[?25l\x1b[?7l\x1b[H\x1b[2J\x1b[3J'
'$oldStyleHistory\x1b[1;1Hremote-current-screen\x1b[0m'
'\x1b[20;7H\x1b[?7h\x1b[?25h',
);
await session.handleBinary(
output(0, keyframe, keyframe: true, cols: 154, rows: 48),
);
expect(session.terminal.reflowEnabled, isFalse);
expect(
session.terminal.buffer.getText(),
contains('remote-current-screen'),
);
expect(() => session.terminal.resize(235, 52), returnsNormally);
expect(() => session.terminal.resize(154, 48), returnsNormally);
expect(session.status, TerminalSessionStatus.controlling);
});
test(
'scroll-region output keeps buffer lines attached across frames',
() async {
await ready();
await session.handleBinary(
output(
0,
utf8.encode(
'one\r\ntwo\r\nthree\r\nfour\r\nfive'
'\x1b[2;5r\x1b[5;1H\n',
),
keyframe: true,
cols: 80,
rows: 24,
),
);
// The first partial-region scroll used to leave duplicated, detached
// BufferLine objects. A later top-anchored scroll then crashed inside
// IndexAwareCircularBuffer.insert, matching the Grok live failure.
await session.handleBinary(
output(1, utf8.encode('\x1b[1;5r\x1b[5;1H\nnext')),
);
expect(session.status, TerminalSessionStatus.controlling);
expect(session.terminal.buffer.getText(), contains('next'));
expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
},
);
test(
'reverse-index scroll keeps buffer lines attached across frames',
() async {
await ready();
await session.handleBinary(
output(
0,
utf8.encode(
'one\r\ntwo\r\nthree\r\nfour\r\nfive'
'\x1b[2;5r\x1b[2;1H\x1bM',
),
keyframe: true,
cols: 80,
rows: 24,
),
);
await session.handleBinary(
output(1, utf8.encode('\x1b[1;5r\x1b[5;1H\nnext')),
);
expect(session.status, TerminalSessionStatus.controlling);
expect(session.terminal.buffer.getText(), contains('next'));
expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
},
);
test('Grok keyframes use remote-owned alternate-buffer scrolling', () async {
session.dispose();
session = TerminalSession(
machineId: 'machine-1',
agentId: 'agent-1',
agentName: 'grok-agent',
engineId: 'grok',
send: (type, payload) async {
sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
return true;
},
sendBinary: (frame) async {
binarySent.add(frame);
return true;
},
);
await ready();
final staleRepaints = List.generate(
80,
(index) => '\x1b[31mstale-grok-frame-$index\x1b[0m\r\n',
).join();
await session.handleBinary(
output(
0,
utf8.encode(
'\x1bc\x1b[?25l\x1b[?7l\x1b[H\x1b[2J'
'$staleRepaints'
'\x1b[H\x1b[2J\x1b[?1003h\x1b[?1006h'
'\x1b[1;1Hcurrent-grok-screen\x1b[0m'
'\x1b[5;7H\x1b[?7h\x1b[?25h',
),
keyframe: true,
cols: 80,
rows: 24,
),
);
expect(session.terminal.isUsingAltBuffer, isTrue);
expect(session.terminal.buffer.getText(), contains('current-grok-screen'));
expect(
session.terminal.buffer.getText(),
isNot(contains('stale-grok-frame')),
);
});
test('scrollViaTmuxCopyMode is true only for grok, mirroring _prepareKeyframeBytes', () {
expect(
session.scrollViaTmuxCopyMode,
isFalse,
); // engineId: 'codex' from setUp
});
group('sendScrollCommand (grok only)', () {
Future<void> readyGrokSession() async {
session.dispose();
session = TerminalSession(
machineId: 'machine-1',
agentId: 'agent-1',
agentName: 'grok-agent',
engineId: 'grok',
send: (type, payload) async {
sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
return true;
},
sendBinary: (frame) async {
binarySent.add(frame);
return true;
},
);
await ready();
// acceptsInput (which _flushScrollCommand requires) only becomes true once a keyframe has
// been applied — terminal_ready alone leaves status at `opening`.
await session.handleBinary(
output(0, utf8.encode('grok'), keyframe: true, cols: 100, rows: 30),
);
}
test(
'is a no-op for a non-grok session — codex still uses raw mouseInput',
() async {
await ready();
session.sendScrollCommand(true, 5);
await Future<void>.delayed(const Duration(milliseconds: 30));
expect(sent.where((f) => f.type == 'terminal_scroll'), isEmpty);
},
);
test('coalesces a burst of same-direction deltas into one frame', () async {
await readyGrokSession();
sent.clear();
for (var i = 0; i < 5; i++) {
session.sendScrollCommand(true, 1);
}
expect(
sent.where((f) => f.type == 'terminal_scroll'),
isEmpty,
); // still coalescing
await Future<void>.delayed(const Duration(milliseconds: 30));
final scrolls = sent.where((f) => f.type == 'terminal_scroll').toList();
expect(scrolls, hasLength(1));
expect(scrolls.single.payload['direction'], 'up');
expect(scrolls.single.payload['lines'], 5);
expect(scrolls.single.payload['streamId'], streamId);
});
test(
'a direction reversal mid-burst flushes the first batch separately',
() async {
await readyGrokSession();
sent.clear();
session.sendScrollCommand(true, 3);
session.sendScrollCommand(true, 2);
session.sendScrollCommand(
false,
1,
); // reverses direction — flushes the 5 "up" first
await Future<void>.delayed(const Duration(milliseconds: 30));
final scrolls = sent
.where((f) => f.type == 'terminal_scroll')
.map((f) => f.payload)
.toList();
expect(scrolls, hasLength(2));
expect(scrolls[0]['direction'], 'up');
expect(scrolls[0]['lines'], 5);
expect(scrolls[1]['direction'], 'down');
expect(scrolls[1]['lines'], 1);
},
);
});
test('Ctrl+C (0x03) is forwarded like any other keystroke', () async {
await ready();
await session.handleBinary(
output(0, utf8.encode(r'prompt> '), keyframe: true, cols: 80, rows: 24),
);
session.terminal.onOutput?.call('\x03');
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent, hasLength(1));
expect(utf8.decode(binarySent.single.bytes), '\x03');
session.terminal.onOutput?.call('a\x03b');
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent, hasLength(2));
expect(utf8.decode(binarySent[1].bytes), 'a\x03b');
});
test(
'sequence gap emits one resync and next keyframe replaces state',
() async {
await ready();
await session.handleBinary(
output(
0,
utf8.encode('old screen'),
keyframe: true,
cols: 80,
rows: 24,
),
);
final oldTerminal = session.terminal;
await session.handleBinary(output(2, utf8.encode('gap')));
await session.handleBinary(output(3, utf8.encode('ignored')));
expect(session.status, TerminalSessionStatus.resyncing);
expect(
sent.where((frame) => frame.type == 'terminal_resync'),
hasLength(1),
);
await session.handleBinary(
output(
9,
utf8.encode('new screen'),
keyframe: true,
cols: 90,
rows: 28,
),
);
expect(session.status, TerminalSessionStatus.controlling);
expect(session.errorCode, isNull);
expect(identical(oldTerminal, session.terminal), isFalse);
expect(session.terminal.buffer.getText(), startsWith('new screen'));
expect(session.cols, 90);
expect(session.rows, 28);
},
);
test('a keystroke dropped while resyncing does not leave a hole in the input seq', () async {
// The daemon counts input frames and never re-syncs that counter. A frame this side drops
// — the session went `resyncing` while an earlier send was still in flight — used to take
// its number with it, so the first keystroke after recovery arrived one ahead and was
// refused: TERMINAL_INPUT_INVALID, and a frozen pane over a perfectly good tmux.
final gate = Completer<void>();
final frames = <TerminalBinaryFrame>[];
final blocking = TerminalSession(
machineId: 'machine-1',
agentId: 'agent-1',
agentName: 'backend-api',
engineId: 'codex',
send: (type, payload) async {
sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
return true;
},
sendBinary: (frame) async {
frames.add(frame);
if (frames.length == 1) await gate.future; // the first send stalls
return true;
},
);
addTearDown(blocking.dispose);
await blocking.open(initialCols: 100, initialRows: 30);
await blocking.handleFrame('terminal_ready', {
'requestId': sent.single.payload['requestId'],
'protocolVersion': 3,
'streamId': streamId,
'agentId': 'agent-1',
});
await blocking.handleBinary(
output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
);
blocking.terminal.onOutput?.call('a'); // seq 0, send stalls on the gate
await Future<void>.delayed(const Duration(milliseconds: 1));
blocking.terminal.onOutput?.call('b'); // queued behind it
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(frames, hasLength(1));
// The output stream skips a number: resync, same stream.
await blocking.handleBinary(output(5, utf8.encode('gap')));
expect(blocking.status, TerminalSessionStatus.resyncing);
gate.complete(); // 'a' goes out; 'b' reaches the tail while resyncing and is dropped
await Future<void>.delayed(const Duration(milliseconds: 1));
await blocking.handleBinary(
output(9, utf8.encode('fresh'), keyframe: true, cols: 80, rows: 24),
);
expect(blocking.status, TerminalSessionStatus.controlling);
blocking.terminal.onOutput?.call('c');
await Future<void>.delayed(const Duration(milliseconds: 12));
final inputs = frames.where((f) => f.kind == TerminalBinaryKind.input);
expect(inputs.map((f) => utf8.decode(f.bytes)), ['a', 'c']);
// Contiguous: the dropped 'b' did not spend a number.
expect(inputs.map((f) => f.seq), [0, 1]);
});
test(
'TERMINAL_INPUT_INVALID with expectedSeq realigns in place, nothing frozen',
() async {
await ready();
await session.handleBinary(
output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
);
session.terminal.onOutput?.call('a');
await Future<void>.delayed(const Duration(milliseconds: 12));
session.terminal.onOutput?.call('b');
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent.map((f) => f.seq), [0, 1]);
// The daemon only ever saw seq 0 — say it is still waiting for 1.
await session.handleFrame('terminal_error', {
'streamId': streamId,
'code': 'TERMINAL_INPUT_INVALID',
'reason': 'seq',
'expectedSeq': 1,
});
expect(session.status, TerminalSessionStatus.controlling);
expect(session.errorCode, isNull);
expect(sent.where((f) => f.type == 'terminal_close'), isEmpty);
expect(sent.where((f) => f.type == 'terminal_open'), hasLength(1));
session.terminal.onOutput?.call('c');
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent.last.seq, 1);
expect(utf8.decode(binarySent.last.bytes), 'c');
},
);
test('a stale duplicate TERMINAL_INPUT_INVALID does not rewind a counter that moved on', () async {
// The daemon refuses every in-flight frame it cannot take, each naming
// the same expected seq. By the time the second refusal lands, the
// first has already realigned us and frames under the new numbers have
// been accepted — rewinding again would reuse them.
await ready();
await session.handleBinary(
output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
);
session.terminal.onOutput?.call('a');
await Future<void>.delayed(const Duration(milliseconds: 12));
session.terminal.onOutput?.call('b');
await Future<void>.delayed(const Duration(milliseconds: 12));
session.terminal.onOutput?.call('c');
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent.map((f) => f.seq), [0, 1, 2]);
// Both 'b' (1) and 'c' (2) were refused: the daemon still wants 1.
final refusal = {
'streamId': streamId,
'code': 'TERMINAL_INPUT_INVALID',
'reason': 'seq',
'expectedSeq': 1,
};
await session.handleFrame('terminal_error', refusal);
session.terminal.onOutput?.call('d'); // goes out as 1, accepted
await Future<void>.delayed(const Duration(milliseconds: 12));
await session.handleFrame('terminal_error', refusal); // the stale one
session.terminal.onOutput?.call('e');
await Future<void>.delayed(const Duration(milliseconds: 12));
final after = binarySent.skip(3).toList();
expect(after.map((f) => utf8.decode(f.bytes)), ['d', 'e']);
expect(after.map((f) => f.seq), [1, 2]);
expect(session.status, TerminalSessionStatus.controlling);
// A genuinely new gap names a larger seq and is honoured.
await session.handleFrame('terminal_error', {...refusal, 'expectedSeq': 2});
session.terminal.onOutput?.call('f');
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent.last.seq, 2);
});
test(
'TERMINAL_INPUT_INVALID from an older daemon reopens instead of freezing',
() async {
await ready();
await session.handleBinary(
output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
);
session.terminal.onOutput?.call('a');
await Future<void>.delayed(const Duration(milliseconds: 12));
// No expectedSeq: a daemon from before it said. The only way back in step is a new stream.
await session.handleFrame('terminal_error', {
'streamId': streamId,
'code': 'TERMINAL_INPUT_INVALID',
});
expect(session.status, isNot(TerminalSessionStatus.error));
expect(sent.where((f) => f.type == 'terminal_close'), hasLength(1));
final opens = sent.where((f) => f.type == 'terminal_open').toList();
expect(opens, hasLength(2));
const newStream = 'ffeeddcc-bbaa-9988-7766-554433221100';
await session.handleFrame('terminal_ready', {
'requestId': opens.last.payload['requestId'],
'protocolVersion': 3,
'streamId': newStream,
'agentId': 'agent-1',
});
await session.handleBinary(
TerminalBinaryFrame(
kind: TerminalBinaryKind.keyframe,
streamId: newStream,
seq: 0,
bytes: Uint8List.fromList(utf8.encode('prompt> ')),
compressed: false,
cols: 80,
rows: 24,
),
);
expect(session.status, TerminalSessionStatus.controlling);
session.terminal.onOutput?.call('b');
await Future<void>.delayed(const Duration(milliseconds: 12));
expect(binarySent.last.streamId, newStream);
expect(binarySent.last.seq, 0);
},
);
test(
'input larger than the daemon accepts is split, never refused',
() async {
await ready();
await session.handleBinary(
output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
);
// Bypass the 8 KiB chunker's boundaries: one contiguous burst of 70,000 bytes.
session.terminal.onOutput?.call('x' * 70000);
await Future<void>.delayed(const Duration(milliseconds: 12));
final inputs = binarySent
.where((f) => f.kind == TerminalBinaryKind.input)
.toList();
expect(
inputs.every(
(f) => f.bytes.length <= TerminalSession.kInputFrameMaxBytes,
),
isTrue,
);
expect(inputs.map((f) => f.seq), List.generate(inputs.length, (i) => i));
expect(inputs.fold<int>(0, (n, f) => n + f.bytes.length), 70000);
},
);
test(
'idle sync advances sequence and is acknowledged after render',
() async {
await ready();
await session.handleBinary(
output(0, utf8.encode('screen'), keyframe: true, cols: 80, rows: 24),
);
await session.handleBinary(
TerminalBinaryFrame(
kind: TerminalBinaryKind.sync,
streamId: streamId,
seq: 1,
bytes: Uint8List(0),
compressed: false,
),
);
await Future<void>.delayed(const Duration(milliseconds: 30));
expect(session.status, TerminalSessionStatus.controlling);
expect(
sent
.lastWhere((frame) => frame.type == 'terminal_ack')
.payload['lastSeq'],
1,
);
},
);
test(
'takeover freezes the rendered terminal until the user reconnects',
() async {
await ready();
await session.handleBinary(
output(
0,
utf8.encode('last screen'),
keyframe: true,
cols: 80,
rows: 24,
),
);
await session.handleFrame('terminal_closed', {
'streamId': streamId,
'code': 'TERMINAL_TAKEN_OVER',
'reason': 'another client connected',
});
expect(session.status, TerminalSessionStatus.takenOver);
expect(session.acceptsInput, isFalse);
expect(session.errorCode, 'TERMINAL_TAKEN_OVER');
expect(session.errorMessage, contains('Another client'));
expect(session.terminal.buffer.getText(), contains('last screen'));
// A WS hiccup on this machine (node offline/online) must not turn a takeover into a plain
// `error`, which auto-reattach would then silently reopen — re-stealing the terminal back
// from whoever took it over.
session.transportLost('Harness reconnected; restoring terminal…');
expect(session.status, TerminalSessionStatus.takenOver);
},
);
// Who took the terminal rides on the close (`takenBy`), so the banner can
// name them; the name goes away with the next open, so a retaken pane never
// shows a stale one.
test('a takeover names its taker when the daemon says who', () async {
await ready();
await session.handleFrame('terminal_closed', {
'streamId': streamId,
'code': 'TERMINAL_TAKEN_OVER',
'reason': 'another client connected',
'takenBy': {
'kind': 'desktop',
'name': 'Mac mini',
'machineId': 'ab12ab12ab12ab12',
},
});
expect(session.status, TerminalSessionStatus.takenOver);
expect(session.takenOverBy?.name, 'Mac mini');
expect(session.takenOverBy?.kind, 'desktop');
expect(session.takenOverBy?.machineId, 'ab12ab12ab12ab12');
expect(session.errorMessage, contains('Mac mini'));
// The fleet's current name for that machine wins over the declared one.
expect(
session.takenOverBy!.label(
(id) => id == 'ab12ab12ab12ab12' ? 'Studio' : null,
),
'Studio',
);
expect(session.takenOverBy!.label((_) => null), 'Mac mini');
await session.reopen();
expect(session.takenOverBy, isNull);
});
test(
'a takeover with no or a malformed taker reads as another app',
() async {
await ready();
await session.handleFrame('terminal_closed', {
'streamId': streamId,
'code': 'TERMINAL_TAKEN_OVER',
'takenBy': {'kind': 'not a kind', 'name': 'x'},
});
expect(session.status, TerminalSessionStatus.takenOver);
expect(session.takenOverBy, isNull);
expect(session.errorMessage, contains('Another client'));
expect(
TerminalClientDescriptor.fromJson({'kind': 'phone', 'name': ' iPhone '})
?.name,
'iPhone',
);
expect(
TerminalClientDescriptor.fromJson({
'kind': 'desktop',
'name': 'a',
'machineId': '../x',
}),
isNull,
);
expect(TerminalClientDescriptor.fromJson('Mac'), isNull);
},
);
test(
'terminal_open carries this client\'s introduction when it has one',
() async {
final introduced = TerminalSession(
machineId: 'machine-1',
agentId: 'agent-1',
agentName: 'backend-api',
engineId: 'codex',
client: const TerminalClientDescriptor(
kind: 'desktop',
name: 'This Mac',
machineId: 'ab12ab12ab12ab12',
),
send: (type, payload) async {
sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
return true;
},
sendBinary: (_) async => true,
);
addTearDown(introduced.dispose);
await introduced.open(initialCols: 100, initialRows: 30);
expect(sent.single.payload['client'], {
'kind': 'desktop',
'name': 'This Mac',
'machineId': 'ab12ab12ab12ab12',
});
sent.clear();
await session.open(initialCols: 100, initialRows: 30);
expect(sent.single.payload.containsKey('client'), isFalse);
},
);
test(
'terminal_link_mode updates linkMode, ignoring a stale stream id',
() async {
await ready();
expect(session.linkMode, isNull);
await session.handleFrame('terminal_link_mode', {
'streamId': streamId,
'mode': 'p2p',
});
expect(session.linkMode, 'p2p');
await session.handleFrame('terminal_link_mode', {
'streamId': streamId,
'mode': 'relay',
});
expect(session.linkMode, 'relay');
// A frame for a DIFFERENT (stale) stream id must not touch this session's state.
await session.handleFrame('terminal_link_mode', {
'streamId': 'some-other-stream',
'mode': 'p2p',
});
expect(session.linkMode, 'relay');
},
);
test('terminal_link_mode accepts turn, the third transport, alongside the other two', () async {
await ready();
// 'turn' is additive: 'relay' keeps meaning the backend WebSocket, so a build that predates TURN
// can never read a Cloudflare-relayed session as a WS-relayed one.
for (final mode in ['p2p', 'turn', 'relay']) {
await session.handleFrame('terminal_link_mode', {
'streamId': streamId,
'mode': mode,
});
expect(session.linkMode, mode);
}
});
test(
'a mode this build cannot draw leaves the last known one alone',
() async {
await ready();
await session.handleFrame('terminal_link_mode', {
'streamId': streamId,
'mode': 'turn',
});
expect(session.linkMode, 'turn');
// A newer CLI inventing a fourth value must not blank the badge or set a value the header has no
// icon for — the allow-list is what keeps linkMode drawable.
await session.handleFrame('terminal_link_mode', {
'streamId': streamId,
'mode': 'quic',
});
expect(session.linkMode, 'turn');
},
);
test(
'linkMode resets whenever streamId resets (reopen/close/error)',
() async {
await ready();
await session.handleFrame('terminal_link_mode', {
'streamId': streamId,
'mode': 'p2p',
});
expect(session.linkMode, 'p2p');
await session.handleFrame('terminal_closed', {
'streamId': streamId,
'reason': 'closed by peer',
});
expect(session.streamId, isNull);
expect(session.linkMode, isNull);
},
);
group('stream liveness', () {
setUp(() => controlledNow = DateTime.utc(2026));
Future<void> tick(WidgetTester tester, Duration elapsed) async {
controlledNow = controlledNow!.add(elapsed);
await tester.pump(elapsed);
}
Future<void> live() async {
await ready();
await session.handleBinary(
output(
0,
utf8.encode('retained screen'),
keyframe: true,
cols: 100,
rows: 30,
),
);
}
TerminalBinaryFrame sync(int seq, {String id = streamId}) =>
TerminalBinaryFrame(
kind: TerminalBinaryKind.sync,
streamId: id,
seq: seq,
bytes: Uint8List(0),
compressed: false,
);
for (final watching in [false, true]) {
testWidgets(
'a silently replaced stream recovers without replaying input (watching=$watching)',
(tester) async {
await live();
final retained = session.terminal;
session.terminal.textInput('sent before disconnect');
await tester.pump(const Duration(milliseconds: 5));
binarySent.clear();
for (var i = 0; i < 3; i++) {
await tick(tester, const Duration(seconds: 5));
}
expect(session.status, TerminalSessionStatus.resyncing);
expect(session.errorCode, 'TERMINAL_STREAM_TIMEOUT');
expect(session.acceptsInput, isFalse);
expect(session.terminal, same(retained));
// Nothing answers for the vanished stream. Use the existing bounded ladder.
for (var i = 0; i < 3; i++) {
await tick(tester, const Duration(seconds: 4));
}
final opens = sent
.where((frame) => frame.type == 'terminal_open')
.toList();
expect(opens, hasLength(2));
expect(opens.last.payload['takeover'], isFalse);
expect(session.status, TerminalSessionStatus.opening);
expect(session.terminal, same(retained));
// The daemon now reports replacement explicitly. A late close for the old
// stream must not kill the reopen this view already asked for.
await session.handleFrame('terminal_closed', {
'streamId': streamId,
'code': 'TERMINAL_TAKEN_OVER',
'reason': 'terminal reopened in another view',
});
expect(session.status, TerminalSessionStatus.opening);
const replacementId = '11112233-4455-6677-8899-aabbccddeeff';
await session.handleFrame('terminal_ready', {
'requestId': opens.last.payload['requestId'],
'protocolVersion': 3,
'streamId': replacementId,
'agentId': 'agent-1',
'readOnly': watching,
});
expect(session.acceptsInput, isFalse);
await session.handleBinary(
TerminalBinaryFrame(
kind: TerminalBinaryKind.keyframe,
streamId: replacementId,
seq: 0,
bytes: Uint8List.fromList(utf8.encode('reconnected screen')),
compressed: false,
cols: 100,
rows: 30,
),
);
expect(session.acceptsInput, !watching);
expect(
binarySent,
isEmpty,
reason: 'Input on the retired stream is never replayed',
);
session.terminal.textInput('new input');
await tester.pump(const Duration(milliseconds: 5));
if (watching) {
expect(binarySent, isEmpty);
} else {
expect(binarySent.single.streamId, replacementId);
expect(utf8.decode(binarySent.single.bytes), 'new input');
}
await session.close();
},
);
}
testWidgets('a live stream that answers resync keeps its lease', (
tester,
) async {
await live();
await tick(tester, const Duration(seconds: 15));
expect(session.status, TerminalSessionStatus.resyncing);
await session.handleBinary(
output(
5,
utf8.encode('fresh snapshot'),
keyframe: true,
cols: 100,
rows: 30,
),
);
expect(session.acceptsInput, isTrue);
expect(session.errorCode, isNull);
await tick(tester, const Duration(seconds: 5));
await session.handleBinary(sync(6));
expect(session.acceptsInput, isTrue);
expect(
sent.where((frame) => frame.type == 'terminal_open'),
hasLength(1),
);
await session.close();
});
for (final kind in ['sync', 'output']) {
testWidgets('$kind frames keep a live terminal healthy', (tester) async {
await live();
for (var seq = 1; seq <= 8; seq++) {
await tick(tester, const Duration(seconds: 5));
await session.handleBinary(
kind == 'sync' ? sync(seq) : output(seq, utf8.encode('text')),
);
}
expect(session.acceptsInput, isTrue);
expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
expect(
sent.where((frame) => frame.type == 'terminal_open'),
hasLength(1),
);
await session.close();
});
}
testWidgets('traffic for other panes cannot hide a stale terminal', (
tester,
) async {
await live();
for (var seq = 1; seq <= 3; seq++) {
await session.handleBinary(sync(seq, id: 'another-pane'));
await session.handleFrame('terminal_link_mode', {
'streamId': streamId,
'mode': 'turn',
});
await tick(tester, const Duration(seconds: 5));
}
expect(session.status, TerminalSessionStatus.resyncing);
expect(session.errorCode, 'TERMINAL_STREAM_TIMEOUT');
await session.close();
});
testWidgets(
'a reported takeover waits for the user instead of reconnecting',
(tester) async {
await live();
await session.handleFrame('terminal_closed', {
'streamId': streamId,
'code': 'TERMINAL_TAKEN_OVER',
'reason': 'terminal reopened in another view',
});
await tick(tester, const Duration(seconds: 60));
expect(session.status, TerminalSessionStatus.takenOver);
expect(session.acceptsInput, isFalse);
expect(
sent.where((frame) => frame.type == 'terminal_open'),
hasLength(1),
);
expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
await session.close();
},
);
});
testWidgets('resync retries three times, reopens once, then fails closed', (
tester,
) async {
session.dispose();
session = TerminalSession(
machineId: 'machine-1',
agentId: 'agent-1',
agentName: 'backend-api',
engineId: 'codex',
resyncTimeout: const Duration(milliseconds: 5),
send: (type, payload) async {
sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
return true;
},
sendBinary: (frame) async {
binarySent.add(frame);
return true;
},
);
await ready();
await session.handleBinary(
output(0, utf8.encode('screen'), keyframe: true, cols: 80, rows: 24),
);
await session.handleBinary(output(2, utf8.encode('gap')));
// Advance the retry clock deterministically; an overloaded test runner
// can wake a 45 ms wall-clock wait before the last 5 ms retry is armed.
await tester.pump(const Duration(milliseconds: 45));
expect(
sent.where((frame) => frame.type == 'terminal_resync'),
hasLength(3),
);
expect(sent.where((frame) => frame.type == 'terminal_open'), hasLength(2));
expect(sent.where((frame) => frame.type == 'terminal_close'), hasLength(1));
expect(session.status, TerminalSessionStatus.error);
expect(session.errorCode, 'TERMINAL_RESYNC_TIMEOUT');
});
testWidgets(
'heartbeats and resyncs ask the daemon to report a stream it no longer has',
(tester) async {
session.dispose();
session = TerminalSession(
machineId: 'machine-1',
agentId: 'agent-1',
agentName: 'backend-api',
engineId: 'codex',
resyncTimeout: const Duration(seconds: 30),
send: (type, payload) async {
sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
return true;
},
sendBinary: (frame) async => true,
);
await ready();
await session.handleBinary(
output(0, utf8.encode('screen'), keyframe: true, cols: 80, rows: 24),
);
await tester.pump(const Duration(seconds: 5));
expect(
sent.lastWhere((frame) => frame.type == 'terminal_alive').payload,
{'streamId': streamId, 'reportMissing': true},
);
await session.handleBinary(output(2, utf8.encode('gap')));
await tester.pump();
expect(
sent
.firstWhere((frame) => frame.type == 'terminal_resync')
.payload['reportMissing'],
isTrue,
);
await session.close();
},
);
test('a reopen that may not redial leaves the machine link alone', () async {
var redials = 0;
TerminalSession stalled() => TerminalSession(
machineId: 'machine-1',
agentId: 'agent-1',
agentName: 'backend-api',
engineId: 'codex',
send: (type, payload) async => type != 'terminal_open',
sendBinary: (frame) async => true,
onOpenStalled: () async => redials++,
);
final quiet = stalled();
addTearDown(quiet.dispose);
await quiet.reopen(redial: false);
expect(redials, 0);
expect(quiet.status, TerminalSessionStatus.error);
final loud = stalled();
final reopening = loud.reopen();
await pumpEventQueue();
expect(redials, 1);
loud.dispose();
await reopening;
});
test(
'a stream the daemon no longer has is reopened in place at once',
() async {
await ready();
await session.handleBinary(
output(0, utf8.encode('screen'), keyframe: true, cols: 100, rows: 30),
);
await session.handleFrame('terminal_error', {
'streamId': streamId,
'code': 'TERMINAL_STREAM_NOT_FOUND',
'message': 'no live terminal stream',
});
await pumpEventQueue();
expect(
sent.where((frame) => frame.type == 'terminal_open'),
hasLength(2),
);
expect(session.status, TerminalSessionStatus.opening);
expect(session.errorCode, isNot('TERMINAL_STREAM_NOT_FOUND'));
},
);
test('a missing-stream report about another stream is ignored', () async {
await ready();
await session.handleFrame('terminal_error', {
'streamId': 'ffffffff-ffff-ffff-ffff-ffffffffffff',
'code': 'TERMINAL_STREAM_NOT_FOUND',
});
await pumpEventQueue();
expect(sent.where((frame) => frame.type == 'terminal_open'), hasLength(1));
expect(session.status, isNot(TerminalSessionStatus.error));
});
test('a failure is written to the file log with its code', () async {
final log = _RecordingLog();
final previous = appLog;
appLog = log;
addTearDown(() => appLog = previous);
await ready();
await session.handleFrame('terminal_error', {
'streamId': streamId,
'code': 'TERMINAL_SNAPSHOT_FAILED',
'message': 'tmux snapshot failed',
});
expect(
log.lines,
contains(
'terminal failed machine=machine-1 agent=agent-1 stream=$streamId '
'code=TERMINAL_SNAPSHOT_FAILED message=tmux snapshot failed',
),
);
});
group('slow input log', () {
late _RecordingLog log;
Future<void> typing() async {
log = _RecordingLog();
final previous = appLog;
appLog = log;
addTearDown(() => appLog = previous);
controlledNow = DateTime(2026, 10, 19, 10);
await ready();
await session.handleBinary(
output(0, utf8.encode(r'$ '), keyframe: true, cols: 100, rows: 30),
);
session.terminal.onOutput?.call('a');
await pumpEventQueue();
expect(binarySent, hasLength(1));
}
List<String> slow() =>
log.lines.where((line) => line.contains('input ')).toList();
test('an echo that comes back late is logged with the wait', () async {
await typing();
controlledNow = controlledNow!.add(const Duration(seconds: 9));
await session.handleBinary(output(1, utf8.encode('a')));
await pumpEventQueue();
expect(slow(), [
'terminal input answered late machine=machine-1 agent=agent-1 stream=$streamId '
'link=null waitedMs=9000 by=output',
]);
});
test('a prompt echo is not logged', () async {
await typing();
controlledNow = controlledNow!.add(const Duration(milliseconds: 300));
await session.handleBinary(output(1, utf8.encode('a')));
await pumpEventQueue();
expect(slow(), isEmpty);
});
test(
'an idle sync after unechoed input is not logged inside its cadence',
() async {
await typing();
controlledNow = controlledNow!.add(const Duration(seconds: 8));
await session.handleBinary(
TerminalBinaryFrame(
kind: TerminalBinaryKind.sync,
streamId: streamId,
seq: 1,
bytes: Uint8List(0),
compressed: false,
),
);
await pumpEventQueue();
expect(slow(), isEmpty);
},
);
test('a stream timeout with typing still waiting is logged', () async {
await typing();
controlledNow = controlledNow!.add(const Duration(seconds: 16));
session.transportLost();
expect(slow(), [
'terminal input unanswered machine=machine-1 agent=agent-1 stream=$streamId '
'link=null waitedMs=16000 until=transport_lost',
]);
});
});
group('composer', () {
/// The `message` frames this session put on the wire.
List<Map<String, dynamic>> messages() => [
for (final frame in sent)
if (frame.type == 'message') frame.payload,
];
Future<void> live() async {
await ready();
await session.handleBinary(
output(0, utf8.encode(r'$ '), keyframe: true, cols: 100, rows: 30),
);
sent.clear();
}
test('drives a turn with the same frame the web client uses', () async {
await live();
expect(await session.sendComposerText('run the tests'), isTrue);
expect(messages(), hasLength(1));
expect(messages().single['content'], 'run the tests');
expect(messages().single['agentId'], 'agent-1');
expect(messages().single['mode'], 'auto');
// Nothing is typed into the pane: injection is the machine's job, and doing it here is what
// left a composed line sitting unsent in Codex.
expect(binarySent, isEmpty);
});
test('carries a multi-line body through verbatim', () async {
await live();
expect(await session.sendComposerText('first line\nsecond line'), isTrue);
// No bracketed-paste wrapping of our own — the machine decides how to inject it.
expect(messages().single['content'], 'first line\nsecond line');
expect(messages().single['content'], isNot(contains('\x1b[200~')));
});
test('drops a trailing newline so it cannot double the submit', () async {
await live();
expect(await session.sendComposerText('ship it\n'), isTrue);
expect(messages().single['content'], 'ship it');
});
test('forwards Ctrl+C in composed text rather than stripping it', () async {
await live();
expect(await session.sendComposerText('a\x03b'), isTrue);
expect(messages().single['content'], 'a\x03b');
});
test('sends nothing while the stream is not accepting input', () async {
expect(session.acceptsInput, isFalse);
expect(await session.sendComposerText('should not go'), isFalse);
expect(messages(), isEmpty);
});
test('sends nothing for a body that is only whitespace', () async {
await live();
expect(await session.sendComposerText(''), isFalse);
expect(await session.sendComposerText(' \n '), isFalse);
expect(messages(), isEmpty);
});
});
group('pasteText', () {
/// The `TerminalBinaryKind.paste` frames this session put on the wire.
List<TerminalBinaryFrame> pastes() => [
for (final frame in binarySent)
if (frame.kind == TerminalBinaryKind.paste) frame,
];
Future<void> live() async {
await ready();
await session.handleBinary(
output(0, utf8.encode(r'$ '), keyframe: true, cols: 100, rows: 30),
);
sent.clear();
binarySent.clear();
}
test(
'sends the whole clipboard as one binary frame, not chunked',
() async {
await live();
final big = List.generate(200, (i) => 'line $i').join('\n');
expect(await session.pasteText(big), isTrue);
expect(pastes(), hasLength(1));
expect(utf8.decode(pastes().single.bytes), big);
expect(pastes().single.streamId, streamId);
expect(pastes().single.compressed, isFalse);
// Never through the ordinary keystroke pipeline this feature exists to avoid, and never as JSON.
expect(
binarySent.where((f) => f.kind == TerminalBinaryKind.input),
isEmpty,
);
expect(sent, isEmpty);
},
);
test('forwards Ctrl+C in a paste rather than stripping it', () async {
await live();
expect(await session.pasteText('a\x03b'), isTrue);
expect(utf8.decode(pastes().single.bytes), 'a\x03b');
});
test('sends nothing while the stream is not accepting input', () async {
expect(session.acceptsInput, isFalse);
expect(await session.pasteText('should not go'), isFalse);
expect(pastes(), isEmpty);
});
test('sends nothing for an empty paste', () async {
await live();
expect(await session.pasteText(''), isFalse);
expect(pastes(), isEmpty);
});
test('a rejected paste (too large/empty) leaves the stream alive, unlike every other terminal_error', () async {
await live();
final handled = await session.handleFrame('terminal_error', {
'streamId': streamId,
'code': 'TERMINAL_PASTE_INVALID',
'message': 'paste too large',
});
expect(handled, isTrue);
expect(session.status, TerminalSessionStatus.controlling);
expect(session.streamId, streamId);
expect(session.errorCode, isNull);
});
test('a real paste delivery failure still freezes the stream, like resize/input failures do', () async {
await live();
await session.handleFrame('terminal_error', {
'streamId': streamId,
'code': 'TERMINAL_PASTE_FAILED',
'message': 'tmux paste-buffer could not be sent',
});
expect(session.status, TerminalSessionStatus.error);
expect(session.errorCode, 'TERMINAL_PASTE_FAILED');
});
});
group('pasteImage / pasteFile — chunked upload', () {
List<TerminalBinaryFrame> imagePastes() => [
for (final frame in binarySent)
if (frame.kind == TerminalBinaryKind.imagePaste) frame,
];
List<TerminalBinaryFrame> filePastes() => [
for (final frame in binarySent)
if (frame.kind == TerminalBinaryKind.pasteFile) frame,
];
Future<void> live() async {
await ready();
await session.handleBinary(
output(0, utf8.encode(r'$ '), keyframe: true, cols: 100, rows: 30),
);
sent.clear();
binarySent.clear();
}
/// Lets the microtasks/event-loop turns between `session.pasteImage`/`pasteFile`'s internal
/// awaits (send → await begin_result → send chunks → await the result frame) actually run,
/// so the test can inject the simulated server replies in between.
Future<void> pump() => Future<void>.delayed(Duration.zero);
Future<void> acceptBegin() async {
await pump();
expect(
sent
.where((frame) => frame.type == 'terminal_chunked_upload_begin')
.single
.type,
'terminal_chunked_upload_begin',
);
await session.handleFrame('terminal_chunked_upload_begin_result', {
'streamId': streamId,
'accepted': true,
});
}
test(
'image: begin → one chunk → result, and reports live progress',
() async {
await live();
final png = Uint8List.fromList(const [
0x89,
0x50,
0x4e,
0x47,
0x0d,
0x0a,
0x1a,
0x0a,
0xff,
]);
final future = session.pasteImage(png);
await acceptBegin();
expect(
sent
.where((frame) => frame.type == 'terminal_chunked_upload_begin')
.single
.payload,
containsPair('uploadKind', 'image'),
);
expect(
sent
.where((frame) => frame.type == 'terminal_chunked_upload_begin')
.single
.payload,
containsPair('totalBytes', png.length),
);
expect(
sent
.where((frame) => frame.type == 'terminal_chunked_upload_begin')
.single
.payload,
isNot(contains('filename')),
);
await pump();
expect(imagePastes(), hasLength(1));
expect(imagePastes().single.bytes, png);
expect(imagePastes().single.seq, 0);
expect(imagePastes().single.compressed, isFalse);
// Never through the ordinary keystroke pipeline or the text-paste kind.
expect(
binarySent.where((f) => f.kind == TerminalBinaryKind.input),
isEmpty,
);
expect(
binarySent.where((f) => f.kind == TerminalBinaryKind.paste),
isEmpty,
);
expect(session.uploadProgress, isNotNull);
await session.handleFrame('terminal_chunked_upload_progress', {
'streamId': streamId,
'bytesWritten': png.length,
'totalBytes': png.length,
});
expect(session.uploadProgress!.percent, 1.0);
await session.handleFrame('terminal_paste_image_result', {
'streamId': streamId,
'outcome': 'clipboard',
});
expect(await future, isTrue);
expect(session.uploadProgress, isNull); // cleared once finished
},
);
test(
'file: begin carries the filename, and the result frame finishes it',
() async {
await live();
final content = Uint8List.fromList(const [0x25, 0x50, 0x44, 0x46]);
final future = session.pasteFile('report.pdf', content);
await acceptBegin();
expect(
sent
.where((frame) => frame.type == 'terminal_chunked_upload_begin')
.single
.payload,
containsPair('uploadKind', 'file'),
);
expect(
sent
.where((frame) => frame.type == 'terminal_chunked_upload_begin')
.single
.payload,
containsPair('filename', 'report.pdf'),
);
await pump();
expect(filePastes(), hasLength(1));
expect(filePastes().single.bytes, content);
await session.handleFrame('terminal_paste_file_result', {
'streamId': streamId,
'path': '/remote/path/report.pdf',
});
expect(await future, isTrue);
},
);
test(
'splits a large image across several chunks, indexed by seq',
() async {
await live();
final big = Uint8List(terminalUploadChunkBytes * 2 + 100)
..fillRange(0, terminalUploadChunkBytes * 2 + 100, 0xab);
final future = session.pasteImage(big);
await acceptBegin();
await pump();
expect(imagePastes(), hasLength(3));
expect(imagePastes().map((f) => f.seq), [0, 1, 2]);
expect(imagePastes()[0].bytes, hasLength(terminalUploadChunkBytes));
expect(imagePastes()[1].bytes, hasLength(terminalUploadChunkBytes));
expect(imagePastes()[2].bytes, hasLength(100));
await session.handleFrame('terminal_paste_image_result', {
'streamId': streamId,
'outcome': 'clipboard',
});
expect(await future, isTrue);
},
);
test(
'resolves false, with no chunks sent, when begin is not accepted',
() async {
await live();
final png = Uint8List.fromList(const [1, 2, 3]);
final future = session.pasteImage(png);
await pump();
await session.handleFrame('terminal_chunked_upload_begin_result', {
'streamId': streamId,
'accepted': false,
'reason': 'exceeds the 8 MB limit',
});
expect(await future, isFalse);
expect(imagePastes(), isEmpty);
expect(session.uploadProgress, isNull);
expect(session.acceptsInput, isTrue);
expect(sent.where((frame) => frame.type == 'terminal_open'), isEmpty);
expect(
sent.where((frame) => frame.type == 'terminal_chunked_upload_cancel'),
isEmpty,
);
},
);
test('cancels an upload the daemon still holds for this pane, then begins again', () async {
await live();
final png = Uint8List.fromList(const [1, 2, 3]);
final future = session.pasteImage(png);
await pump();
await session.handleFrame('terminal_chunked_upload_begin_result', {
'streamId': streamId,
'accepted': false,
'reason': 'an upload is already in progress on this pane',
});
await pump();
expect(sent.map((frame) => frame.type), [
'terminal_chunked_upload_begin',
'terminal_chunked_upload_cancel',
'terminal_chunked_upload_begin',
]);
expect(imagePastes(), isEmpty);
await session.handleFrame('terminal_chunked_upload_begin_result', {
'streamId': streamId,
'accepted': true,
});
await pump();
expect(imagePastes().single.bytes, png);
await session.handleFrame('terminal_paste_image_result', {
'streamId': streamId,
'outcome': 'clipboard',
});
expect(await future, isTrue);
});
test(
'asks only once more when the daemon still says an upload is in progress',
() async {
await live();
final future = session.pasteImage(Uint8List.fromList(const [1]));
for (var answer = 0; answer < 2; answer++) {
await pump();
await session.handleFrame('terminal_chunked_upload_begin_result', {
'streamId': streamId,
'accepted': false,
'reason': 'an upload is already in progress on this pane',
});
}
expect(await future, isFalse);
expect(
sent.where((frame) => frame.type == 'terminal_chunked_upload_begin'),
hasLength(2),
);
expect(imagePastes(), isEmpty);
expect(session.uploadProgress, isNull);
},
);
test('cancels on the daemon a begin it never answered', () {
fakeAsync((async) {
live();
async.flushMicrotasks();
bool? result;
session
.pasteImage(Uint8List.fromList(const [1, 2, 3]))
.then((value) => result = value);
async.flushMicrotasks();
expect(
sent.where((frame) => frame.type == 'terminal_chunked_upload_begin'),
hasLength(1),
);
async.elapse(const Duration(seconds: 9));
expect(result, isNull);
async.elapse(const Duration(seconds: 2));
expect(result, isFalse);
expect(
sent
.where((frame) => frame.type == 'terminal_chunked_upload_cancel')
.single
.payload['streamId'],
streamId,
);
expect(session.uploadProgress, isNull);
expect(imagePastes(), isEmpty);
});
});
test('keeps at most the window of unconfirmed bytes on the way', () async {
await live();
final chunks = terminalUploadWindowBytes ~/ terminalUploadChunkBytes;
final big = Uint8List(terminalUploadChunkBytes * (chunks + 2) + 10);
final future = session.pasteImage(big);
await acceptBegin();
await pump();
expect(imagePastes(), hasLength(chunks));
Future<void> confirm(int bytes) async {
await session.handleFrame('terminal_chunked_upload_progress', {
'streamId': streamId,
'bytesWritten': bytes,
'totalBytes': big.length,
});
await pump();
}
await confirm(terminalUploadChunkBytes);
expect(imagePastes(), hasLength(chunks + 1));
// A repeated or older figure makes no room.
await confirm(terminalUploadChunkBytes);
expect(imagePastes(), hasLength(chunks + 1));
await confirm(terminalUploadChunkBytes * 3);
expect(imagePastes().map((frame) => frame.seq), [
for (var seq = 0; seq < chunks + 3; seq++) seq,
]);
expect(imagePastes().last.bytes, hasLength(10));
await confirm(big.length);
await session.handleFrame('terminal_paste_image_result', {
'streamId': streamId,
'outcome': 'clipboard',
});
expect(await future, isTrue);
expect(
sent.where((frame) => frame.type == 'terminal_chunked_upload_cancel'),
isEmpty,
);
});
for (final waitingForRoom in [true, false]) {
test('gives up an upload the daemon stops confirming, here and on the daemon '
'(waiting for room in the window: $waitingForRoom)', () async {
session.dispose();
session = TerminalSession(
machineId: 'machine-1',
agentId: 'agent-1',
agentName: 'backend-api',
engineId: 'codex',
uploadStallTimeout: const Duration(milliseconds: 50),
send: (type, payload) async {
sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
return true;
},
sendBinary: (frame) async {
binarySent.add(frame);
return true;
},
);
await live();
final chunks = waitingForRoom
? terminalUploadWindowBytes ~/ terminalUploadChunkBytes + 3
: 3;
final image = Uint8List(terminalUploadChunkBytes * chunks);
final future = session.pasteImage(image);
await acceptBegin();
await pump();
// Part of the image arrives; the rest was lost on the way.
await session.handleFrame('terminal_chunked_upload_progress', {
'streamId': streamId,
'bytesWritten': terminalUploadChunkBytes,
'totalBytes': image.length,
});
expect(await future, isFalse);
expect(imagePastes(), hasLength(waitingForRoom ? 5 : 3));
expect(session.uploadProgress, isNull);
expect(
session.lastStalledUpload!.bytesWritten,
terminalUploadChunkBytes,
);
expect(sent.last.type, 'terminal_chunked_upload_cancel');
expect(sent.last.payload['streamId'], streamId);
// The stream itself is fine: nothing reopens, and the next upload starts at once.
expect(session.status, TerminalSessionStatus.controlling);
expect(sent.where((frame) => frame.type == 'terminal_open'), isEmpty);
unawaited(session.pasteImage(Uint8List.fromList(const [1])));
await pump();
expect(sent.last.type, 'terminal_chunked_upload_begin');
expect(session.lastStalledUpload, isNull);
await session.cancelUpload();
});
}
for (final coded in [true, false]) {
test(
'a missing-stream upload rejection reopens once without replay (coded=$coded)',
() async {
await live();
final retained = session.terminal;
final uploading = session.pasteImage(Uint8List.fromList([1, 2, 3]));
await pump();
final rejection = <String, dynamic>{
'streamId': streamId,
'accepted': false,
if (coded) 'code': 'TERMINAL_STREAM_NOT_FOUND',
'reason': coded ? 'stream unavailable' : 'no live terminal stream for this pane (reopen it and try again)',
};
await session.handleFrame(
'terminal_chunked_upload_begin_result',
rejection,
);
expect(await uploading, isFalse);
expect(session.status, TerminalSessionStatus.opening);
expect(session.terminal, same(retained));
expect(session.uploadProgress, isNull);
expect(imagePastes(), isEmpty);
final opens = sent.where((frame) => frame.type == 'terminal_open');
expect(opens, hasLength(1));
expect(opens.single.payload['takeover'], isFalse);
await session.handleFrame(
'terminal_chunked_upload_begin_result',
rejection,
);
expect(
sent.where((frame) => frame.type == 'terminal_open'),
hasLength(1),
);
},
);
}
test(
'a malformed-chunk error clears the upload without freezing the session',
() async {
await live();
final png = Uint8List.fromList(const [1, 2, 3]);
final future = session.pasteImage(png);
await acceptBegin();
await pump();
await session.handleFrame('terminal_error', {
'streamId': streamId,
'code': 'TERMINAL_CHUNKED_UPLOAD_INVALID',
'message': 'malformed upload chunk',
});
expect(await future, isFalse);
expect(session.status, TerminalSessionStatus.controlling);
expect(session.uploadProgress, isNull);
},
);
test('a genuine mid-transfer failure freezes the session, like TERMINAL_PASTE_FAILED does', () async {
await live();
final png = Uint8List.fromList(const [1, 2, 3]);
final future = session.pasteImage(png);
await acceptBegin();
await pump();
await session.handleFrame('terminal_error', {
'streamId': streamId,
'code': 'TERMINAL_PASTE_IMAGE_FAILED',
'message': 'xclip exited with code 1',
});
expect(await future, isFalse);
expect(session.status, TerminalSessionStatus.error);
expect(session.errorCode, 'TERMINAL_PASTE_IMAGE_FAILED');
expect(session.uploadProgress, isNull);
});
test(
'cancelUpload before the daemon answers the begin settles it at once',
() {
fakeAsync((async) {
live();
async.flushMicrotasks();
bool? result;
session
.pasteImage(Uint8List.fromList(const [1, 2, 3]))
.then((value) => result = value);
async.flushMicrotasks();
session.cancelUpload();
async.flushMicrotasks();
expect(result, isFalse);
expect(
sent.where(
(frame) => frame.type == 'terminal_chunked_upload_cancel',
),
hasLength(1),
);
});
},
);
test('cancelUpload stops the transfer and tells the daemon', () async {
await live();
final png = Uint8List.fromList(const [1, 2, 3]);
final future = session.pasteImage(png);
await acceptBegin();
await pump();
expect(session.uploadProgress, isNotNull);
await session.cancelUpload();
expect(await future, isFalse);
expect(session.uploadProgress, isNull);
expect(sent.last, isA<Object>());
expect(sent.last.type, 'terminal_chunked_upload_cancel');
expect(sent.last.payload['streamId'], streamId);
});
test(
'rejects a second upload while one is already in flight on this session',
() async {
await live();
final png = Uint8List.fromList(const [1, 2, 3]);
final first = session.pasteImage(png);
await acceptBegin();
await pump();
expect(
await session.pasteFile('a.txt', Uint8List.fromList(const [1])),
isFalse,
);
await session.handleFrame('terminal_paste_image_result', {
'streamId': streamId,
'outcome': 'clipboard',
});
expect(await first, isTrue);
},
);
test('sends nothing while the stream is not accepting input', () async {
expect(session.acceptsInput, isFalse);
expect(
await session.pasteImage(Uint8List.fromList(const [1, 2, 3])),
isFalse,
);
expect(
await session.pasteFile('a.txt', Uint8List.fromList(const [1])),
isFalse,
);
expect(imagePastes(), isEmpty);
expect(filePastes(), isEmpty);
});
test(
'sends nothing for an empty image or an empty filename/content',
() async {
await live();
expect(await session.pasteImage(Uint8List(0)), isFalse);
expect(
await session.pasteFile('', Uint8List.fromList(const [1])),
isFalse,
);
expect(await session.pasteFile('a.txt', Uint8List(0)), isFalse);
expect(imagePastes(), isEmpty);
expect(filePastes(), isEmpty);
expect(sent, isEmpty);
},
);
});
test('xterm learns the desktop it runs on', () {
addTearDown(() => debugDefaultTargetPlatformOverride = null);
for (final (platform, expected) in [
(TargetPlatform.macOS, TerminalTargetPlatform.macos),
(TargetPlatform.linux, TerminalTargetPlatform.linux),
(TargetPlatform.windows, TerminalTargetPlatform.windows),
]) {
debugDefaultTargetPlatformOverride = platform;
final local = TerminalSession(
machineId: 'm',
agentId: 'a',
agentName: 'a',
engineId: 'codex',
send: (type, payload) async => true,
sendBinary: (frame) async => true,
);
expect(local.terminal.platform, expected, reason: '$platform');
local.dispose();
}
});
}
class _RecordingLog implements AppLog {
final lines = <String>[];
@override
void record(
AppLogLevel level,
String category,
String message, {
Object? error,
StackTrace? stackTrace,
}) => lines.add('$category $message');
}