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.

22.2 KB
Raw Blame
import 'package:flutter/foundation.dart';
import 'package:flutter/services.dart';
import 'package:flutter_local_notifications/flutter_local_notifications.dart';

import 'package:harness_mobile/core/last_opened_agent.dart';
import 'package:harness_mobile/logging/app_log.dart';

import 'agent_notice.dart';

/// One notice about one agent, as the OS draws it: the agent's name, the
/// machine it runs on, and the news — what the turn said, or what it is asking
/// — the three lines of the dial's drawer row. [quiet] posts it with no sound,
/// no vibration and no banner ([AgentNotice.quiet]).
typedef AgentNoticeMessage = ({
  AgentRef agent,
  NoticeKind kind,
  String title,
  String machine,
  String body,
  bool quiet,
});

/// Where a Swarm notice leads: the Swarm, and the conversation it is about;
/// for a message only in a thread, that thread's root ([threadId]), since the
/// chat alone does not show it.
typedef SwarmNoticeTarget = ({
  String swarmId,
  String conversationId,
  String? messageId,
  String? decisionId,
  String? threadId,
});

/// One notice about what a Swarm asks of the person. [key] names the
/// notification it shows in, so the same need posted twice replaces itself,
/// and so does the server's push for it (task #3248: a thread's replies share
/// one); [subtitle] says where it is. [quiet] replaces what that notification
/// showed with no sound, no vibration and no banner.
typedef SwarmNoticeMessage = ({
  String key,
  String title,
  String subtitle,
  String body,
  SwarmNoticeTarget target,
  bool quiet,
});

/// The notification centre's Swarm notices: decisions asked of the person,
/// Lead tags, work waiting on them.
///
/// Not on [SystemNotices], whose stand-ins would all have to answer it:
/// [LocalSystemNotices] and [SilentSystemNotices] carry both.
abstract interface class SwarmNotices {
  Future<void> showSwarm(SwarmNoticeMessage message);

  /// Takes the notice [key] names back down: its need was met somewhere else.
  Future<void> cancelSwarm(String key);

  /// Shows [count] on the app icon: what the Swarms ask of the person, the
  /// drawer's waiting count. Zero takes it off.
  Future<void> setSwarmBadge(int count);

  /// The Swarm notice tapped last — what the shell opens. Reset to null by
  /// whoever acts on it.
  ValueNotifier<SwarmNoticeTarget?> get openedSwarm;
}

/// The OS notification centre, as far as the phone uses it.
///
/// An interface so the notifier's tests never reach a platform plugin — see
/// [SilentSystemNotices].
abstract interface class SystemNotices {
  /// Asks the person, once, whether the phone may notify them. The OS
  /// remembers the answer; asking again is a no-op. True when allowed, false
  /// when refused, null when nothing could say.
  Future<bool?> requestPermission();

  Future<void> show(AgentNoticeMessage message);

  /// Takes [agent]'s notice back down — its question was answered somewhere
  /// else, so the lock screen must stop asking.
  Future<void> cancel(AgentRef agent);

  /// The agent whose notice was tapped last — what the shell opens. Reset to
  /// null by whoever acts on it.
  ValueNotifier<AgentRef?> get opened;

  /// The key of the device whose notice was tapped last — what the shell opens. Reset to null by
  /// whoever acts on it.
  ValueNotifier<String?> get openedDevice;

  /// News about the ACCOUNT rather than an agent: a device joined it. [key] names the notice, so the
  /// same news posted twice replaces itself. Tapping it opens that device's page ([key] is its key).
  Future<void> showAccountNotice({required String key, required String title, required String body});
}

/// Nothing leaves the process. What a test notifier is given.
class SilentSystemNotices implements SystemNotices, SwarmNotices {
  @override
  final opened = ValueNotifier<AgentRef?>(null);

  @override
  final openedDevice = ValueNotifier<String?>(null);

  @override
  final openedSwarm = ValueNotifier<SwarmNoticeTarget?>(null);

  @override
  Future<bool?> requestPermission() async => null;

  @override
  Future<void> show(AgentNoticeMessage message) async {}

  @override
  Future<void> cancel(AgentRef agent) async {}

  @override
  Future<void> showAccountNotice({required String key, required String title, required String body}) async {}

  @override
  Future<void> showSwarm(SwarmNoticeMessage message) async {}

  @override
  Future<void> cancelSwarm(String key) async {}

