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.

19.2 KB
Raw Blame
import 'dart:async';
import 'dart:isolate';

import 'package:flutter/foundation.dart';

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

import 'model.dart';
import 'parts.dart';
import 'swarm_buddy.dart';
import 'swarm_chat_notify.dart';
import 'swarm_kept.dart';
import 'swarm_read_marks.dart';
import 'swarm_request.dart';
import 'waiting_work.dart';

/// A Swarm of this many groups and agents or more is made into what the
/// screens draw off the UI isolate: on the owner's iPhone 14 a 1.3 MB Swarm took 73 to 93 ms
/// there, several frames (Mira's Profile numbers, 2026-10-27). A small one
/// takes less than sending it away does.
const swarmParseOffThreadParts = 100;

/// What the screens draw of a Swarm, worked out from its parts.
typedef _View = ({
  SuperTabSnapshot snapshot,
  Map<String, String> partners,
  SwarmBuddies buddies,
});

/// [parts] as [accountId] reads them: whose Buddies are whose depends on who
/// reads. Each conversation carries when it last changed, which the state
/// leaves out ([SuperTabConversation.changedAt]), and each project's board
/// pulse, from a server that sends it in `derived` ([SuperTabSnapshot.pulses];
/// parts.dart stays the desktop's copy).
_View _viewOf(SuperTabParts parts, String accountId) {
  final state = parts.state;
  if (parts.derived['pulse'] case final Map pulse) state['pulse'] = pulse;
  for (final conversation in state['conversations'] as List) {
    if (conversation case {'id': final String id} && final Map row) {
      row['changedAt'] = parts.groupChangedAt(id);
    }
  }
  return (
    snapshot: SuperTabSnapshot.fromJson(state),
    partners: swarmPartners(state),
    buddies: SwarmBuddies.read(state, accountId),
  );
}

/// Whether a Swarm whose first load is [answer] is big enough to be worked
/// out off the UI isolate: its groups and agents are nearly all of it.
bool _big(Map<String, dynamic> answer) =>
    ((answer['groups'] as List?)?.length ?? 0) +
        ((answer['agents'] as List?)?.length ?? 0) >=
    swarmParseOffThreadParts;

/// [work], off the UI isolate when [big]. Top-level, so its closures carry
/// only what they are handed, never a reader.
Future<T> _offThread<T>(bool big, T Function() work) =>
    big ? Isolate.run(work) : Future.sync(work);

Future<_View> _view(
  SuperTabParts parts,
  String accountId, {
  required bool big,
}) => _offThread(big, () => _viewOf(parts, accountId));

Future<({SuperTabParts parts, _View view})> _load(
  Map<String, dynamic> answer,
  String accountId,
) => _offThread(_big(answer), () {
  final parts = SuperTabParts.firstLoad(answer);
  return (parts: parts, view: _viewOf(parts, accountId));
});

/// One Swarm as this phone keeps it current: a first load, then only the parts
/// that changed since its cursor (docs/design/2026-10-26-swarm-state-parts.md,
/// section 4) — the desktop's `SuperTabController` read, without its panes,
/// drafts and launches.
///
/// It reads only while [shown]: a phone pays for every read in data and
/// battery, and a Swarm nobody is looking at needs none (the web build's
/// `SuperTabReading.pausesAway`). Shown again, it reads at once.
class SwarmReader extends ChangeNotifier {
  SwarmReader({
    required this.tabId,
    required this.accountId,
    required this.request,
    this.upload = refuseSwarmUpload,
    this.pollInterval = const Duration(seconds: 5),
  });

  final String tabId, accountId;
  final SwarmRequest request;

  /// Sends a chat's file to the backend ([SwarmConversation.send]).
  final SwarmUpload upload;
  final Duration pollInterval;

  /// The Swarm as last read; null before the first read and after access ends.
  SuperTabSnapshot? snapshot;

