Sync Needs-you dismissals and chat read state across devices

This commit is contained in:
2026-10-31 12:47:25 +00:00
parent f4b3ef17cc
commit d1aa36163a
12 changed files with 1164 additions and 14 deletions
+21
View File
@@ -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<PipelinesApp>
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<JsonMap>? _attentionFrames;
int _attentionEpoch = 0;
@@ -169,6 +183,8 @@ class _PipelinesAppState extends State<PipelinesApp>
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<PipelinesApp>
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<PipelinesApp>
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
@@ -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<String> dismissed;
final Map<String, int> 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)),
);
}
@@ -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<String?> read();
Future<bool> 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<SharedPreferences?> _preferences() async {
try {
return await SharedPreferences.getInstance();
} catch (_) {
return null;
}
}
@override
Future<String?> read() async {
try {
return (await _preferences())?.getString(_key);
} catch (_) {
return null;
}
}
@override
Future<bool> 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<String?> read() async => stored;
@override
Future<bool> write(String value) async {
stored = value;
return true;
}
}
@@ -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<JsonMap> _frames;
final Map<String, Completer<JsonMap>> _replies = {};
AttentionAcks _acks = const AttentionAcks();
AttentionAcks _pending = const AttentionAcks();
Future<void>? _loading;
Future<void>? _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<void> load() => _loading ??= _load();
Future<void> _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<void> acknowledge({
Iterable<String> dismissed = const [],
Map<String, int> 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<void> 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<void> flush() => _flushing ??= _flush().whenComplete(() {
_flushing = null;
});
Future<void> _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<JsonMap> _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<JsonMap>();
_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<void> _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<AttentionAckSync>('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];
@@ -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<AttentionTransition> _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<bool> dismiss(AttentionEntry entry) =>
_commit(attentionDismiss(_dismissed, entry.key));
Future<bool> dismiss(AttentionEntry entry) {
_share([entry.key]);
return _commit(attentionDismiss(_dismissed, entry.key));
}
/// Applies only the identities captured when the sheet opened.
Future<bool> clearAll(Iterable<AttentionEntry> snapshot) =>
_commit(attentionDismissAll(_dismissed, snapshot));
Future<bool> clearAll(Iterable<AttentionEntry> 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<String> keys) {
final shared = sync;
if (_disposed || shared == null || keys.isEmpty) return;
unawaited(shared.acknowledge(dismissed: keys));
}
Future<bool> _commit(Set<String> next) async {
final unchanged =
@@ -174,6 +209,7 @@ class AttentionController extends ChangeNotifier {
@override
void dispose() {
_disposed = true;
sync?.removeListener(_syncChanged);
super.dispose();
}
}
@@ -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<String, String> _actionErrors = {};
List<JsonMap> _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<void> _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();
}
}
+97
View File
@@ -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.
@@ -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<String, dynamic> _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<void> start(List<Map<String, dynamic>> rows) async {
await sync.load();
await attention.load();
attention.seedRows(rows);
await sync.connected();
}
List<int> 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']));
});
}
@@ -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 = <FakeAckClient>[];
/// 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<JsonMap> 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<JsonMap>.broadcast();
final calls = <String>[];
bool online = true;
@override
Stream<JsonMap> get frames => pushed.stream;
@override
Future<JsonMap> 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<void> settle() async {
for (var i = 0; i < 10; i++) {
await Future<void>.delayed(Duration.zero);
}
}
@@ -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<void> 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<void>.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);
});
}
+5 -1
View File
@@ -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.
+16
View File
@@ -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`,