  @override
  Future<void> setSwarmBadge(int count) async {}
}

/// Whether the OS lets this app post notices right now — Settings ▸ Notifications reads it. Null
/// where nothing can say: a stand-in centre (tests, the sample), or a platform call that failed.
///
/// Not on [SystemNotices] itself: every stand-in would have to answer it, and only the real centre
/// knows.
Future<bool?> noticesEnabled(SystemNotices notices) =>
    notices is LocalSystemNotices
    ? notices.enabled()
    : Future<bool?>.value(null);

/// What the phone's notices are about, in the words Settings ▸ Notifications and Focus's tips use —
/// one source, so the two never promise different things.
///
/// "Needs you" since 2026-10-21: `commander_question` ([NoticeKind.question]) reaches a phone over the
/// relay (`cli/src/core/questions.ts` `sendRemote`). From 2026-10-14 until then the daemon sent it only
/// to the dial and its own computer, and this did not promise it.
const noticesWhen =
    'a harness finishes or needs you, or a new device joins your account';

/// What a device notice's payload starts with; the device's key follows. An agent notice's payload
/// is `machine\nagent`, so the two never read as each other.
const _devicePayload = 'device:';

/// What a Swarm notice's payload starts with: `swarm:<swarm>/<conversation>`, each part
/// URI-encoded, with no newline — so it never reads as an agent's or a device's.
const _swarmPayload = 'swarm:';

/// The Android channel, iOS thread and iOS category of Swarm notices.
const _swarmChannel = 'swarm-needs-you';

/// The Android channel of a quiet push (task #3248; backend `push/sender.ts` SWARM_QUIET_CHANNEL): on
/// Android the channel, not the push, decides whether it sounds, so this one never does.
const _swarmQuietChannel = 'swarm-quiet';

/// How Android names the Swarm channel, here and when a notice makes it.
const _swarmChannelName = 'Swarm needs you';
const _swarmChannelDescription =
    'A Swarm asks you to decide, tags you, or has work waiting on you.';

/// Android draws an FCM push under its tag with this id (the server tags it with the notice's key), so a
/// Swarm notice posted under the same tag and id replaces the push, and the other way round.
const _androidPushId = 0;

bool get _android => defaultTargetPlatform == TargetPlatform.android;

/// `harness/app_badge` — the app icon's count (Swift: `AppBadgeChannel` in `ios/Runner/AppDelegate.swift`).
const _appBadge = MethodChannel('harness/app_badge');

/// The real centre, through flutter_local_notifications.
///
/// Started lazily on first use, so a launch that never needs it — and every
/// test — pays nothing for it.
class LocalSystemNotices implements SystemNotices, SwarmNotices {
  LocalSystemNotices([FlutterLocalNotificationsPlugin? plugin])
    : _plugin = plugin ?? FlutterLocalNotificationsPlugin();

  final FlutterLocalNotificationsPlugin _plugin;
  Future<void>? _ready;
  Future<void>? _pushReady;

  @override
  final opened = ValueNotifier<AgentRef?>(null);

  @override
  final openedDevice = ValueNotifier<String?>(null);

  @override
  final openedSwarm = ValueNotifier<SwarmNoticeTarget?>(null);

  /// Told when the person has just allowed notices ([requestPermission]): the moment pushes can
  /// start reaching them (`notify/push_tokens.dart`).
  void Function()? onAllowed;

  /// Android: makes the channels pushes are drawn on, before one can arrive (task #3248). Without
  /// them a push that came before the app's first Swarm notice landed on FCM's default channel, and
  /// a quiet one would sound. Needs no start of the centre; nothing on iOS, whose pushes have no
  /// channel. Shared with notification initialization, so permission checks wait for both channels
  /// even when eager startup is still preparing them. A failed attempt is logged once per launch.
  Future<void> preparePush() => _pushReady ??= _makePushChannels()
      .timeout(const Duration(seconds: 10))
      .catchError((Object error) {
        appLog.warn('notify', 'push channels not made', error: error);
      });

  Future<void> _makePushChannels() async {
    if (!_android) return;
    final android = _plugin
        .resolvePlatformSpecificImplementation<
          AndroidFlutterLocalNotificationsPlugin
        >();
    await android?.createNotificationChannel(
      const AndroidNotificationChannel(
        _swarmChannel,
        _swarmChannelName,
        description: _swarmChannelDescription,
        importance: Importance.high,
      ),
    );
    await android?.createNotificationChannel(
      const AndroidNotificationChannel(
        _swarmQuietChannel,
        'Swarm, quiet updates',
        description:
            'A newer reply in a thread you have not read yet: it replaces the notice already there.',
        importance: Importance.low,
        playSound: false,
        enableVibration: false,
      ),
    );
  }