  /// Each conversation's partner, the person its work needs ([swarmPartners]).
  Map<String, String> partners = const {};

  /// The Buddy chats and Buddies held, the reader's own by project
  /// ([swarmBuddyChat], [swarmBuddy]).
  SwarmBuddies buddies = SwarmBuddies.none;

  /// How far the person has read each chat, which its inbox keeps with it;
  /// null where nobody keeps them, and nothing reads as unread.
  SwarmReadMarks? readMarks;

  /// The account's drafts and unsent posts, which its inbox keeps; null where
  /// nobody keeps them, and each chat holds its own while it is open.
  SwarmKept? kept;

  /// What the last read could not do, as a sentence; null once one succeeds.
  String? error;

  /// The newest change of any part, as the last read said: what tells a list
  /// this Swarm changed. -1 before the first read. A move of it alone is no
  /// notify, only a [reads] count.
  int lastChangedAt = -1;

  /// The reader may no longer read this Swarm: it left, or was removed.
  bool accessRevoked = false;

  /// Moves each time what this reader holds is read again from nothing (a
  /// first load) or taken away: an answer asked for under an earlier one may
  /// carry what the reader can no longer see, and is not applied.
  int generation = 0;

  /// The backend needs a newer build: no read can succeed, so none is tried.
  bool updateRequired = false;

  /// True until the first read answers, either way.
  bool get loading => snapshot == null && error == null && !accessRevoked;

  /// Counts the reads that answered, changed or not: what tells a read that
  /// failed beside this one to try again, where the Swarm itself stays as it
  /// was and so tells nothing.
  ValueListenable<int> get reads => _reads;
  final _reads = ValueNotifier(0);

  /// Counts the first loads asked for, each told once its request is out:
  /// what is read alongside one answers no earlier than it does.
  ValueListenable<int> get firstLoads => _firstLoads;
  final _firstLoads = ValueNotifier(0);

  /// Which of [firstLoads] what this reader holds came from; 0 while it holds
  /// none.
  int get heldLoad => _heldLoad;
  int _heldLoad = 0;

  SuperTabParts? _parts;

  /// The first load held was big ([swarmParseOffThreadParts]): its changes
  /// are drawn off the UI isolate too.
  bool _bigParts = false;

  /// Counts what was drawn: one worked out off the UI isolate is not shown
  /// over one drawn meanwhile from the parts as they are now.
  int _views = 0;
  Future<void>? _refreshing;
  Timer? _poll;
  bool _shown = false, _disposed = false;

  String get _path => '/api/super-tabs/${Uri.encodeComponent(tabId)}';

  bool get shown => _shown;

  /// On screen: reads at once and every [pollInterval] after. Off screen:
  /// reads nothing.
  set shown(bool value) {
    if (_shown == value) return;
    _shown = value;
    _poll?.cancel();
    _poll = null;
    if (value) unawaited(_tick());
  }

  Future<void> _tick() async {
    await refresh();
    if (_disposed || !_shown || updateRequired || accessRevoked) return;
    _poll?.cancel();
    _poll = Timer(pollInterval, () => unawaited(_tick()));
  }

  /// A read is under way ([refresh]): one joined now may have been sent
  /// before what asks, and answer what was so then.
  bool get refreshing => _refreshing != null;

  /// One read now, joining one under way.
  Future<void> refresh() {
    if (_disposed || accessRevoked || updateRequired) return Future.value();
    return _refreshing ??= _read().whenComplete(() => _refreshing = null);
  }

  Future<Map<String, dynamic>> _get(String path) async =>
      superTabMap(await request('GET', path));

