Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

desktop: an on-screen banner for the same two moments, and clicking it opens that agent

bitcoinbuilderf31983172347
diff --git a/desktop/lib/core/startup.dart b/desktop/lib/core/startup.dart
index 1760edce8..f2a3163a8 100644
--- a/desktop/lib/core/startup.dart
+++ b/desktop/lib/core/startup.dart
@@ -22,6 +22,7 @@ Future<void> loadPersistedSettings({
AppearancePrefsStore? appearance,
HarnessStats? stats,
AlertSoundStore? alertSounds,
+ ScreenAlertStore? screenAlerts,
}) async {
// Independent stores may load together, but all must finish before runApp.
// Font and appearance share a serialized file store; each reads its related
@@ -41,5 +42,6 @@ Future<void> loadPersistedSettings({
// Before the first agent event, not after: the setting decides whether that event makes a
// noise, and a late read would let one through on the default while the person had it off.
(alertSounds ?? alertSoundStore).load(),
+ (screenAlerts ?? screenAlertStore).load(),
]);
}
diff --git a/desktop/lib/notify/agent_alerts.dart b/desktop/lib/notify/agent_alerts.dart
new file mode 100644
index 000000000..7b27bb4d4
--- /dev/null
+++ b/desktop/lib/notify/agent_alerts.dart
@@ -0,0 +1,144 @@
+library;
+
+import 'dart:async';
+
+import 'package:flutter/foundation.dart';
+
+import 'alert_sounds.dart';
+
+/// One thing an agent did that is worth saying on screen.
+@immutable
+class AgentAlert {
+ const AgentAlert({
+ required this.machineId,
+ required this.agentId,
+ required this.title,
+ required this.kind,
+ required this.at,
+ });
+
+ final String machineId;
+ final String agentId;
+
+ /// What the agent is called, as the window calls it.
+ final String title;
+ final AlertKind kind;
+ final DateTime at;
+
+ /// One banner per AGENT, so a busy one replaces its own last message rather
+ /// than stacking three of them. The kind is deliberately not part of this:
+ /// an agent that finished and then asked a question has one current state,
+ /// and the newer message is it.
+ String get key => '$machineId/$agentId';
+
+ /// What the banner says under the agent's name.
+ String get sentence => switch (kind) {
+ AlertKind.done => 'Finished',
+ AlertKind.needsYou => 'Waiting on you',
+ };
+}
+
+/// The banners currently on screen.
+///
+/// Its own notifier rather than app state: a banner appearing must not rebuild
+/// the workspace, and an agent event already rebuilds enough.
+class AgentAlerts extends ChangeNotifier {
+ AgentAlerts({
+ ScreenAlertStore? store,
+ this.now = _systemNow,
+ this.life = const Duration(seconds: 7),
+ this.visible = 3,
+ }) : store = store ?? screenAlertStore;
+
+ static DateTime _systemNow() => DateTime.now();
+
+ final ScreenAlertStore store;
+ final DateTime Function() now;
+
+ /// How long a banner stays before it withdraws on its own. Long enough to
+ /// read a name and reach for it, short enough that a swarm does not leave a
+ /// wall of them standing.
+ final Duration life;
+
+ /// How many are shown at once. Past this the oldest goes: a stack taller than
+ /// this stops being a glance and starts being a list, and there is already a
+ /// list — the workspace.
+ final int visible;
+
+ final _alerts = <AgentAlert>[];
+ Timer? _sweep;
+
+ /// Newest first, which is the order they are read in.
+ List<AgentAlert> get alerts => List.unmodifiable(_alerts.reversed);
+
+ /// Say something happened. Silent when the feature is off.
+ void post(AgentAlert alert) {
+ if (!store.value) return;
+ // Sweep before adding. The timer is what takes a banner down while nothing else is happening,
+ // but anything that touches the stack is also a chance to notice what has outlived its life —
+ // and a window that was asleep, or a clock that is not the system's, may have left the timer
+ // behind entirely.
+ _dropExpired();
+ _alerts.removeWhere((a) => a.key == alert.key);
+ _alerts.add(alert);
+ while (_alerts.length > visible) {
+ _alerts.removeAt(0);
+ }
+ _schedule();
+ notifyListeners();
+ }
+
+ /// Take one down — the person dealt with it, or dismissed it.
+ void dismiss(AgentAlert alert) {
+ final before = _alerts.length;
+ _dropExpired();
+ _alerts.removeWhere((a) => a.key == alert.key);
+ if (_alerts.length == before) return;
+ _schedule();
+ notifyListeners();
+ }
+
+ void clear() {
+ if (_alerts.isEmpty) return;
+ _alerts.clear();
+ _sweep?.cancel();
+ _sweep = null;
+ notifyListeners();
+ }
+
+ /// Drop whatever has outlived [life], and arrange to be called again while
+ /// anything is still standing.
+ ///
+ /// One timer for the whole stack rather than one per banner: the banners come
+ /// in bursts, and a timer each would be a timer per agent in a swarm.
+ void _schedule() {
+ _sweep?.cancel();
+ _sweep = null;
+ if (_alerts.isEmpty) return;
+ final at = now();
+ final oldest = _alerts.first.at;
+ final left = life - at.difference(oldest);
+ _sweep = Timer(left.isNegative ? Duration.zero : left, _expire);
+ }
+
+ /// Drop what has outlived [life]. Each banner is judged on ITS OWN age: a stack that expired
+ /// together would take a notice raised a second ago down with one from a minute ago.
+ bool _dropExpired() {
+ final at = now();
+ final before = _alerts.length;
+ _alerts.removeWhere((a) => at.difference(a.at) >= life);
+ return _alerts.length != before;
+ }
+
+ void _expire() {
+ final changed = _dropExpired();
+ _schedule();
+ if (changed) notifyListeners();
+ }
+
+ @override
+ void dispose() {
+ _sweep?.cancel();
+ super.dispose();
+ }
+}
diff --git a/desktop/lib/notify/alert_sounds.dart b/desktop/lib/notify/alert_sounds.dart
index bc8abbe18..5326bd199 100644
--- a/desktop/lib/notify/alert_sounds.dart
+++ b/desktop/lib/notify/alert_sounds.dart
@@ -67,8 +67,47 @@ class AlertSoundStore extends ValueNotifier<bool> {
}
}
-/// The one store the app reads, loaded at start-up beside the other preferences.
+/// Whether a banner appears in the window when an agent finishes or gets stuck.
+///
+/// ON by default, unlike the sound. A banner is inside the app's own window and
+/// says nothing until an agent does something the person asked for — it is the
+/// half of this feature that answers "which one was that", and a default of off
+/// would leave the sound with nothing to point at.
+class ScreenAlertStore extends ValueNotifier<bool> {
+ ScreenAlertStore({LocalKeyValueStore? storage})
+ : _storage = storage ?? HarnessFileStore.shared,
+ super(true);
+
+ static const _key = 'app_screen_alerts';
+
+ final LocalKeyValueStore _storage;
+ Future<void>? _save;
+
+ /// Only the exact string `off` switches it off — a truncated file lands on
+ /// the default, which is the mirror of the rule [AlertSoundStore] follows for
+ /// its own opposite default.
+ Future<void> load() async {
+ try {
+ value = (await _storage.read(_key)) != 'off';
+ } catch (_) {
+ value = true;
+ }
+ }
+
+ Future<void> set(bool on) {
+ if (value == on) return _save ?? Future.value();
+ value = on;
+ final pending = (_save ?? Future.value()).then(
+ (_) => _storage.write(_key, on ? 'on' : 'off'),
+ );
+ _save = pending;
+ return pending;
+ }
+}
+
+/// The stores the app reads, loaded at start-up beside the other preferences.
final alertSoundStore = AlertSoundStore();
+final screenAlertStore = ScreenAlertStore();
/// Plays the alerts.
///
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index 11a5c59d9..c1a88c9f4 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -77,6 +77,7 @@ import '../widgets/workspace_quick_start.dart';
import '../widgets/workspace_start_guide.dart';
import '../widgets/workspace_welcome.dart';
import '../shortcuts/keyboard_practice.dart';
+import '../widgets/agent_alert_banners.dart';
class SwarmScreen extends StatefulWidget {
const SwarmScreen({
@@ -3203,6 +3204,10 @@ class _SwarmScreenState extends State<SwarmScreen>
),
if (_hasCommandBar && _commandBarOpen)
_commandPalette(),
+ // Last in the stack, so a banner is never painted
+ // under a pane, a tab or the palette. It takes
+ // pointers only on the banners themselves.
+ AgentAlertBanners(notifier: app),
],
),
),
diff --git a/desktop/lib/settings/sections/alerts_card.dart b/desktop/lib/settings/sections/alerts_card.dart
index c07c7fb2c..eaf62ad83 100644
--- a/desktop/lib/settings/sections/alerts_card.dart
+++ b/desktop/lib/settings/sections/alerts_card.dart
@@ -8,39 +8,62 @@ import '../../notify/alert_sounds.dart';
import '../../shared/theme/app_theme.dart' as grid;
import '../../shared/widgets/setting_row.dart';
-/// Customize Harness ▸ Appearance: whether this Mac makes a noise for you.
+/// Settings ▸ Notifications: how an agent gets your attention.
///
-/// One switch, because there is one decision. Splitting "finished" and "needs
-/// you" into two was considered and dropped: somebody who wants to hear about
-/// an agent that got stuck wants to hear about one that finished, and a second
-/// switch buys a combination nobody asked for at the cost of a screen that
-/// reads as configuration rather than as a preference.
+/// Two switches, because there are two CHANNELS and people differ about them —
+/// a banner is welcome in a quiet office where a sound is not. "Finished" and
+/// "needs you" are not split the same way: those are two triggers of one thing,
+/// and somebody who wants to know about a stuck agent wants to know about a
+/// finished one.
class AlertsCard extends StatelessWidget {
- const AlertsCard({super.key, this.store});
+ const AlertsCard({super.key, this.store, this.screenStore});
- /// Injected by tests; the app reads the one the window loaded at start-up.
+ /// Injected by tests; the app reads the ones the window loaded at start-up.
final AlertSoundStore? store;
+ final ScreenAlertStore? screenStore;
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
- final store = this.store ?? alertSoundStore;
- return ValueListenableBuilder<bool>(
- valueListenable: store,
- builder: (context, on, _) => SettingRow(
- title: 'Alert sounds',
- detail:
- 'Play a sound when an agent finishes, or stops to ask you '
- 'something.',
- control: Align(
- alignment: Alignment.centerLeft,
- child: Switch(
- key: const Key('settings-alert-sounds'),
- value: on,
- onChanged: (next) => unawaited(store.set(next)),
+ final sound = store ?? alertSoundStore;
+ final screen = screenStore ?? screenAlertStore;
+ return Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ ValueListenableBuilder<bool>(
+ valueListenable: screen,
+ builder: (context, on, _) => SettingRow(
+ title: 'On-screen alerts',
+ detail:
+ 'Show a banner when an agent finishes, or stops to ask you '
+ 'something. Click it to go to that agent.',
+ control: Align(
+ alignment: Alignment.centerLeft,
+ child: Switch(
+ key: const Key('settings-screen-alerts'),
+ value: on,
+ onChanged: (next) => unawaited(screen.set(next)),
+ ),
+ ),
),
),
- ),
+ const SizedBox(height: 10),
+ ValueListenableBuilder<bool>(
+ valueListenable: sound,
+ builder: (context, on, _) => SettingRow(
+ title: 'Alert sounds',
+ detail: 'Play a sound at the same two moments.',
+ control: Align(
+ alignment: Alignment.centerLeft,
+ child: Switch(
+ key: const Key('settings-alert-sounds'),
+ value: on,
+ onChanged: (next) => unawaited(sound.set(next)),
+ ),
+ ),
+ ),
+ ),
+ ],
);
}
}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 50aa16d48..d3c35d934 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -67,6 +67,7 @@ import 'session_preview.dart';
import '../usage/remote_usage.dart';
import '../usage/usage_accounts.dart';
import '../orchestrator/orchestrator_controller.dart';
+import '../notify/agent_alerts.dart';
import '../notify/alert_sounds.dart';
enum AppStatus {
@@ -428,6 +429,10 @@ class AppNotifier extends ChangeNotifier {
/// The noise this window makes when an agent finishes or gets stuck.
final AlertSounds alerts;
+ /// And what it puts on screen for the same two moments. Its own notifier, so
+ /// a banner appearing does not rebuild the workspace.
+ final AgentAlerts agentAlerts;
+
AppConfig config;
late ApiClient api;
@@ -1515,7 +1520,9 @@ class AppNotifier extends ChangeNotifier {
PaneLayoutStore? paneLayoutStore,
this.turnActivityTimeout = const Duration(seconds: 12),
AlertSounds? alerts,
+ AgentAlerts? agentAlerts,
}) : alerts = alerts ?? AlertSounds(store: alertSoundStore),
+ agentAlerts = agentAlerts ?? AgentAlerts(),
_paneLayout = paneLayoutStore,
// Remembers "a dial has been seen here" on the same terms the pane
// layout is remembered: with a layout store there is a state file, and
@@ -5801,6 +5808,46 @@ class AppNotifier extends ChangeNotifier {
notifyListeners();
}
+ /// Put one agent's news on screen, named the way the window names it.
+ void _raiseAlert(MachineState machine, String agentId, AlertKind kind) {
+ final agent = machine.agents.where((a) => a.id == agentId).firstOrNull;
+ agentAlerts.post(
+ AgentAlert(
+ machineId: machine.machine.machineId,
+ agentId: agentId,
+ // The agent's own name, and its id only when it has none — a banner
+ // naming a uuid tells nobody which pane to look at.
+ title: (agent?.name.trim().isNotEmpty ?? false)
+ ? agent!.name.trim()
+ : agentId,
+ kind: kind,
+ at: DateTime.now(),
+ ),
+ );
+ }
+
+ /// What clicking a banner does: show that agent, wherever it is.
+ ///
+ /// Reveal first — an agent already on screen just needs focus, and opening a
+ /// second view of it would take the terminal away from the one that has it.
+ /// Only an agent with no view at all is placed, on the current Swarm, in the
+ /// same order [placeFork] uses for the same reason.
+ Future<void> revealAgentFromAlert(String machineId, String agentId) async {
+ agentAlerts.dismiss(
+ AgentAlert(
+ machineId: machineId,
+ agentId: agentId,
+ title: '',
+ kind: AlertKind.done,
+ at: DateTime.now(),
+ ),
+ );
+ if (revealAgentView(machineId, agentId)) return;
+ if (activeSwarm.panes.length >= maxPanes) newSwarm();
+ await addAgentToSwarm(machineId, agentId, swarmId: activeSwarmId);
+ revealAgentView(machineId, agentId);
+ }
+
String? _eventAgentId(
MachineState machine,
Map<String, dynamic> event,
@@ -9888,7 +9935,10 @@ class AppNotifier extends ChangeNotifier {
// Only a NEW question earns a sound. The daemon re-announces every open one after a
// reconnect and when attaching to a turn that was already mid-dialog, and a window
// that beeped at those would sound an alarm every time the network hiccuped.
- if (!repeat) alerts.play(AlertKind.needsYou);
+ if (!repeat) {
+ alerts.play(AlertKind.needsYou);
+ _raiseAlert(machine, agentId, AlertKind.needsYou);
+ }
}
}
break;
@@ -9941,9 +9991,10 @@ class AppNotifier extends ChangeNotifier {
case 'turn_ended':
final agentId = _eventAgentId(machine, event, payload);
if (agentId != null) {
- // The work someone was waiting on is on screen. Played whether or not the pane is in
+ // The work someone was waiting on is on screen. Raised whether or not the pane is in
// front: the whole point is the agent that finished while you were looking elsewhere.
alerts.play(AlertKind.done);
+ _raiseAlert(machine, agentId, AlertKind.done);
_cancelTurnActivity(machine.machine.machineId, agentId);
} else {
final sessionId = _eventSessionId(event, payload);
@@ -10014,6 +10065,8 @@ class AppNotifier extends ChangeNotifier {
terminalThemeStore.removeListener(_announceTerminalThemeEverywhere);
_localGitProjects.dispose();
sessionPreviews.dispose();
+ // Its sweep timer would otherwise outlive the window it was drawing into.
+ agentAlerts.dispose();
_disposed = true;
_sharingDiscoveryTimer?.cancel();
_stopMachineRecovery();
diff --git a/desktop/lib/widgets/agent_alert_banners.dart b/desktop/lib/widgets/agent_alert_banners.dart
new file mode 100644
index 000000000..51e1769bd
--- /dev/null
+++ b/desktop/lib/widgets/agent_alert_banners.dart
@@ -0,0 +1,148 @@
+library;
+
+import 'package:flutter/material.dart';
+
+import '../notify/agent_alerts.dart';
+import '../notify/alert_sounds.dart';
+import '../shared/theme/app_theme.dart' as grid;
+import '../shared/theme/app_type.dart';
+import '../state/app_state.dart';
+import '../theme/app_theme.dart';
+import 'engine_identity.dart';
+
+/// The banners an agent's news appears in, stacked in the window's top-right.
+///
+/// Top-right and not centred: the middle of the window is where the work is,
+/// and a notice that covers it is worse than no notice. Right is also where the
+/// eye already goes for a pane's own controls.
+///
+/// Non-blocking by construction — the stack is only ever as wide and as tall as
+/// the banners in it, so there is no invisible area over the pane behind it.
+///
+/// ⚠️ NOT an `IgnorePointer` around the column with the banners opting back in.
+/// That does not work and it looks like it should: `ignoring: false` on a child
+/// cannot undo an ancestor's `ignoring: true`, because the ancestor refuses the
+/// hit test for the whole subtree before the child is ever asked. Written that
+/// way first, the banners were dead to the mouse.
+class AgentAlertBanners extends StatelessWidget {
+ const AgentAlertBanners({super.key, required this.notifier});
+
+ final AppNotifier notifier;
+
+ @override
+ Widget build(BuildContext context) {
+ grid.AppTheme.watch(context);
+ return Positioned(
+ top: 12,
+ right: 12,
+ child: ListenableBuilder(
+ listenable: notifier.agentAlerts,
+ builder: (context, _) {
+ final alerts = notifier.agentAlerts.alerts;
+ if (alerts.isEmpty) return const SizedBox.shrink();
+ return Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.end,
+ children: [
+ for (final alert in alerts)
+ Padding(
+ padding: const EdgeInsets.only(bottom: 8),
+ child: _Banner(alert: alert, notifier: notifier),
+ ),
+ ],
+ );
+ },
+ ),
+ );
+ }
+}
+
+class _Banner extends StatelessWidget {
+ const _Banner({required this.alert, required this.notifier});
+
+ final AgentAlert alert;
+ final AppNotifier notifier;
+
+ @override
+ Widget build(BuildContext context) {
+ final machine = notifier.machineStates[alert.machineId];
+ final agent = machine?.agents
+ .where((a) => a.id == alert.agentId)
+ .firstOrNull;
+ final waiting = alert.kind == AlertKind.needsYou;
+ return MouseRegion(
+ cursor: SystemMouseCursors.click,
+ child: GestureDetector(
+ onTap: () =>
+ notifier.revealAgentFromAlert(alert.machineId, alert.agentId),
+ child: Container(
+ key: const Key('agent-alert-banner'),
+ width: 288,
+ padding: const EdgeInsets.fromLTRB(12, 10, 8, 10),
+ decoration: BoxDecoration(
+ color: AppColors.surface,
+ borderRadius: BorderRadius.circular(11),
+ border: Border.all(
+ // The one that is BLOCKED gets the accent edge. Both are news;
+ // only one of them is work that has stopped.
+ color: waiting
+ ? AppColors.accent.withValues(alpha: 0.55)
+ : AppColors.border,
+ ),
+ boxShadow: [
+ BoxShadow(
+ color: const Color(0x40000000),
+ blurRadius: 14,
+ offset: const Offset(0, 4),
+ ),
+ ],
+ ),
+ child: Row(
+ children: [
+ EngineMark(engine: agent?.engine, size: 15),
+ const SizedBox(width: 9),
+ Expanded(
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Text(
+ alert.title,
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: AppType.body(color: AppColors.text)
+ .copyWith(fontWeight: FontWeight.w600, fontSize: 13),
+ ),
+ const SizedBox(height: 1),
+ Text(
+ alert.sentence,
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: AppType.body(
+ color: waiting
+ ? AppColors.accent
+ : AppColors.mutedStrong,
+ ).copyWith(fontSize: 12),
+ ),
+ ],
+ ),
+ ),
+ // Dismiss without going anywhere. A banner that could only be
+ // answered by following it would make every stray notice a
+ // navigation.
+ IconButton(
+ key: const Key('agent-alert-dismiss'),
+ icon: const Icon(Icons.close, size: 14),
+ color: AppColors.mutedStrong,
+ splashRadius: 14,
+ visualDensity: VisualDensity.compact,
+ tooltip: 'Dismiss',
+ onPressed: () => notifier.agentAlerts.dismiss(alert),
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+ }
+}
diff --git a/desktop/test/agent_alert_banner_widget_test.dart b/desktop/test/agent_alert_banner_widget_test.dart
new file mode 100644
index 000000000..28d436569
--- /dev/null
+++ b/desktop/test/agent_alert_banner_widget_test.dart
@@ -0,0 +1,120 @@
+// The banner as a CONTROL: that a click reaches it at all, and what the click does.
+//
+// This file exists because the first version was unclickable and looked correct — an
+// `IgnorePointer` around the stack with `ignoring: false` on each banner, which reads like
+// "the column is transparent, the banners are not" and is not how that widget works.
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/auth/auth_session.dart';
+import 'package:harness/core/config.dart';
+import 'package:harness/core/local_key_value_store.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/notify/agent_alerts.dart';
+import 'package:harness/notify/alert_sounds.dart';
+import 'package:harness/state/app_state.dart';
+import 'package:harness/widgets/agent_alert_banners.dart';
+
+class _Memory implements LocalKeyValueStore {
+ final values = <String, String?>{};
+ @override
+ Future<String?> read(String key) async => values[key];
+ @override
+ Future<void> write(String key, String value) async => values[key] = value;
+ @override
+ Future<void> delete(String key) async => values.remove(key);
+}
+
+const _machine = Machine(
+ machineId: 'm1',
+ authMode: MachineAuthMode.remote,
+ name: 'MacBook-Pro.local',
+);
+
+void main() {
+ late AppNotifier app;
+
+ setUp(() {
+ final screen = ScreenAlertStore(storage: _Memory())..value = true;
+ app = AppNotifier(
+ config: AppConfig.dev,
+ authSession: AuthSession(),
+ agentAlerts: AgentAlerts(store: screen),
+ );
+ app.machines = [_machine];
+ app.machineStates['m1'] = MachineState(_machine)
+ ..agents = [
+ const Agent(id: 'a1', name: 'Respond to greeting', engine: 'codex'),
+ ];
+ });
+
+ tearDown(() => app.dispose());
+
+ Future<void> show(WidgetTester tester) async {
+ tester.view.physicalSize = const Size(1200, 900);
+ tester.view.devicePixelRatio = 1;
+ addTearDown(tester.view.reset);
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: Stack(children: [AgentAlertBanners(notifier: app)]),
+ ),
+ ),
+ );
+ app.agentAlerts.post(
+ AgentAlert(
+ machineId: 'm1',
+ agentId: 'a1',
+ title: 'Respond to greeting',
+ kind: AlertKind.done,
+ at: DateTime.now(),
+ ),
+ );
+ await tester.pump();
+ }
+
+ testWidgets('a banner appears, named after the agent', (tester) async {
+ await show(tester);
+ expect(find.byKey(const Key('agent-alert-banner')), findsOneWidget);
+ expect(find.text('Respond to greeting'), findsOneWidget);
+ expect(find.text('Finished'), findsOneWidget);
+ // A standing banner holds its sweep timer, and the binding checks for pending timers at the
+ // END OF THE BODY — before any tearDown, registered or top-level. The other tests here leave
+ // nothing standing because clicking and dismissing both empty the stack.
+ app.agentAlerts.clear();
+ });
+
+ testWidgets('clicking it opens that agent — which also proves it is reachable', (tester) async {
+ // `tester.tap` dispatches a real pointer through hit testing, so an ancestor refusing the hit
+ // test fails this rather than needing an assertion of its own. That is what the first version
+ // did, and it left a banner perfectly visible and perfectly dead.
+ await show(tester);
+ expect(app.panes, isEmpty);
+
+ await tester.tap(find.byKey(const Key('agent-alert-banner')));
+ await tester.pumpAndSettle();
+
+ // The agent now has a pane, and it is the focused one.
+ expect(app.panes, isNotEmpty);
+ final pane = app.panes.firstWhere(
+ (p) => p.machineId == 'm1' && p.agentId == 'a1',
+ );
+ expect(app.focusedPane?.id, pane.id);
+ });
+
+ testWidgets('clicking it takes the banner down', (tester) async {
+ await show(tester);
+ await tester.tap(find.byKey(const Key('agent-alert-banner')));
+ await tester.pumpAndSettle();
+ expect(find.byKey(const Key('agent-alert-banner')), findsNothing);
+ });
+
+ testWidgets('dismissing takes it down WITHOUT opening anything', (tester) async {
+ // A notice you can only answer by following it would make every stray banner a navigation.
+ await show(tester);
+ await tester.tap(find.byKey(const Key('agent-alert-dismiss')));
+ await tester.pumpAndSettle();
+ expect(find.byKey(const Key('agent-alert-banner')), findsNothing);
+ expect(app.panes, isEmpty);
+ });
+}
+
diff --git a/desktop/test/agent_alerts_test.dart b/desktop/test/agent_alerts_test.dart
new file mode 100644
index 000000000..6de879c1b
--- /dev/null
+++ b/desktop/test/agent_alerts_test.dart
@@ -0,0 +1,133 @@
+// The banners an agent's news appears in: when one is raised, which one it replaces, when it goes
+// away on its own, and what clicking it does.
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/local_key_value_store.dart';
+import 'package:harness/notify/agent_alerts.dart';
+import 'package:harness/notify/alert_sounds.dart';
+
+class _Memory implements LocalKeyValueStore {
+ final values = <String, String?>{};
+ @override
+ Future<String?> read(String key) async => values[key];
+ @override
+ Future<void> write(String key, String value) async => values[key] = value;
+ @override
+ Future<void> delete(String key) async => values.remove(key);
+}
+
+void main() {
+ late DateTime clock;
+
+ ScreenAlertStore store({bool on = true}) {
+ final made = ScreenAlertStore(storage: _Memory());
+ made.value = on;
+ return made;
+ }
+
+ AgentAlerts alerts({ScreenAlertStore? on, int visible = 3}) {
+ clock = DateTime(2026, 9, 23, 12);
+ return AgentAlerts(
+ store: on ?? store(),
+ now: () => clock,
+ life: const Duration(seconds: 7),
+ visible: visible,
+ );
+ }
+
+ AgentAlert alert(String agentId, {AlertKind kind = AlertKind.done, String? title}) =>
+ AgentAlert(
+ machineId: 'm1',
+ agentId: agentId,
+ title: title ?? agentId,
+ kind: kind,
+ at: clock,
+ );
+
+ test('the banner is ON by default — it is the half that says WHICH agent', () {
+ expect(ScreenAlertStore(storage: _Memory()).value, isTrue);
+ });
+
+ test('newest first, because that is the order they are read in', () {
+ final queue = alerts();
+ queue.post(alert('a'));
+ clock = clock.add(const Duration(seconds: 1));
+ queue.post(alert('b'));
+ expect(queue.alerts.map((a) => a.agentId), ['b', 'a']);
+ });
+
+ test('one banner per agent: a busy one replaces its own last message', () {
+ // Otherwise a single chatty agent fills the stack and every other agent's news falls off it.
+ final queue = alerts();
+ queue.post(alert('a', kind: AlertKind.done));
+ clock = clock.add(const Duration(seconds: 1));
+ queue.post(alert('a', kind: AlertKind.needsYou));
+ expect(queue.alerts, hasLength(1));
+ expect(queue.alerts.single.kind, AlertKind.needsYou);
+ });
+
+ test('past the cap the OLDEST goes, not the newest', () {
+ final queue = alerts(visible: 2);
+ for (final id in ['a', 'b', 'c']) {
+ queue.post(alert(id));
+ clock = clock.add(const Duration(seconds: 1));
+ }
+ expect(queue.alerts.map((a) => a.agentId), ['c', 'b']);
+ });
+
+ test('a banner withdraws on its own once its life is up', () {
+ final queue = alerts();
+ queue.post(alert('a'));
+ expect(queue.alerts, hasLength(1));
+ clock = clock.add(const Duration(seconds: 8));
+ queue.post(alert('b'));
+ // Posting sweeps: the one that has outlived its welcome goes with it.
+ expect(queue.alerts.map((a) => a.agentId), ['b']);
+ });
+
+ test('the newer banner does not inherit the older one’s clock', () {
+ // A stack that expired as one would take a fresh notice down with a stale one.
+ final queue = alerts();
+ queue.post(alert('a'));
+ clock = clock.add(const Duration(seconds: 6));
+ queue.post(alert('b'));
+ clock = clock.add(const Duration(seconds: 2));
+ queue.post(alert('c'));
+ expect(queue.alerts.map((a) => a.agentId), ['c', 'b']);
+ });
+
+ test('dismissing takes one down and leaves the rest', () {
+ final queue = alerts();
+ queue.post(alert('a'));
+ queue.post(alert('b'));
+ queue.dismiss(alert('a'));
+ expect(queue.alerts.map((a) => a.agentId), ['b']);
+ });
+
+ test('nothing is raised while the switch is off', () {
+ final queue = alerts(on: store(on: false));
+ queue.post(alert('a'));
+ expect(queue.alerts, isEmpty);
+ });
+
+ test('each kind says what it is, and they do not say the same thing', () {
+ expect(alerts().runtimeType, AgentAlerts);
+ final done = AgentAlert(
+ machineId: 'm', agentId: 'a', title: 'A', kind: AlertKind.done, at: clock,
+ );
+ final waiting = AgentAlert(
+ machineId: 'm', agentId: 'a', title: 'A', kind: AlertKind.needsYou, at: clock,
+ );
+ expect(done.sentence, isNotEmpty);
+ expect(waiting.sentence, isNotEmpty);
+ expect(done.sentence, isNot(waiting.sentence));
+ });
+
+ test('two agents with the same name are still two banners', () {
+ // The key is the machine and the agent, never the title — a swarm of "Codex" panes is the
+ // ordinary case, and collapsing them would hide every one but the last.
+ final queue = alerts();
+ queue.post(alert('a', title: 'Codex'));
+ queue.post(alert('b', title: 'Codex'));
+ expect(queue.alerts, hasLength(2));
+ });
+}
diff --git a/desktop/test/pending_question_test.dart b/desktop/test/pending_question_test.dart
index c0d22cf63..3dd376819 100644
--- a/desktop/test/pending_question_test.dart
+++ b/desktop/test/pending_question_test.dart
@@ -308,6 +308,35 @@ void main() {
expect(played, [AlertKind.done.sound]);
});
+ test('a finished turn also raises a banner, named after the agent', () async {
+ final app = wired();
+ addTearDown(app.dispose);
+ app.machineStates['m1']!.agents = [
+ const Agent(id: 'a1', name: 'Respond to greeting', engine: 'codex'),
+ ];
+ await app.handleMachineEventForTest('m1', {
+ 'type': 'turn_ended',
+ 'agentId': 'a1',
+ 'payload': {'agentId': 'a1'},
+ });
+ final raised = app.agentAlerts.alerts;
+ expect(raised, hasLength(1));
+ // The agent's own NAME. A banner naming a uuid tells nobody which pane to look at.
+ expect(raised.single.title, 'Respond to greeting');
+ expect(raised.single.kind, AlertKind.done);
+ expect(raised.single.agentId, 'a1');
+ });
+
+ test('a question raises a banner too, and a re-announced one does not', () async {
+ final app = wired();
+ addTearDown(app.dispose);
+ await app.handleMachineEventForTest('m1', asked());
+ clock = clock.add(const Duration(minutes: 5));
+ await app.handleMachineEventForTest('m1', asked());
+ expect(app.agentAlerts.alerts, hasLength(1));
+ expect(app.agentAlerts.alerts.single.kind, AlertKind.needsYou);
+ });
+
test('nothing is heard while the switch is off', () async {
final off = store(on: false);
final app = AppNotifier(