  /// One Android channel per kind, so a person can silence finished turns and
  /// still hear questions — the two are not equally urgent. Also the iOS
  /// thread each kind is grouped under.
  static const _channels = {
    NoticeKind.done: (
      id: 'agent-done',
      name: 'Agent finished',
      description: 'An agent finished its turn while Harness was away.',
    ),
    NoticeKind.question: (
      id: 'agent-question',
      name: 'Agent needs you',
      description: 'An agent stopped to ask you something.',
    ),
  };

  /// Started once and shared — but only a start that WORKED is kept. A failed
  /// one kept here would fail every notice after it, instantly, for the rest of
  /// the launch; forgetting it lets the next notice try again.
  Future<void> _init() =>
      _ready ??= _start().catchError((Object error, StackTrace stack) {
        _ready = null;
        Error.throwWithStackTrace(error, stack);
      });

  Future<void> _start() async {
    await _plugin.initialize(
      settings: const InitializationSettings(
        android: AndroidInitializationSettings('@mipmap/ic_launcher'),
        // Asked for explicitly in [requestPermission], never as a side effect
        // of the first notice.
        iOS: DarwinInitializationSettings(
          requestAlertPermission: false,
          requestBadgePermission: false,
          requestSoundPermission: false,
          // A Swarm notice on a phone that hides previews still says who asks
          // and where.
          notificationCategories: [
            DarwinNotificationCategory(
              _swarmChannel,
              options: {
                DarwinNotificationCategoryOption.hiddenPreviewShowTitle,
                DarwinNotificationCategoryOption.hiddenPreviewShowSubtitle,
              },
            ),
          ],
        ),
      ),
      onDidReceiveNotificationResponse: (response) => _open(response.payload),
    );
    await preparePush();
    // A notice tapped while the app was not running at all launches it; the
    // tap reaches no callback then, only this.
    final launch = await _plugin.getNotificationAppLaunchDetails();
    if (launch?.didNotificationLaunchApp ?? false) {
      _open(launch?.notificationResponse?.payload);
    }
  }

  void _open(String? payload) {
    if (decodeSwarmPayload(payload) case final target?) {
      openedSwarm.value = target;
      return;
    }
    // A device notice carries `device:<key>` — no newline, so it never reads as an agent's payload.
    if (payload != null && payload.startsWith(_devicePayload)) {
      openedDevice.value = payload.substring(_devicePayload.length);
      return;
    }
    final agent = decodeAgentPayload(payload);
    if (agent != null) opened.value = agent;
  }

  @override
  Future<bool?> requestPermission() async {
    try {
      await _init();
      final ios = await _plugin
          .resolvePlatformSpecificImplementation<
            IOSFlutterLocalNotificationsPlugin
          >()
          ?.requestPermissions(alert: true, sound: true, badge: true);
      final android = await _plugin
          .resolvePlatformSpecificImplementation<
            AndroidFlutterLocalNotificationsPlugin
          >()
          ?.requestNotificationsPermission();
      final allowed = ios ?? android;
      if (allowed == true) onAllowed?.call();
      return allowed;
    } catch (error) {
      appLog.warn('notify', 'permission request failed', error: error);
      return null;
    }
  }

  /// Whether notices are allowed now — see [noticesEnabled]. iOS cannot tell "never asked" from
  /// "refused" here: both read false, and asking ([requestPermission]) is what tells them apart.
  Future<bool?> enabled() async {
    try {
      await _init();
      final ios = _plugin
          .resolvePlatformSpecificImplementation<
            IOSFlutterLocalNotificationsPlugin
          >();
      if (ios != null) return (await ios.checkPermissions())?.isEnabled;
      final android = _plugin
          .resolvePlatformSpecificImplementation<
            AndroidFlutterLocalNotificationsPlugin
          >();
      if (android != null) return await android.areNotificationsEnabled();
    } catch (error) {
      appLog.warn('notify', 'permission check failed', error: error);
    }
    return null;
  }