  Future<void> _read() async {
    var changed = false;
    final failedBefore = error;
    final serial = ++_readSerial;
    try {
      final read = await _readParts();
      if (_disposed || accessRevoked) return;
      final parts = _parts!;
      // Sent before this read began: what it holds is the server's own now.
      final settled = _notifyKept.length;
      _notifyKept.removeWhere((_, kept) => kept.$2 < serial);
      if (_notifyKept.length != settled) changed = true;
      if (read.changed || snapshot == null) {
        final views = _views;
        final view = read.view ?? await _view(parts, accountId, big: _bigParts);
        if (_disposed || accessRevoked) return;
        if (view.snapshot.id != tabId) {
          _parts = null;
          throw const FormatException('A different Swarm was returned.');
        }
        if (views == _views && identical(parts, _parts)) {
          _show(view);
          changed = true;
        }
      }
      // Moved alone, it is a change this reader cannot see: nothing to draw
      // again. What waits on it hears of it through [reads].
      lastChangedAt = parts.lastChangedAt;
      error = null;
      _reads.value++;
    } on SuperTabFailure catch (failure) {
      if (_disposed || accessRevoked) return;
      if (failure.statusCode == 426 ||
          (failure.code == 'UPDATE_REQUIRED' && failure.statusCode != 400)) {
        updateRequired = true;
        error = 'Update Harness to keep using this Swarm.';
        _poll?.cancel();
      } else if (const {'FORBIDDEN', 'NOT_FOUND'}.contains(failure.code)) {
        // Refused a first load: nothing of a Swarm it left stays on screen.
        _forget();
        error = failure.message;
      } else {
        error = failure.message;
      }
      changed = true;
    } on FormatException catch (failure) {
      if (_disposed || accessRevoked) return;
      error = failure.message.isEmpty
          ? 'Could not read this Swarm.'
          : failure.message;
      changed = true;
    } catch (_) {
      if (_disposed || accessRevoked) return;
      error = 'Could not reach this Swarm. Try again.';
      changed = true;
    }
    // Once per failure, not once per poll. Home shows its skeleton meanwhile.
    if (error case final failed? when failed != failedBefore) {
      appLog.warn('swarm', 'Swarm $tabId not read: $failed');
    }
    if (changed || error != failedBefore) notifyListeners();
  }

  /// Changes since the cursor once a first load is held, else a first load. A
  /// reload answer, or a change read refused for access (the Swarm or the
  /// reader's access moved), loads in full at once.
  Future<({bool changed, _View? view})> _readParts() async {
    final held = _parts;
    if (held != null) {
      try {
        final answer = await _get('$_path/changes?${held.changesQuery}');
        if (answer['reload'] != true) {
          final SuperTabPartsChange change;
          try {
            change = held.apply(answer);
          } catch (_) {
            // Half merged: the next read starts again from a first load.
            if (identical(_parts, held)) _parts = null;
            rethrow;
          }
          final stale = await _refreshStale(held);
          return (changed: change.changed || stale, view: null);
        }
      } on SuperTabFailure catch (failure) {
        // A backend rolled back to one without the summary etag refuses it
        // (#2906): read in full, which holds none.
        final etagRefused =
            failure.code == 'VALIDATION_ERROR' && held.derivedEtag != null;
        if (!etagRefused &&
            !const {'FORBIDDEN', 'NOT_FOUND'}.contains(failure.code)) {
          rethrow;
        }
      }
      _parts = null;
    }
    final asked = _get('$_path/parts');
    final number = ++_firstLoads.value;
    final answer = await asked;
    final load = await _load(answer, accountId);
    // Revoked meanwhile: what was read is not kept.
    if (_disposed || accessRevoked) return (changed: false, view: null);
    _parts = load.parts;
    _bigParts = _big(answer);
    _heldLoad = number;
    generation++;
    // A new store holds no closed conversations: they are read again.
    _dormantPages.clear();
    _dormantReads.clear();
    return (changed: true, view: load.view);
  }

  void _show(_View view) {
    snapshot = view.snapshot;
    partners = view.partners;
    buddies = view.buddies;
    swarmMarkBuddies(view.snapshot, view.buddies);
    _views++;
  }

