From d1aa36163a25bf0f48b860927a6eba2eb2e23f97 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 31 Oct 2026 12:47:25 +0000 Subject: [PATCH] Sync Needs-you dismissals and chat read state across devices --- app/lib/application/pipelines_app.dart | 21 ++ .../attention/domain/attention_acks.dart | 110 ++++++++ .../runtime/attention_ack_queue.dart | 66 +++++ .../attention/runtime/attention_ack_sync.dart | 239 ++++++++++++++++++ .../runtime/attention_controller.dart | 48 +++- .../ui/sessions/chat_sessions_controller.dart | 97 ++++++- app/notes/synced-attention.md | 97 +++++++ .../runtime/attention_ack_sync_test.dart | 198 +++++++++++++++ .../attention/runtime/fake_ack_server.dart | 113 +++++++++ .../chat/ui/sessions/chat_seen_sync_test.dart | 167 ++++++++++++ docs/cli.md | 6 +- docs/ntfy.md | 16 ++ 12 files changed, 1164 insertions(+), 14 deletions(-) create mode 100644 app/lib/features/attention/domain/attention_acks.dart create mode 100644 app/lib/features/attention/runtime/attention_ack_queue.dart create mode 100644 app/lib/features/attention/runtime/attention_ack_sync.dart create mode 100644 app/notes/synced-attention.md create mode 100644 app/test/features/attention/runtime/attention_ack_sync_test.dart create mode 100644 app/test/features/attention/runtime/fake_ack_server.dart create mode 100644 app/test/features/chat/ui/sessions/chat_seen_sync_test.dart diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart index 374e7594..1d20559a 100644 --- a/app/lib/application/pipelines_app.dart +++ b/app/lib/application/pipelines_app.dart @@ -13,6 +13,8 @@ import '../shell/destination.dart'; import '../features/attention/notify/notification_controller.dart'; import '../features/attention/notify/chat_question_notices.dart'; import '../features/attention/notify/notification_store.dart'; +import '../features/attention/runtime/attention_ack_queue.dart'; +import '../features/attention/runtime/attention_ack_sync.dart'; import '../features/attention/runtime/attention_controller.dart'; import '../features/attention/runtime/attention_store.dart'; import '../features/runs/ui/run_search_selection.dart'; @@ -126,6 +128,18 @@ class _PipelinesAppState extends State store: SharedPreferencesAttentionStore( serverId: serverStorageScope(widget.serverId), ), + sync: _ackSync, + ); + + /// Shares Needs-you dismissals and chat read watermarks with every device + /// through the server. Bound to the gateway so the chat list (created by its + /// destination) uses the same channel; refreshed on every connection. + late final AttentionAckSync _ackSync = AttentionAckSync( + gateway: _session.gateway, + sendOnly: _session.client.sendOnly, + queue: SharedPreferencesAttentionAckQueue( + serverId: serverStorageScope(widget.serverId), + ), ); StreamSubscription? _attentionFrames; int _attentionEpoch = 0; @@ -169,6 +183,8 @@ class _PipelinesAppState extends State if (mounted) _delegate.goTo(AppRoute.run(id)); }; unawaited(_notifications.load()); + bindAttentionAckSync(_session.gateway, _ackSync); + unawaited(_ackSync.load()); unawaited(_attention.load()); _attentionFrames = _session.gateway.frames .where((frame) => frame['type'] == 'run_event') @@ -216,6 +232,8 @@ class _PipelinesAppState extends State unawaited(_attentionFrames?.cancel()); _attention.removeListener(_attentionChanged); _attention.dispose(); + bindAttentionAckSync(_session.gateway, null); + _ackSync.dispose(); _attentionCount.dispose(); _notifications.dispose(); _chatQuestionNotices?.dispose(); @@ -275,6 +293,9 @@ class _PipelinesAppState extends State if (epoch == _attentionEpoch) return; _attentionEpoch = epoch; _attention.resetForReconnect(); + // Every connected transition sends acknowledgements queued while offline + // and re-reads the shared set, so a gap cannot leave this device stale. + if (_session.connected) unawaited(_ackSync.connected()); } /// Mirrors the controller's entry count for the shell. The Runs list seeds diff --git a/app/lib/features/attention/domain/attention_acks.dart b/app/lib/features/attention/domain/attention_acks.dart new file mode 100644 index 00000000..e1d7f18c --- /dev/null +++ b/app/lib/features/attention/domain/attention_acks.dart @@ -0,0 +1,110 @@ +import 'dart:convert'; + +import '../../../core/api_gateway.dart'; + +/// The server-shared "I have seen this" state (`attention_acks` on the wire): +/// dismissed Needs-you identities (`{runId}:{kind}`) and per-chat-session +/// read watermarks in epoch milliseconds. +/// +/// The set only grows — dismissals are added and watermarks only advance — so +/// merging is a union/maximum and applying a frame twice or out of order is +/// harmless. The same shape is used for the whole set, a pushed delta and the +/// offline queue of acknowledgements not yet accepted by the server. +class AttentionAcks { + const AttentionAcks({this.dismissed = const {}, this.chatSeen = const {}}); + + final Set dismissed; + final Map chatSeen; + + bool get isEmpty => dismissed.isEmpty && chatSeen.isEmpty; + + int get length => dismissed.length + chatSeen.length; + + /// The union of both sets, keeping the larger watermark per session. + /// Returns this instance when [other] adds nothing. + AttentionAcks merge(AttentionAcks other) { + final addsDismissal = !dismissed.containsAll(other.dismissed); + final advances = other.chatSeen.entries.any( + (entry) => entry.value > (chatSeen[entry.key] ?? 0), + ); + if (!addsDismissal && !advances) return this; + final seen = {...chatSeen}; + other.chatSeen.forEach((id, at) { + if (at > (seen[id] ?? 0)) seen[id] = at; + }); + return AttentionAcks( + dismissed: {...dismissed, ...other.dismissed}, + chatSeen: seen, + ); + } + + /// What remains of this queue after [sent] was accepted: a dismissal is + /// gone once sent, a watermark only when no newer value was queued since. + AttentionAcks without(AttentionAcks sent) => AttentionAcks( + dismissed: dismissed.difference(sent.dismissed), + chatSeen: { + for (final entry in chatSeen.entries) + if (entry.value > (sent.chatSeen[entry.key] ?? 0)) + entry.key: entry.value, + }, + ); + + /// The wire body of `ack_attention` / the stored queue. + JsonMap toJson() { + final keys = dismissed.toList()..sort(); + return {'dismissed': keys, 'chat_seen': chatSeen}; + } + + String encode() => jsonEncode(toJson()); + + /// Total decode of a wire or stored value: unreadable members are skipped + /// and a malformed value is the empty set, never an exception. + static AttentionAcks fromJson(Object? value) { + if (value is! Map) return const AttentionAcks(); + final dismissed = value['dismissed']; + final chatSeen = value['chat_seen']; + return AttentionAcks( + dismissed: { + if (dismissed is List) + for (final key in dismissed) + if (key is String && key.isNotEmpty) key, + }, + chatSeen: { + if (chatSeen is Map) + for (final entry in chatSeen.entries) + if (entry.key is String && + entry.value is num && + (entry.value as num) > 0) + entry.key as String: (entry.value as num).toInt(), + }, + ); + } + + static AttentionAcks decode(String? stored) { + final text = (stored ?? '').trim(); + if (text.isEmpty) return const AttentionAcks(); + try { + return fromJson(jsonDecode(text)); + } catch (_) { + return const AttentionAcks(); + } + } +} + +/// The server's bound on one `ack_attention`; a larger queue is sent in parts. +const maxAttentionAckItems = 500; + +/// The first [limit] items of [acks], dismissals first, for one request. +AttentionAcks attentionAckBatch( + AttentionAcks acks, { + int limit = maxAttentionAckItems, +}) { + if (acks.length <= limit) return acks; + final keys = acks.dismissed.toList()..sort(); + final dismissed = keys.take(limit).toSet(); + final room = limit - dismissed.length; + return AttentionAcks( + dismissed: dismissed, + chatSeen: Map.fromEntries(acks.chatSeen.entries.take(room)), + ); +} diff --git a/app/lib/features/attention/runtime/attention_ack_queue.dart b/app/lib/features/attention/runtime/attention_ack_queue.dart new file mode 100644 index 00000000..3dd58e2a --- /dev/null +++ b/app/lib/features/attention/runtime/attention_ack_queue.dart @@ -0,0 +1,66 @@ +import 'package:shared_preferences/shared_preferences.dart'; + +import '../../../core/servers/server_scope.dart'; + +/// Persistence for acknowledgements made while the server could not take +/// them (offline, or a server without `ack_attention`). The value is the +/// opaque string from `AttentionAcks.encode`; both directions may fail, and a +/// failure only means the queue lives in memory for this session. +abstract interface class AttentionAckQueueStore { + Future read(); + + Future write(String value); +} + +/// `shared_preferences` storage scoped to the server, like the other device +/// caches. An unavailable plugin returns null/false instead of throwing. +class SharedPreferencesAttentionAckQueue implements AttentionAckQueueStore { + const SharedPreferencesAttentionAckQueue({this.serverId = ''}); + + static const key = 'pipelines.next.attention.pending_acks.v1'; + + final String serverId; + String get _key => scopedServerKey(key, serverId); + + Future _preferences() async { + try { + return await SharedPreferences.getInstance(); + } catch (_) { + return null; + } + } + + @override + Future read() async { + try { + return (await _preferences())?.getString(_key); + } catch (_) { + return null; + } + } + + @override + Future write(String value) async { + try { + return await (await _preferences())?.setString(_key, value) ?? false; + } catch (_) { + return false; + } + } +} + +/// An in-memory queue for tests and isolated fixtures. +class MemoryAttentionAckQueue implements AttentionAckQueueStore { + MemoryAttentionAckQueue({this.stored}); + + String? stored; + + @override + Future read() async => stored; + + @override + Future write(String value) async { + stored = value; + return true; + } +} diff --git a/app/lib/features/attention/runtime/attention_ack_sync.dart b/app/lib/features/attention/runtime/attention_ack_sync.dart new file mode 100644 index 00000000..6edabd0c --- /dev/null +++ b/app/lib/features/attention/runtime/attention_ack_sync.dart @@ -0,0 +1,239 @@ +import 'dart:async'; + +import 'package:flutter/foundation.dart'; + +import '../../../core/api_gateway.dart'; +import '../../../core/transport/connection_state.dart'; +import '../domain/attention_acks.dart'; +import 'attention_ack_queue.dart'; + +/// Keeps this device's attention acknowledgements in step with the server so +/// clearing on one device clears everywhere. +/// +/// [acks] is everything known to be acknowledged: the server's set, every +/// pushed `attention_acks_changed` delta and this device's own acknowledgements +/// (applied at once, before the server answers). Listeners — the Needs-you +/// controller and the chat list — fold it into their own state. +/// +/// An acknowledgement the server has not accepted yet stays in a persisted +/// queue and is re-sent on the next [connected]. A server refusal drops the +/// refused batch (it can never succeed); a server that does not know +/// `ack_attention` keeps the queue for a later upgrade and this device falls +/// back to its local state. +/// +/// With [sendOnly] (the app passes the socket's own send-only path, as the +/// run watch does) requests are not queued behind the transport's serialized +/// request/reply calls, so a connect-time read never delays the first screen's +/// list; the reply is matched by id from the pushed frames. +class AttentionAckSync extends ChangeNotifier { + AttentionAckSync({ + required this.gateway, + required this.queue, + this.sendOnly, + this.replyTimeout = const Duration(seconds: 30), + }) { + _frames = gateway.frames.listen(_onFrame); + } + + final ApiGateway gateway; + final AttentionAckQueueStore queue; + final String Function(String type, JsonMap fields)? sendOnly; + final Duration replyTimeout; + late final StreamSubscription _frames; + final Map> _replies = {}; + + AttentionAcks _acks = const AttentionAcks(); + AttentionAcks _pending = const AttentionAcks(); + Future? _loading; + Future? _flushing; + bool _supported = true; + bool _disposed = false; + + /// Everything acknowledged on any device, as far as this device knows. + AttentionAcks get acks => _acks; + + /// Acknowledgements made here that the server has not accepted yet. + AttentionAcks get pending => _pending; + + /// False after the server answered `attention_acks` with something else + /// (an older server); reset on the next [connected]. + bool get supported => _supported; + + /// Reads the persisted offline queue once. + Future load() => _loading ??= _load(); + + Future _load() async { + String? stored; + try { + stored = await queue.read(); + } catch (_) { + stored = null; + } + if (_disposed) return; + final queued = AttentionAcks.decode(stored); + _pending = queued.merge(_pending); + _apply(queued); + } + + /// Records an acknowledgement made on this device: it applies here at once + /// and is sent to the server (now, or on the next [connected]). + Future acknowledge({ + Iterable dismissed = const [], + Map chatSeen = const {}, + }) async { + final ack = AttentionAcks( + dismissed: { + for (final key in dismissed) + if (key.trim().isNotEmpty) key, + }, + chatSeen: { + for (final entry in chatSeen.entries) + if (entry.key.isNotEmpty && entry.value > 0) entry.key: entry.value, + }, + ); + if (_disposed || ack.isEmpty) return; + await load(); + if (_disposed) return; + _pending = _pending.merge(ack); + _apply(ack); + await _persist(); + await flush(); + } + + /// Called on every connected transition of the shared socket: send what was + /// queued while disconnected, then read the server's whole set. + Future connected() async { + if (_disposed) return; + _supported = true; + // Replies still awaited belong to the replaced socket and never arrive; + // fail them now so a stalled flush does not hold up this connection. + _failReplies(StateError('Connection replaced')); + await load(); + await flush(); + if (_disposed || !_supported) return; + try { + final reply = await _request('attention_acks'); + _accept(reply); + } catch (_) { + // Offline or refused: the local state still applies; the next + // connection reads again. + } + } + + /// Sends the queue in bounded batches, one request at a time. + Future flush() => _flushing ??= _flush().whenComplete(() { + _flushing = null; + }); + + Future _flush() async { + while (!_disposed && _supported && !_pending.isEmpty) { + final batch = attentionAckBatch(_pending); + try { + final reply = await _request('ack_attention', { + 'attention_acks': batch.toJson(), + }); + if (!_accept(reply)) return; + } on ProtocolError { + // The server refused this batch; it will never be accepted. + } catch (_) { + return; // Not connected or timed out: keep it for the next connection. + } + _pending = _pending.without(batch); + await _persist(); + } + } + + /// Folds an `attention_acks` reply; false when the server answered with + /// another type, i.e. it does not support shared acknowledgements. + bool _accept(JsonMap reply) { + if (reply['type'] != 'attention_acks') { + _supported = false; + return false; + } + _apply(AttentionAcks.fromJson(reply['attention_acks'])); + return true; + } + + void _onFrame(JsonMap frame) { + final id = frame['id']; + final reply = id is String ? _replies.remove(id) : null; + if (reply != null) { + if (frame['type'] == 'error') { + final reason = '${frame['error'] ?? ''}'.trim(); + reply.completeError( + ProtocolError(reason.isEmpty ? 'server error' : reason), + ); + } else { + reply.complete(frame); + } + return; + } + if (frame['type'] != 'attention_acks_changed') return; + _apply(AttentionAcks.fromJson(frame['attention_acks'])); + } + + /// One request: through [sendOnly] when available (reply matched by id), + /// else the gateway's ordinary request/reply call. + Future _request(String type, [JsonMap fields = const {}]) { + final send = sendOnly; + if (send == null) return gateway.call(type, fields); + final String id; + try { + id = send(type, fields); + } catch (error) { + return Future.error(error); + } + final reply = Completer(); + _replies[id] = reply; + return reply.future.timeout( + replyTimeout, + onTimeout: () { + _replies.remove(id); + throw TimeoutException('$type timed out', replyTimeout); + }, + ); + } + + void _apply(AttentionAcks incoming) { + if (_disposed) return; + final next = _acks.merge(incoming); + if (identical(next, _acks)) return; + _acks = next; + notifyListeners(); + } + + Future _persist() async { + try { + await queue.write(_pending.encode()); + } catch (_) { + // The queue still lives in memory for this session. + } + } + + @override + void dispose() { + _disposed = true; + unawaited(_frames.cancel()); + _failReplies(StateError('Attention sync disposed')); + super.dispose(); + } + + void _failReplies(Object error) { + final waiting = _replies.values.toList(); + _replies.clear(); + for (final reply in waiting) { + reply.completeError(error); + } + } +} + +final _syncs = Expando('attention acknowledgement sync'); + +/// Makes [sync] the acknowledgement channel of [gateway], so feature +/// controllers created later for the same socket (the chat list) share it. +void bindAttentionAckSync(ApiGateway gateway, AttentionAckSync? sync) { + _syncs[gateway] = sync; +} + +/// The acknowledgement channel bound to [gateway], if the app bound one. +AttentionAckSync? attentionAckSyncOf(ApiGateway gateway) => _syncs[gateway]; diff --git a/app/lib/features/attention/runtime/attention_controller.dart b/app/lib/features/attention/runtime/attention_controller.dart index d80e3fcc..697152ba 100644 --- a/app/lib/features/attention/runtime/attention_controller.dart +++ b/app/lib/features/attention/runtime/attention_controller.dart @@ -6,6 +6,7 @@ import '../../../core/api_gateway.dart'; import '../../runs/domain/run_events.dart'; import '../domain/attention_models.dart'; import '../domain/attention_transitions.dart'; +import 'attention_ack_sync.dart'; import 'attention_store.dart'; /// The live `Needs you` state behind the Runs-list bell. @@ -20,11 +21,22 @@ import 'attention_store.dart'; /// [AttentionStore] without blocking the caller. A failed read or write leaves /// the in-memory set in force for this session; neither direction can throw into /// the UI. +/// +/// With a [sync], dismissals are shared with every device: Dismiss and Clear +/// all are also acknowledged to the server, and identities dismissed elsewhere +/// (the server's set and pushed deltas) are folded in and cached locally, so +/// the local store doubles as the offline copy. class AttentionController extends ChangeNotifier { - AttentionController({required this.store, DateTime Function()? now}) - : _now = now ?? DateTime.now; + AttentionController({ + required this.store, + this.sync, + DateTime Function()? now, + }) : _now = now ?? DateTime.now { + sync?.addListener(_syncChanged); + } final AttentionStore store; + final AttentionAckSync? sync; final DateTime Function() _now; final AttentionTransitionDetector _detector = AttentionTransitionDetector(); final List _transitions = []; @@ -75,6 +87,16 @@ class AttentionController extends ChangeNotifier { // older stored value; the in-memory set is the operator's latest intent. if (!_dirty) _dismissed = stored; notifyListeners(); + _syncChanged(); + } + + /// Folds identities acknowledged on any device into this set. A change is + /// cached in the local store; nothing is sent back to the server. + void _syncChanged() { + final shared = sync?.acks.dismissed; + if (_disposed || !_loaded || shared == null) return; + if (_dismissed.containsAll(shared)) return; + unawaited(_commit({..._dismissed, ...shared})); } /// Replaces the drawn rows with an authoritative read. @@ -149,12 +171,25 @@ class AttentionController extends ChangeNotifier { /// The in-memory set and the bell update before the store is touched, so a /// slow or failed write never blocks the sheet. The returned future reports /// whether the write succeeded; callers that do not need it may ignore it. - Future dismiss(AttentionEntry entry) => - _commit(attentionDismiss(_dismissed, entry.key)); + Future dismiss(AttentionEntry entry) { + _share([entry.key]); + return _commit(attentionDismiss(_dismissed, entry.key)); + } /// Applies only the identities captured when the sheet opened. - Future clearAll(Iterable snapshot) => - _commit(attentionDismissAll(_dismissed, snapshot)); + Future clearAll(Iterable snapshot) { + final entries = snapshot.toList(); + _share([for (final entry in entries) entry.key]); + return _commit(attentionDismissAll(_dismissed, entries)); + } + + /// Acknowledges [keys] to every device. The sync queues them while offline, + /// and sending never blocks or fails the local dismissal. + void _share(List keys) { + final shared = sync; + if (_disposed || shared == null || keys.isEmpty) return; + unawaited(shared.acknowledge(dismissed: keys)); + } Future _commit(Set next) async { final unchanged = @@ -174,6 +209,7 @@ class AttentionController extends ChangeNotifier { @override void dispose() { _disposed = true; + sync?.removeListener(_syncChanged); super.dispose(); } } diff --git a/app/lib/features/chat/ui/sessions/chat_sessions_controller.dart b/app/lib/features/chat/ui/sessions/chat_sessions_controller.dart index 64b49a62..e11afd84 100644 --- a/app/lib/features/chat/ui/sessions/chat_sessions_controller.dart +++ b/app/lib/features/chat/ui/sessions/chat_sessions_controller.dart @@ -1,10 +1,12 @@ import 'dart:async'; +import 'dart:math'; import 'package:flutter/foundation.dart'; import '../../../../core/api_gateway.dart'; import '../../../../core/servers/server_scope.dart'; import '../../../../core/transport/connection_state.dart'; +import '../../../attention/runtime/attention_ack_sync.dart'; import '../../data/chat_repository.dart'; import '../../domain/chat_sessions.dart'; import 'chat_session_local.dart'; @@ -16,18 +18,40 @@ import 'session_attention.dart'; /// discarded, so a slow reply can never replace fresher state. Accepted /// mutations always re-read the server list; only this device's hidden ids and /// read watermark are local. +/// +/// With an [AttentionAckSync] (bound to the gateway by the app, or passed in), +/// reading is shared: opening a chat acknowledges a `chat_seen` watermark to +/// every device, and a watermark acknowledged elsewhere that is newer than this +/// device's own clears the chat's New badge here. The local store remains the +/// offline cache of both. class ChatSessionsController extends ChangeNotifier { - ChatSessionsController(this.repository, {ChatSessionLocalStore? localStore}) - : _localStore = - localStore ?? - SharedPreferencesChatSessionLocalStore( - serverId: serverStorageScope(serverIdentity(repository.gateway)), - ) { + ChatSessionsController( + this.repository, { + ChatSessionLocalStore? localStore, + AttentionAckSync? ackSync, + int Function()? nowMillis, + this.activeAckDelay = const Duration(milliseconds: 1500), + }) : _localStore = + localStore ?? + SharedPreferencesChatSessionLocalStore( + serverId: serverStorageScope(serverIdentity(repository.gateway)), + ), + _nowMillis = nowMillis ?? _wallClockMillis { _listenFrames(); + _bindAckSync(ackSync ?? attentionAckSyncOf(repository.gateway)); } + static int _wallClockMillis() => DateTime.now().millisecondsSinceEpoch; + + /// How long the open chat stays quiet before its new content is + /// acknowledged to the other devices; streaming text arrives in many frames. + final Duration activeAckDelay; + ChatRepository repository; final ChatSessionLocalStore _localStore; + final int Function() _nowMillis; + AttentionAckSync? _ackSync; + Timer? _activeAck; ChatSessionLocal _local = const ChatSessionLocal(); final Map _actionErrors = {}; List _sessions = const []; @@ -59,6 +83,59 @@ class ChatSessionsController extends ChangeNotifier { if (row['closed_at'] != null || row['closed'] == true) return; if (effect.running != null) _setRunning(id, effect.running!); if (effect.attention && id != activeSessionId) unawaited(_markUnseen(id)); + if (effect.attention && id == activeSessionId) _scheduleActiveAck(id); + } + + void _bindAckSync(AttentionAckSync? sync) { + if (identical(sync, _ackSync)) return; + _ackSync?.removeListener(_ackChanged); + _ackSync = sync; + sync?.addListener(_ackChanged); + _ackChanged(); + } + + /// Content arriving in the chat this device has open is read here, so it is + /// acknowledged to the other devices once the stream goes quiet. + void _scheduleActiveAck(String id) { + if (_ackSync == null) return; + _activeAck?.cancel(); + _activeAck = Timer(activeAckDelay, () { + if (_disposed || id != activeSessionId) return; + unawaited(_acknowledgeSeen(id, 0)); + }); + } + + /// Applies watermarks acknowledged on any device: one newer than this + /// device's own marks the chat read here (clearing its New badge) and raises + /// the local watermark, so a later badge is not cleared by the same ack. + void _ackChanged() { + final seen = _ackSync?.acks.chatSeen; + if (_disposed || !_localLoaded || seen == null) return; + var next = _local; + seen.forEach((id, at) { + if (at > next.watermark(id)) next = next.read(id, at); + }); + if (identical(next, _local)) return; + _local = next; + _notify(); + unawaited(_persist()); + } + + /// Marks [id] read up to now here and acknowledges it to every device. The + /// value is at least the row's own recency; the server lifts it further to + /// the session's registry recency. + Future _acknowledgeSeen(String id, int updatedAt) async { + await _ensureLocal(); + if (_disposed) return; + final at = max(updatedAt, _nowMillis()); + final next = _local.read(id, at); + if (!identical(next, _local)) { + _local = next; + _notify(); + await _persist(); + } + if (_disposed) return; + await _ackSync?.acknowledge(chatSeen: {id: at}); } void _setRunning(String id, bool running) { @@ -126,6 +203,7 @@ class ChatSessionsController extends ChangeNotifier { repository = next; _runningFrames.clear(); _listenFrames(); + _bindAckSync(attentionAckSyncOf(next.gateway) ?? _ackSync); refresh(); } @@ -242,7 +320,9 @@ class ChatSessionsController extends ChangeNotifier { activeSessionId = id; await _ensureLocal(); if (_disposed) return; - final next = _local.read(id, chatSessionMillis(session['updated_at'])); + final updatedAt = chatSessionMillis(session['updated_at']); + if (_ackSync != null) return _acknowledgeSeen(id, updatedAt); + final next = _local.read(id, updatedAt); if (identical(next, _local)) return; _local = next; _notify(); @@ -313,6 +393,7 @@ class ChatSessionsController extends ChangeNotifier { } _localLoaded = true; _seedLocal(); + _ackChanged(); _notify(); } @@ -351,6 +432,8 @@ class ChatSessionsController extends ChangeNotifier { _disposed = true; _generation++; unawaited(_frameSubscription?.cancel()); + _activeAck?.cancel(); + _ackSync?.removeListener(_ackChanged); super.dispose(); } } diff --git a/app/notes/synced-attention.md b/app/notes/synced-attention.md new file mode 100644 index 00000000..81d655d2 --- /dev/null +++ b/app/notes/synced-attention.md @@ -0,0 +1,97 @@ +# Synced attention: clearing on one device clears everywhere + +Operator request: "when I clear notifications, it should clear in all places, +not only on the web and then I have to clear again on mobile." + +## What is shared + +- **Needs-you dismissals.** Dismiss and Clear all in the Needs-you sheet. Each + entry's identity is `{runId}:{Decision|Failed}` (`attentionKey`). +- **Chat New badges.** Opening a chat, and content arriving in the chat this + device has open, records a per-session `chat_seen` watermark in epoch ms. + +ntfy notifications already shown on a phone cannot be retracted (see +`docs/ntfy.md`, "Clearing notifications across devices"). + +## Protocol (server, `internal/protocol/attention_acks.go`) + +| Direction | Envelope | +| --- | --- | +| read | `{"type":"attention_acks"}` → `{"type":"attention_acks","attention_acks":{"dismissed":[…],"chat_seen":{…}}}` (the whole set) | +| add | `{"type":"ack_attention","attention_acks":{"dismissed":["42:Failed"],"chat_seen":{"ses_x":1730000000000}}}` → same reply (the whole set) | +| push | `{"type":"attention_acks_changed","attention_acks":{…}}`: only what changed, sent to every *other* connection | + +The set only grows: dismissals are added and watermarks only advance. That makes +merging a union/max that is safe to apply in any order or twice. Invalid +identities, invalid session ids, non-positive times, empty acks and acks with +more than 500 items are refused with `error`, and nothing is written. Dismissals +of unknown runs and watermarks for sessions that are not operator sessions are +skipped silently. A stored watermark is +`max(old, client value, operator_sessions.last_used_at)`. + +Storage: two additive SQLite tables, `attention_dismissals(key, run_id, +dismissed_at)` and `chat_seen_watermarks(session_id, seen_at, acked_at)`, +created in `Store.Open`. Each ack prunes rows for deleted runs and sessions, and +rows older than 30 days (`AttentionAckRetention`). + +**Clear all** sends the identities the sheet showed (its snapshot), not a +"cleared up to time T" marker. A time marker would hide a run created before T +that starts waiting on a person after T. The snapshot keeps the existing +"entries that arrive later stay" rule, and the request is bounded to 500 +identities per batch. + +## App + +- `features/attention/domain/attention_acks.dart`: the value type (merge, + `without`, encode/decode, bounded batches). +- `features/attention/runtime/attention_ack_sync.dart` (`AttentionAckSync`): one + per app/gateway, bound with `bindAttentionAckSync`. It applies local + acknowledgements immediately and queues them persistently + (`attention_ack_queue.dart`, SharedPreferences, server-scoped). On every + connected transition it flushes the queue and reads the set. It also applies + pushed deltas. It sends through the socket's send-only path, so the + connect-time read never queues ahead of the first screen's request. A + refusal drops the batch. An older server that answers `pong` keeps the queue + and turns syncing off until the next connection, so the local state still + applies. +- `AttentionController(sync:)`: Dismiss and Clear all also acknowledge. Shared + identities are unioned into the local set and cached in the existing local + store, which acts as the offline copy. +- `ChatSessionsController`: looks up the bound sync. Opening a chat stores and + acknowledges `max(row updated_at, now)`. A shared watermark newer than this + device's own clears the badge and raises the local watermark, so the same + acknowledgement cannot later clear newer content. Content arriving in the open + chat is acknowledged after 1.5 s of quiet. +- `PipelinesApp` creates and binds the sync, loads the queue, and calls + `connected()` on each connection epoch. + +The Needs-you sheet layout was not touched. + +## Known limits + +- The chat watermark compares a device clock with server times, so large clock + skew can mis-order a badge. +- An acknowledgement queued offline for a long time can clear a badge for + content that arrived between the offline open and the reconnect. +- Local dismissals made before this change are not uploaded. Only new + dismissals are shared. + +## Tests + +- Go: `internal/pipeline/attention_acks_test.go` (persist/reopen, advance-only, + unknown skipped, registry lift, prune deleted/expired, malformed refused), + `internal/server/attention_acks_test.go` (two websocket clients: push to the + other, no push for malformed/no-op acks), and + `internal/protocol/attention_acks_test.go`. +- Flutter: `test/features/attention/runtime/attention_ack_sync_test.dart` (two + devices: dismiss, Clear all, late connect, offline queue, restart, refusal, + legacy server, send-only path) and + `test/features/chat/ui/sessions/chat_seen_sync_test.dart` (open clears + everywhere, an earlier ack never clears later content, open-chat content, and + offline open synced on reconnect). + +## Deployment + +The server needs a rebuild and restart to serve the new requests; the tables are +created on open. The rebuilt web app and APK also need publishing. Until the +server is upgraded, the app keeps working with its local state and its queue. diff --git a/app/test/features/attention/runtime/attention_ack_sync_test.dart b/app/test/features/attention/runtime/attention_ack_sync_test.dart new file mode 100644 index 00000000..7f67f4cf --- /dev/null +++ b/app/test/features/attention/runtime/attention_ack_sync_test.dart @@ -0,0 +1,198 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/attention/domain/attention_acks.dart'; +import 'package:pipelines_app/features/attention/runtime/attention_ack_queue.dart'; +import 'package:pipelines_app/features/attention/runtime/attention_ack_sync.dart'; +import 'package:pipelines_app/features/attention/runtime/attention_controller.dart'; +import 'package:pipelines_app/features/attention/runtime/attention_store.dart'; + +import 'fake_ack_server.dart'; + +final _now = DateTime(2026, 10, 22, 12); + +Map _failed(int id) => { + 'id': id, + 'name': 'release', + 'title': 'Run $id', + 'status': 'failed', + 'created_at': _now.subtract(const Duration(hours: 1)).toIso8601String(), + 'finished_at': _now.subtract(const Duration(minutes: 30)).toIso8601String(), +}; + +/// One device: its gateway, sync, local stores and Needs-you controller. +class _Device { + _Device(FakeAckServer server) + : client = server.connect(), + store = MemoryAttentionStore(), + queue = MemoryAttentionAckQueue() { + sync = AttentionAckSync(gateway: client, queue: queue); + attention = AttentionController(store: store, sync: sync, now: () => _now); + } + + final FakeAckClient client; + final MemoryAttentionStore store; + final MemoryAttentionAckQueue queue; + late final AttentionAckSync sync; + late final AttentionController attention; + + Future start(List> rows) async { + await sync.load(); + await attention.load(); + attention.seedRows(rows); + await sync.connected(); + } + + List get shown => [for (final e in attention.entries) e.runId]; + + void dispose() { + attention.dispose(); + sync.dispose(); + } +} + +void main() { + late FakeAckServer server; + late _Device web; + late _Device phone; + final rows = [_failed(1), _failed(2), _failed(3)]; + + setUp(() async { + server = FakeAckServer(); + web = _Device(server); + phone = _Device(server); + await web.start(rows); + await phone.start(rows); + }); + + tearDown(() { + web.dispose(); + phone.dispose(); + }); + + test( + 'a dismissal on one device disappears on the other via the push', + () async { + expect(phone.shown, [3, 2, 1]); + await web.attention.dismiss( + web.attention.entries.firstWhere((e) => e.runId == 2), + ); + await settle(); + + expect(web.shown, [3, 1]); + expect(phone.shown, [3, 1]); + expect(server.state.dismissed, {'2:Failed'}); + // The other device caches the shared identity locally for offline use. + expect(phone.store.stored, contains('2:Failed')); + // The receiving device did not send anything back. + expect(phone.client.count('ack_attention'), 0); + }, + ); + + test('Clear all on the web clears the phone too', () async { + final snapshot = web.attention.entries; + await web.attention.clearAll(snapshot); + await settle(); + + expect(web.shown, isEmpty); + expect(phone.shown, isEmpty); + expect(server.state.dismissed, {'1:Failed', '2:Failed', '3:Failed'}); + }); + + test('a device that connects later loads the shared set', () async { + await web.attention.dismiss(web.attention.entries.first); + await settle(); + final late = _Device(server); + addTearDown(late.dispose); + await late.start(rows); + await settle(); + expect(late.shown, [2, 1]); + }); + + test( + 'a dismissal made offline is queued, then synced on reconnect', + () async { + phone.client.online = false; + await phone.attention.dismiss(phone.attention.entries.first); + await settle(); + + expect(phone.shown, [2, 1]); + expect(web.shown, [3, 2, 1]); + expect(phone.sync.pending.dismissed, {'3:Failed'}); + expect(AttentionAcks.decode(phone.queue.stored).dismissed, {'3:Failed'}); + + // A restarted app reads the persisted queue. + final restarted = AttentionAckSync( + gateway: phone.client, + queue: phone.queue, + ); + addTearDown(restarted.dispose); + await restarted.load(); + expect(restarted.pending.dismissed, {'3:Failed'}); + + phone.client.online = true; + await phone.sync.connected(); + await settle(); + + expect(phone.sync.pending.isEmpty, isTrue); + expect(AttentionAcks.decode(phone.queue.stored).isEmpty, isTrue); + expect(web.shown, [2, 1]); + }, + ); + + test('a refused batch is dropped; a legacy server keeps the queue', () async { + server.refuse = 'invalid attention identity'; + await web.sync.acknowledge(dismissed: ['9:Failed']); + expect(web.sync.pending.isEmpty, isTrue); + + server + ..refuse = null + ..legacy = true; + await web.sync.connected(); + expect(web.sync.supported, isFalse); + await web.attention.dismiss(web.attention.entries.first); + await settle(); + expect(web.shown, [2, 1], reason: 'the local dismissal still applies'); + expect(web.sync.pending.dismissed, {'3:Failed'}); + + server.legacy = false; + await web.sync.connected(); + await settle(); + expect(web.sync.pending.isEmpty, isTrue); + expect(phone.shown, [2, 1]); + }); + + test('batches stay within the server bound', () { + final big = AttentionAcks( + dismissed: {for (var i = 1; i <= 600; i++) '$i:Failed'}, + chatSeen: const {'ses_a': 1}, + ); + final batch = attentionAckBatch(big); + expect(batch.length, maxAttentionAckItems); + final rest = big.without(batch); + expect(rest.length, big.length - maxAttentionAckItems); + }); + + test('the send-only path matches replies and refusals by id', () async { + final client = server.connect(); + final sync = AttentionAckSync( + gateway: client, + queue: MemoryAttentionAckQueue(), + sendOnly: client.sendOnly, + ); + addTearDown(sync.dispose); + await sync.acknowledge(dismissed: ['1:Failed']); + await settle(); + expect(sync.pending.isEmpty, isTrue); + expect(phone.shown, [3, 2]); + + server.refuse = 'invalid attention identity'; + await sync.acknowledge(dismissed: ['2:Failed']); + await settle(); + expect(sync.pending.isEmpty, isTrue, reason: 'a refusal is dropped'); + + server.refuse = null; + await web.attention.dismiss(web.attention.entries.first); + await settle(); + await sync.connected(); + expect(sync.acks.dismissed, containsAll(['1:Failed', '3:Failed'])); + }); +} diff --git a/app/test/features/attention/runtime/fake_ack_server.dart b/app/test/features/attention/runtime/fake_ack_server.dart new file mode 100644 index 00000000..78cf75fe --- /dev/null +++ b/app/test/features/attention/runtime/fake_ack_server.dart @@ -0,0 +1,113 @@ +import 'dart:async'; + +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/core/transport/connection_state.dart'; +import 'package:pipelines_app/features/attention/domain/attention_acks.dart'; + +/// An in-memory stand-in for the server's `attention_acks` / `ack_attention` +/// protocol with any number of connected clients. Like the Go handler, an ack +/// that changes the set is pushed to every *other* connected client as an +/// `attention_acks_changed` delta. +class FakeAckServer { + AttentionAcks state = const AttentionAcks(); + final clients = []; + + /// When set, every ack_attention is refused with this reason. + String? refuse; + + /// When true the server predates shared acks and answers `pong`. + bool legacy = false; + + /// The chat list this server reports, for chat-list controllers. + List chatSessions = const []; + + FakeAckClient connect() { + final client = FakeAckClient(this); + clients.add(client); + return client; + } + + JsonMap _reply() => { + 'type': 'attention_acks', + 'attention_acks': state.toJson(), + }; + + JsonMap _ack(FakeAckClient from, JsonMap fields) { + final incoming = AttentionAcks.fromJson(fields['attention_acks']); + final delta = AttentionAcks( + dismissed: incoming.dismissed.difference(state.dismissed), + chatSeen: { + for (final entry in incoming.chatSeen.entries) + if (entry.value > (state.chatSeen[entry.key] ?? 0)) + entry.key: entry.value, + }, + ); + state = state.merge(incoming); + if (!delta.isEmpty) { + for (final client in clients) { + if (identical(client, from) || !client.online) continue; + client.pushed.add({ + 'type': 'attention_acks_changed', + 'attention_acks': delta.toJson(), + }); + } + } + return _reply(); + } +} + +class FakeAckClient implements ApiGateway { + FakeAckClient(this.server); + + final FakeAckServer server; + final pushed = StreamController.broadcast(); + final calls = []; + bool online = true; + + @override + Stream get frames => pushed.stream; + + @override + Future call(String type, [JsonMap fields = const {}]) async { + calls.add(type); + if (!online) throw const NotConnectedError(); + switch (type) { + case 'attention_acks': + case 'ack_attention': + if (server.legacy) return {'type': 'pong'}; + if (type == 'attention_acks') return server._reply(); + final reason = server.refuse; + if (reason != null) throw ProtocolError(reason); + return server._ack(this, fields); + case 'chat_sessions': + return {'type': 'chat_sessions', 'chat_sessions': server.chatSessions}; + } + return {'type': 'pong'}; + } + + int count(String type) => calls.where((call) => call == type).length; + + var _sequence = 0; + + /// The socket's send-only path: the reply (or error) arrives later as a + /// frame carrying the request id, like the real transport. + String sendOnly(String type, JsonMap fields) { + if (!online) throw const NotConnectedError(); + final id = 'send-${++_sequence}'; + scheduleMicrotask(() async { + try { + pushed.add({...await call(type, fields), 'id': id}); + } on ProtocolError catch (error) { + pushed.add({'type': 'error', 'id': id, 'error': error.message}); + } + }); + return id; + } +} + +/// Lets queued microtasks and stream deliveries settle. +Future settle() async { + for (var i = 0; i < 10; i++) { + await Future.delayed(Duration.zero); + } +} diff --git a/app/test/features/chat/ui/sessions/chat_seen_sync_test.dart b/app/test/features/chat/ui/sessions/chat_seen_sync_test.dart new file mode 100644 index 00000000..51258f9d --- /dev/null +++ b/app/test/features/chat/ui/sessions/chat_seen_sync_test.dart @@ -0,0 +1,167 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/attention/runtime/attention_ack_queue.dart'; +import 'package:pipelines_app/features/attention/runtime/attention_ack_sync.dart'; +import 'package:pipelines_app/features/chat/data/chat_repository.dart'; +import 'package:pipelines_app/features/chat/ui/sessions/chat_session_local.dart'; +import 'package:pipelines_app/features/chat/ui/sessions/chat_sessions_controller.dart'; + +import '../../../attention/runtime/fake_ack_server.dart'; +import 'chat_test_harness.dart'; + +JsonMap _text(String id) => { + 'type': 'chat_event', + 'chat_event': {'session_id': id, 'kind': 'text', 'delta': 'hello'}, +}; + +/// One device's chat list sharing read state through [FakeAckServer]. +class _Device { + _Device(FakeAckServer server, {required this.clock}) + : client = server.connect(), + local = MemoryChatSessionLocalStore() { + sync = AttentionAckSync(gateway: client, queue: MemoryAttentionAckQueue()); + bindAttentionAckSync(client, sync); + list = ChatSessionsController( + ChatRepository(client), + localStore: local, + nowMillis: () => clock(), + activeAckDelay: const Duration(milliseconds: 20), + ); + } + + final FakeAckClient client; + final MemoryChatSessionLocalStore local; + final int Function() clock; + late final AttentionAckSync sync; + late final ChatSessionsController list; + + Future start() async { + await sync.connected(); + await list.refresh(); + await settle(); + } + + bool isNew(String id) => + list.isUnseen(list.sessions.firstWhere((row) => row['id'] == id)); + + JsonMap row(String id) => list.sessions.firstWhere((row) => row['id'] == id); + + void dispose() { + list.dispose(); + sync.dispose(); + } +} + +void main() { + late FakeAckServer server; + late _Device web; + late _Device phone; + var now = 5000; + + setUp(() async { + now = 5000; + server = FakeAckServer() + ..chatSessions = [ + {'id': 'ses_a', 'title': 'A', 'directory': '/w', 'updated_at': 1000}, + {'id': 'ses_b', 'title': 'B', 'directory': '/w', 'updated_at': 1000}, + ]; + web = _Device(server, clock: () => now); + phone = _Device(server, clock: () => now); + await web.start(); + await phone.start(); + }); + + tearDown(() { + web.dispose(); + phone.dispose(); + }); + + void pushToAll(JsonMap frame) { + for (final client in server.clients) { + client.pushed.add(frame); + } + } + + test( + 'opening a chat on one device clears its New badge everywhere', + () async { + pushToAll(_text('ses_a')); + await settle(); + expect(web.isNew('ses_a'), isTrue); + expect(phone.isNew('ses_a'), isTrue); + + now = 6000; + await web.list.markOpened(web.row('ses_a')); + await settle(); + + expect(server.state.chatSeen['ses_a'], 6000); + expect(phone.isNew('ses_a'), isFalse); + expect(phone.local.state?.watermark('ses_a'), 6000); + // Only the opened chat is affected. + pushToAll(_text('ses_b')); + await settle(); + expect(phone.isNew('ses_b'), isTrue); + }, + ); + + test('an earlier acknowledgement never clears later content', () async { + now = 6000; + await web.list.markOpened(web.row('ses_a')); + web.list.activeSessionId = null; + await settle(); + // New content after the open: the phone marks it New and a reload of the + // same shared watermark must not clear it. + pushToAll(_text('ses_a')); + await settle(); + expect(phone.isNew('ses_a'), isTrue); + await phone.sync.connected(); + await settle(); + expect(phone.isNew('ses_a'), isTrue); + }); + + test('content arriving in a chat open elsewhere is read there', () async { + now = 6000; + await web.list.markOpened(web.row('ses_a')); + await settle(); + now = 7000; + pushToAll(_text('ses_a')); + await settle(); + expect(phone.isNew('ses_a'), isTrue); + expect(web.isNew('ses_a'), isFalse); + + // The open chat acknowledges once its stream goes quiet (20 ms here). + for (var i = 0; i < 100 && server.state.chatSeen['ses_a'] != 7000; i++) { + await Future.delayed(const Duration(milliseconds: 20)); + } + await settle(); + expect(server.state.chatSeen['ses_a'], 7000); + expect(phone.isNew('ses_a'), isFalse); + }); + + test('a chat opened offline is synced and cleared on reconnect', () async { + pushToAll(_text('ses_a')); + await settle(); + web.client.online = false; + now = 6000; + await web.list.markOpened(web.row('ses_a')); + await settle(); + expect(phone.isNew('ses_a'), isTrue); + expect(web.sync.pending.chatSeen, {'ses_a': 6000}); + + web.client.online = true; + await web.sync.connected(); + await settle(); + expect(phone.isNew('ses_a'), isFalse); + + // A device that was not connected for the push applies the stored set + // on its next connection. + final late = _Device(server, clock: () => now); + addTearDown(late.dispose); + late.local.state = const ChatSessionLocal( + seenAt: {'ses_a': 1000}, + unseen: ['ses_a'], + ); + await late.start(); + expect(late.isNew('ses_a'), isFalse); + }); +} diff --git a/docs/cli.md b/docs/cli.md index e2c5978e..4d07158a 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -316,7 +316,11 @@ Existing protocol commands: `ping`, `list_pipelines`, `get_pipeline`, optional `kind` and `limit`) and returns a `search_results` response whose ranked `results` each carry a stable `target` the client can open plus the typed payload and matched field. `list_runs` also returns all-history `usage` -aggregates. See `internal/protocol/message.go` for JSON envelopes. Mutating RPCs +aggregates. `attention_acks` reads and `ack_attention` adds to the operator's +shared in-app acknowledgements (dismissed Needs-you entries and chat read +watermarks; see [ntfy.md](ntfy.md#clearing-notifications-across-devices)); other +connections receive an `attention_acks_changed` push. See +`internal/protocol/message.go` for JSON envelopes. Mutating RPCs have real effects; they are not previews. TUI-only animation, scrolling, and transient client logs are presentation, not separate server capabilities. diff --git a/docs/ntfy.md b/docs/ntfy.md index 26175f21..17eb2018 100644 --- a/docs/ntfy.md +++ b/docs/ntfy.md @@ -182,6 +182,22 @@ changes any subset; both reply with type `notification_settings` carrying all three keys. Unknown keys and non-boolean values are refused with an `error` reply and nothing is written. +## Clearing notifications across devices + +The app's in-app attention state is shared through the server: dismissing an +entry or using **Clear all** in the Needs-you sheet, and opening a chat (which +clears its **New** badge), clears it on every connected browser and phone at +once, and on a disconnected device when it next connects. The protocol is +`{"type":"attention_acks"}` (read the whole set) and +`{"type":"ack_attention","attention_acks":{"dismissed":["42:Failed"],"chat_seen":{"ses_x":1730000000000}}}` +(add to it). Both reply `attention_acks`, and every other connection receives an +`attention_acks_changed` frame with the change. Acknowledgements for deleted runs +or sessions, or older than 30 days, are pruned. + +This does **not** reach notifications the ntfy app has already shown on a phone: +once ntfy delivered a message, the server cannot retract it, so those must still +be swiped away in the ntfy app (or the Android notification shade). + ## Explicit delivery stage (optional) The preceding stage must output three nonempty UTF-8 strings: `title`, `summary`,