  @override
  Future<void> show(AgentNoticeMessage message) async {
    final channel = _channels[message.kind]!;
    try {
      await _init();
      await _plugin.show(
        // One per AGENT: newer news replaces its own last notice rather than
        // stacking beside it — the desktop banner's rule, and the unread
        // mark's: a question after a finish is the one that stands.
        id: noticeIdFor(message.agent),
        title: message.title,
        body: message.body,
        payload: encodeAgentPayload(message.agent),
        notificationDetails: NotificationDetails(
          android: AndroidNotificationDetails(
            channel.id,
            channel.name,
            channelDescription: channel.description,
            importance: Importance.high,
            priority: Priority.high,
            subText: message.machine,
            // A quiet notice replaces or joins the list without a sound, a
            // vibration or a heads-up, whatever its channel says.
            silent: message.quiet,
          ),
          iOS: DarwinNotificationDetails(
            subtitle: message.machine,
            threadIdentifier: channel.id,
            // Unset is the plugin's default, sound and banner. Without a sound
            // here iOS plays none in the background either; passive neither
            // lights the screen nor shows a banner, only the list.
            presentSound: message.quiet ? false : null,
            presentBanner: message.quiet ? false : null,
            interruptionLevel: message.quiet ? InterruptionLevel.passive : null,
          ),
        ),
      );
    } catch (error) {
      appLog.warn('notify', 'notice failed', error: error);
    }
  }

  @override
  Future<void> showAccountNotice({required String key, required String title, required String body}) async {
    try {
      await _init();
      await _plugin.show(
        id: accountNoticeIdFor(key),
        title: title,
        body: body,
        notificationDetails: const NotificationDetails(
          android: AndroidNotificationDetails(
            'account-device',
            'New device on your account',
            channelDescription: 'A computer or app signed in to your account and can reach your machines.',
            importance: Importance.high,
            priority: Priority.high,
          ),
          iOS: DarwinNotificationDetails(threadIdentifier: 'account-device'),
        ),
        payload: '$_devicePayload$key',
      );
    } catch (error) {
      appLog.warn('notify', 'account notice failed', error: error);
    }
  }

  /// Where a Swarm notice is in the notification centre: the notification the server's push for the
  /// same thing uses (task #3248). Android: its key as the tag, with FCM's id. iOS: [swarmNoticeIdFor],
  /// which the push carries in decimal as its `apns-collapse-id`.
  ({int id, String? tag}) _swarmPlace(String key) => _android
      ? (id: _androidPushId, tag: key)
      : (id: swarmNoticeIdFor(key), tag: null);

  @override
  Future<void> showSwarm(SwarmNoticeMessage message) async {
    final place = _swarmPlace(message.key);
    final quiet = message.quiet;
    try {
      await _init();
      await _plugin.show(
        id: place.id,
        title: message.title,
        body: message.body,
        payload: encodeSwarmPayload(message.target),
        notificationDetails: NotificationDetails(
          android: AndroidNotificationDetails(
            _swarmChannel,
            _swarmChannelName,
            channelDescription: _swarmChannelDescription,
            importance: Importance.high,
            priority: Priority.high,
            subText: message.subtitle,
            // Hidden on a secure lock screen set to hide private content.
            visibility: NotificationVisibility.private,
            tag: place.tag,
            // A quiet one replaces what its notification showed, without a sound, a vibration or a
            // heads-up, as a quiet agent notice does.
            silent: quiet,
          ),
          iOS: DarwinNotificationDetails(
            subtitle: message.subtitle,
            threadIdentifier: _swarmChannel,
            categoryIdentifier: _swarmChannel,
            presentSound: quiet ? false : null,
            presentBanner: quiet ? false : null,
            interruptionLevel: quiet ? InterruptionLevel.passive : null,
          ),
        ),
      );
    } catch (error) {
      appLog.warn('notify', 'swarm notice failed', error: error);
    }
  }

  /// Also takes down the push shown in the same notification.
  @override
  Future<void> cancelSwarm(String key) async {
    final place = _swarmPlace(key);
    try {
      await _init();
      await _plugin.cancel(id: place.id, tag: place.tag);
    } catch (error) {
      appLog.warn('notify', 'swarm cancel failed', error: error);
    }
  }

  /// iOS only: Android has no count of its own on the icon — launchers draw a dot from the
  /// notices posted.
  @override
  Future<void> setSwarmBadge(int count) async {
    if (defaultTargetPlatform != TargetPlatform.iOS) return;
    try {
      await _appBadge.invokeMethod<void>('set', count);
    } catch (error) {
      appLog.warn('notify', 'swarm badge failed', error: error);
    }
  }