  /// The reader may no longer read this Swarm — a first load was refused, or
  /// it left the account's list: nothing read of it stays, and it reads no
  /// more. Its listeners hear of it, so a screen holding it lets go too.
  void revoke() {
    if (_disposed || accessRevoked) return;
    _forget();
    error = null;
    notifyListeners();
  }

  void _forget() {
    accessRevoked = true;
    _notifySending.clear();
    _notifyKept.clear();
    snapshot = null;
    partners = const {};
    buddies = SwarmBuddies.none;
    _parts = null;
    _heldLoad = 0;
    generation++;
    _dormantPages.clear();
    _dormantReads.clear();
    _poll?.cancel();
  }

  /// The reader's notification setting for chat [id] (backend
  /// chatSettings.ts): the one being sent, else the one the server kept and
  /// no read has carried yet, else the last read's, else Mentions only.
  SwarmNotify notifyOf(String id) =>
      _notifySending[id] ??
      _notifyKept[id]?.$1 ??
      SwarmNotify.parse(snapshot?.chatSettings[id]);

  /// Settings sent and not yet answered: the newest choice per chat, with
  /// its number.
  final _notifySending = <String, SwarmNotify>{};
  final _notifyAsked = <String, int>{};

  /// Settings the server kept, until a read carries them, with the number of
  /// the newest read begun when it answered: one begun after it carries the
  /// setting. Without it a chat would flick back to the last read's setting
  /// meanwhile.
  final _notifyKept = <String, (SwarmNotify, int)>{};

  /// Reads begun, in order ([_read]).
  int _readSerial = 0;

  /// Keeps [level] for chat [id] on every device of the reader, through the
  /// desktop's own call: shown at once, and the old setting back when the
  /// server did not keep it. A later choice for the same chat wins over one
  /// still on its way. False only when the newest choice was not kept; an
  /// answer after access went changes nothing.
  Future<bool> setNotify(String id, SwarmNotify level) async {
    if (_disposed || accessRevoked || snapshot?.conversation(id) == null) {
      return false;
    }
    final asked = (_notifyAsked[id] ?? 0) + 1;
    _notifyAsked[id] = asked;
    _notifySending[id] = level;
    notifyListeners();
    var kept = false;
    try {
      final answer = superTabMap(
        await request(
          'POST',
          '$_path/conversations/${Uri.encodeComponent(id)}/notifications',
          body: {'notify': level.name},
        ),
      );
      kept = answer['notify'] == level.name;
    } catch (_) {
      kept = false;
    }
    // A newer choice for this chat settles it; access gone takes it away.
    if (_disposed || accessRevoked || _notifyAsked[id] != asked) return true;
    _notifyAsked.remove(id);
    _notifySending.remove(id);
    // Kept only while the chat is still one the reader reads.
    if (kept && snapshot?.conversation(id) != null) {
      _notifyKept[id] = (level, _readSerial);
    }
    notifyListeners();
    return kept;
  }

  /// A dormant stub says a held group closed, not how: its data is read again
  /// by id. Best effort: a failure leaves it as it was until the next read.
  Future<bool> _refreshStale(SuperTabParts parts) async {
    var read = false;
    for (final id in parts.staleGroups) {
      try {
        if (await _readGroup(parts, id)) {
          read = true;
        } else {
          parts.forgetStale(id);
        }
      } on SuperTabFailure {
        // Tried again at the next read.
      }
    }
    return read;
  }

  /// Reads group [id] by id into [parts], active or closed (section 4.5).
  /// False when the reader cannot read it.
  Future<bool> _readGroup(SuperTabParts parts, String id) async {
    try {
      final answer = await _get('$_path/groups/${Uri.encodeComponent(id)}');
      if (!identical(parts, _parts)) return false;
      parts.addDormant([answer['group']]);
      return true;
    } on SuperTabFailure catch (failure) {
      if (const {'FORBIDDEN', 'NOT_FOUND'}.contains(failure.code)) return false;
      rethrow;
    }
  }