  @override
  Future<void> cancel(AgentRef agent) async {
    try {
      await _init();
      await _plugin.cancel(id: noticeIdFor(agent));
    } catch (error) {
      appLog.warn('notify', 'cancel failed', error: error);
    }
  }
}

/// A stable, positive id per agent, so a notice replaces the last one for the
/// same agent across runs too.
@visibleForTesting
int noticeIdFor(AgentRef agent) {
  // FNV-1a: `String.hashCode` is not guaranteed stable from one run to the next.
  var hash = 0x811c9dc5;
  for (final unit in encodeAgentPayload(agent).codeUnits) {
    hash = ((hash ^ unit) * 0x01000193) & 0x7fffffff;
  }
  return hash;
}

/// A stable, positive id per account notice — the same FNV-1a as [noticeIdFor], over its own key,
/// so it never lands on an agent's.
@visibleForTesting
int accountNoticeIdFor(String key) {
  var hash = 0x811c9dc5;
  for (final unit in 'account\n$key'.codeUnits) {
    hash = ((hash ^ unit) * 0x01000193) & 0x7fffffff;
  }
  return hash;
}

/// A stable, positive id per Swarm notice — the same FNV-1a, over its own key, so it never lands
/// on an agent's or an account's.
@visibleForTesting
int swarmNoticeIdFor(String key) {
  var hash = 0x811c9dc5;
  for (final unit in 'swarm\n$key'.codeUnits) {
    hash = ((hash ^ unit) * 0x01000193) & 0x7fffffff;
  }
  return hash;
}

@visibleForTesting
String encodeSwarmPayload(SwarmNoticeTarget target) =>
    '$_swarmPayload${Uri.encodeComponent(target.swarmId)}'
    '/${Uri.encodeComponent(target.conversationId)}'
    '${target.messageId != null
        ? '/message/${Uri.encodeComponent(target.messageId!)}'
              '${target.threadId != null ? '/thread/${Uri.encodeComponent(target.threadId!)}' : ''}'
        : target.decisionId != null
        ? '/decision/${Uri.encodeComponent(target.decisionId!)}'
        : ''}';

@visibleForTesting
SwarmNoticeTarget? decodeSwarmPayload(String? payload) {
  if (payload == null || !payload.startsWith(_swarmPayload)) return null;
  final parts = payload.substring(_swarmPayload.length).split('/');
  if ((parts.length != 2 && parts.length != 4 && parts.length != 6) ||
      parts.any((p) => p.isEmpty)) {
    return null;
  }
  if (parts.length >= 4 && !const ['message', 'decision'].contains(parts[2])) {
    return null;
  }
  // A message in a thread names its root after it (encodeSwarmPayload).
  if (parts.length == 6 && (parts[2] != 'message' || parts[4] != 'thread')) {
    return null;
  }
  try {
    return (
      swarmId: Uri.decodeComponent(parts[0]),
      conversationId: Uri.decodeComponent(parts[1]),
      messageId: parts.length >= 4 && parts[2] == 'message'
          ? Uri.decodeComponent(parts[3])
          : null,
      decisionId: parts.length == 4 && parts[2] == 'decision'
          ? Uri.decodeComponent(parts[3])
          : null,
      threadId: parts.length == 6 ? Uri.decodeComponent(parts[5]) : null,
    );
  } on ArgumentError {
    return null;
  }
}

@visibleForTesting
String encodeAgentPayload(AgentRef agent) =>
    '${agent.machineId}\n${agent.agentId}';

@visibleForTesting
AgentRef? decodeAgentPayload(String? payload) {
  final parts = payload?.split('\n');
  if (parts == null || parts.length != 2) return null;
  if (parts[0].isEmpty || parts[1].isEmpty) return null;
  return (machineId: parts[0], agentId: parts[1]);
}

/// A tapped push (`notify/push_channel.dart`) opens the chat its `link` names: the app's own
/// `swarm:` payload, which the server puts beside the notice's `key` (`backend/src/push/notices.ts`).
/// Anything else (no link, an agent's or a device's payload) only opened the app.
void openPushed(Map<String, String> data, SystemNotices notices) {
  if (notices case final SwarmNotices swarm) {
    if (decodeSwarmPayload(data['link']) case final target?) {
      swarm.openedSwarm.value = target;
    }
  }
}