  /// Makes conversation [id] part of [snapshot]: one a first load leaves out
  /// (closed, or quiet for a day) is read by id, as a decision or a tag can
  /// point at one. False when the reader cannot read it; a read that failed
  /// throws, as it says nothing of whether it could.
  Future<bool> loadConversation(String id) async {
    if (snapshot?.conversation(id) != null) return true;
    if (_parts == null) {
      await refresh();
      if (snapshot?.conversation(id) != null) return true;
    }
    if (_disposed || accessRevoked) return false;
    final parts = _parts;
    if (parts == null) {
      throw SuperTabFailure(
        'UNAVAILABLE',
        error ?? 'Could not read this Swarm.',
      );
    }
    final bool readable;
    try {
      readable = await _readGroup(parts, id);
    } on SuperTabFailure catch (failure) {
      if (!_disposed) {
        error = failure.message;
        notifyListeners();
      }
      rethrow;
    }
    if (_disposed || accessRevoked) return false;
    // Read again from nothing meanwhile: that read is the one to ask.
    if (!identical(parts, _parts)) return loadConversation(id);
    if (!readable) return false;
    _show(_viewOf(parts, accountId));
    notifyListeners();
    return snapshot?.conversation(id) != null;
  }

  /// Each project's closed conversations as read: where the next earlier
  /// page starts, null when there is none. A project not here is not read.
  final _dormantPages = <String, String?>{};
  final _dormantReads = <String, Future<void>>{};

  /// Whether [projectId]'s closed conversations have been read.
  bool dormantLoaded(String projectId) => _dormantPages.containsKey(projectId);

  /// Whether a read of [projectId]'s closed conversations is under way.
  bool dormantLoading(String projectId) => _dormantReads.containsKey(projectId);

  /// Whether [projectId] has closed conversations older than those read.
  bool hasEarlierDormant(String projectId) => _dormantPages[projectId] != null;

  /// Reads [projectId]'s closed conversations (archived, or quiet for a day),
  /// which no first load has, newest first and a page at a time (section
  /// 4.5): the first page once, [earlier] the next. Joins a read under way;
  /// a read that failed throws, and asking again reads again — the desktop's
  /// `loadDormant`.
  Future<void> loadDormant(String projectId, {bool earlier = false}) {
    if (_disposed || accessRevoked || _parts == null) return Future.value();
    if (_dormantReads[projectId] case final reading?) return reading;
    if (earlier ? !hasEarlierDormant(projectId) : dormantLoaded(projectId)) {
      return Future.value();
    }
    late final Future<void> reading;
    reading = _readDormant(projectId, earlier).whenComplete(() {
      if (identical(_dormantReads[projectId], reading)) {
        _dormantReads.remove(projectId);
      }
      if (!_disposed) notifyListeners();
    });
    _dormantReads[projectId] = reading;
    notifyListeners();
    return reading;
  }

  Future<void> _readDormant(String projectId, bool earlier) async {
    final parts = _parts!;
    final before = earlier ? _dormantPages[projectId] : null;
    final answer = await _get(
      '$_path/groups?dormant=1&projectId=${Uri.encodeQueryComponent(projectId)}'
      '${before == null ? '' : '&before=${Uri.encodeQueryComponent(before)}'}',
    );
    // Read again from nothing meanwhile: this page is of the parts before.
    if (_disposed || accessRevoked || !identical(parts, _parts)) return;
    final change = parts.addDormant(answer['groups'] as List);
    _dormantPages[projectId] = answer['next'] as String?;
    if (change.changed) _show(_viewOf(parts, accountId));
  }

  @override
  void dispose() {
    _disposed = true;
    _poll?.cancel();
    _reads.dispose();
    _firstLoads.dispose();
    super.dispose();
  }
}