From f4b3ef17cc3c223878c7310729bd6f6b4dd7cade Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 31 Oct 2026 12:23:51 +0000 Subject: [PATCH 1/2] Persist and broadcast shared attention acknowledgements --- internal/pipeline/attention_acks.go | 172 +++++++++++++++++++++++ internal/pipeline/attention_acks_test.go | 166 ++++++++++++++++++++++ internal/pipeline/store.go | 4 + internal/protocol/attention_acks.go | 89 ++++++++++++ internal/protocol/attention_acks_test.go | 37 +++++ internal/protocol/message.go | 4 + internal/server/attention_acks.go | 90 ++++++++++++ internal/server/attention_acks_test.go | 110 +++++++++++++++ internal/server/websocket.go | 12 ++ 9 files changed, 684 insertions(+) create mode 100644 internal/pipeline/attention_acks.go create mode 100644 internal/pipeline/attention_acks_test.go create mode 100644 internal/protocol/attention_acks.go create mode 100644 internal/protocol/attention_acks_test.go create mode 100644 internal/server/attention_acks.go create mode 100644 internal/server/attention_acks_test.go diff --git a/internal/pipeline/attention_acks.go b/internal/pipeline/attention_acks.go new file mode 100644 index 00000000..7012b94d --- /dev/null +++ b/internal/pipeline/attention_acks.go @@ -0,0 +1,172 @@ +package pipeline + +import ( + "context" + "database/sql" + "sort" + "strconv" + "strings" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// AttentionAckRetention bounds how long an acknowledgement is kept. The +// Needs-you list shows only today's work and a chat watermark is refreshed +// whenever the chat is opened, so a month-old acknowledgement protects nothing. +const AttentionAckRetention = 30 * 24 * time.Hour + +// initAttentionAcks creates the two additive acknowledgement tables. They are +// tables of their own so no run or session schema changes; run_id is kept as a +// column so pruning against pipeline_runs uses an integer comparison. +func (s *Store) initAttentionAcks() error { + _, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS attention_dismissals ( +key TEXT PRIMARY KEY, run_id INTEGER NOT NULL, dismissed_at INTEGER NOT NULL); +CREATE TABLE IF NOT EXISTS chat_seen_watermarks ( +session_id TEXT PRIMARY KEY, seen_at INTEGER NOT NULL, acked_at INTEGER NOT NULL);`) + return err +} + +type attentionQuerier interface { + QueryContext(context.Context, string, ...any) (*sql.Rows, error) +} + +func readAttentionAcks(ctx context.Context, q attentionQuerier) (protocol.AttentionAcks, error) { + acks := protocol.AttentionAcks{Dismissed: []string{}, ChatSeen: map[string]int64{}} + rows, err := q.QueryContext(ctx, `SELECT key FROM attention_dismissals ORDER BY key`) + if err != nil { + return acks, err + } + for rows.Next() { + var key string + if err := rows.Scan(&key); err != nil { + rows.Close() + return acks, err + } + acks.Dismissed = append(acks.Dismissed, key) + } + rows.Close() + if err := rows.Err(); err != nil { + return acks, err + } + rows, err = q.QueryContext(ctx, `SELECT session_id, seen_at FROM chat_seen_watermarks`) + if err != nil { + return acks, err + } + defer rows.Close() + for rows.Next() { + var id string + var at int64 + if err := rows.Scan(&id, &at); err != nil { + return acks, err + } + acks.ChatSeen[id] = at + } + return acks, rows.Err() +} + +// AttentionAcks returns every stored acknowledgement. +func (s *Store) AttentionAcks(ctx context.Context) (protocol.AttentionAcks, error) { + return readAttentionAcks(ctx, s.db) +} + +// AckAttention validates and records one acknowledgement, prunes stale rows, +// and returns the delta that actually changed the stored set together with the +// whole set afterwards. +// +// A dismissal of a run that does not exist is skipped, and so is a watermark +// for a session that is not in the operator registry, so a client cannot grow +// the tables with invented ids. A watermark only advances: the stored value is +// the maximum of the old value, the client's value and the session's own +// registry recency, so a device that opened the chat from a stale list row +// still acknowledges everything the server listed at that moment. +func (s *Store) AckAttention(ctx context.Context, ack *protocol.AttentionAcks, now time.Time) (delta, all protocol.AttentionAcks, err error) { + valid, err := protocol.ValidateAttentionAck(ack) + if err != nil { + return delta, all, err + } + tx, err := s.db.BeginTx(ctx, nil) + if err != nil { + return delta, all, err + } + defer tx.Rollback() + nowMillis := now.UnixMilli() + delta = protocol.AttentionAcks{Dismissed: []string{}, ChatSeen: map[string]int64{}} + for _, key := range valid.Dismissed { + runID, _ := strconv.ParseInt(key[:strings.IndexByte(key, ':')], 10, 64) + result, err := tx.ExecContext(ctx, `INSERT INTO attention_dismissals(key, run_id, dismissed_at) +SELECT ?, id, ? FROM pipeline_runs WHERE id=? ON CONFLICT(key) DO NOTHING`, key, nowMillis, runID) + if err != nil { + return delta, all, err + } + if n, _ := result.RowsAffected(); n > 0 { + delta.Dismissed = append(delta.Dismissed, key) + } + } + ids := make([]string, 0, len(valid.ChatSeen)) + for id := range valid.ChatSeen { + ids = append(ids, id) + } + sort.Strings(ids) + for _, id := range ids { + var recency, stored int64 + var hasStored bool + err := tx.QueryRowContext(ctx, `SELECT last_used_at FROM operator_sessions WHERE session_id=?`, id).Scan(&recency) + if err == sql.ErrNoRows { + continue + } + if err != nil { + return delta, all, err + } + switch err := tx.QueryRowContext(ctx, `SELECT seen_at FROM chat_seen_watermarks WHERE session_id=?`, id).Scan(&stored); err { + case nil: + hasStored = true + case sql.ErrNoRows: + default: + return delta, all, err + } + next := max(valid.ChatSeen[id], recency, stored) + if _, err := tx.ExecContext(ctx, `INSERT INTO chat_seen_watermarks(session_id, seen_at, acked_at) VALUES(?,?,?) +ON CONFLICT(session_id) DO UPDATE SET seen_at=excluded.seen_at, acked_at=excluded.acked_at`, id, next, nowMillis); err != nil { + return delta, all, err + } + if !hasStored || next > stored { + delta.ChatSeen[id] = next + } + } + if err := pruneAttentionAcks(ctx, tx, now); err != nil { + return delta, all, err + } + all, err = readAttentionAcks(ctx, tx) + if err != nil { + return delta, all, err + } + return delta, all, tx.Commit() +} + +// PruneAttentionAcks drops acknowledgements for runs and sessions that no +// longer exist and any older than AttentionAckRetention. +func (s *Store) PruneAttentionAcks(ctx context.Context, now time.Time) error { + tx, err := s.db.BeginTx(ctx, nil) + if err != nil { + return err + } + defer tx.Rollback() + if err := pruneAttentionAcks(ctx, tx, now); err != nil { + return err + } + return tx.Commit() +} + +func pruneAttentionAcks(ctx context.Context, tx *sql.Tx, now time.Time) error { + cutoff := now.Add(-AttentionAckRetention).UnixMilli() + for _, statement := range []string{ + `DELETE FROM attention_dismissals WHERE dismissed_at < ? OR run_id NOT IN (SELECT id FROM pipeline_runs)`, + `DELETE FROM chat_seen_watermarks WHERE acked_at < ? OR session_id NOT IN (SELECT session_id FROM operator_sessions)`, + } { + if _, err := tx.ExecContext(ctx, statement, cutoff); err != nil { + return err + } + } + return nil +} diff --git a/internal/pipeline/attention_acks_test.go b/internal/pipeline/attention_acks_test.go new file mode 100644 index 00000000..0498227f --- /dev/null +++ b/internal/pipeline/attention_acks_test.go @@ -0,0 +1,166 @@ +package pipeline + +import ( + "context" + "fmt" + "path/filepath" + "reflect" + "testing" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +func attentionAckFixture(t *testing.T) (*Store, string, []int64) { + t.Helper() + ctx := context.Background() + path := filepath.Join(t.TempDir(), "acks.db") + s, err := Open(path) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { s.Close() }) + if _, err := s.Submit(ctx, "acks", Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, err := s.List(ctx) + if err != nil { + t.Fatal(err) + } + definition, err := s.Get(ctx, items[0].ID, 1) + if err != nil { + t.Fatal(err) + } + var runs []int64 + for i := range 2 { + id, _, err := s.CreateRun(ctx, definition, fmt.Sprintf("ack-%d", i), "/work/acks", false, nil, map[string]any{"prompt": "task"}) + if err != nil { + t.Fatal(err) + } + runs = append(runs, id) + } + if err := s.RecordOperatorSession(ctx, "ses_seen", "/work/acks", "Seen", "operator"); err != nil { + t.Fatal(err) + } + return s, path, runs +} + +func TestAttentionAcksPersistAdvanceAndSkipUnknown(t *testing.T) { + ctx := context.Background() + s, path, runs := attentionAckFixture(t) + empty, err := s.AttentionAcks(ctx) + if err != nil || len(empty.Dismissed) != 0 || len(empty.ChatSeen) != 0 { + t.Fatalf("fresh acks = %+v, %v", empty, err) + } + session, _, err := s.OperatorSession(ctx, "ses_seen") + if err != nil { + t.Fatal(err) + } + failed := fmt.Sprintf("%d:Failed", runs[0]) + decision := fmt.Sprintf("%d:Decision", runs[1]) + now := time.Now() + delta, all, err := s.AckAttention(ctx, &protocol.AttentionAcks{ + Dismissed: []string{failed, failed, decision, "999999:Failed"}, + ChatSeen: map[string]int64{"ses_seen": session.UpdatedAt + 5, "ses_gone": 10}, + }, now) + if err != nil { + t.Fatal(err) + } + wantKeys := []string{decision, failed} + if decision > failed { + wantKeys = []string{failed, decision} + } + if !reflect.DeepEqual(delta.Dismissed, wantKeys) || !reflect.DeepEqual(all.Dismissed, wantKeys) { + t.Fatalf("dismissed delta=%v all=%v, want %v (unknown run skipped)", delta.Dismissed, all.Dismissed, wantKeys) + } + if len(delta.ChatSeen) != 1 || delta.ChatSeen["ses_seen"] != session.UpdatedAt+5 || len(all.ChatSeen) != 1 { + t.Fatalf("chat seen delta=%v all=%v", delta.ChatSeen, all.ChatSeen) + } + // A repeated dismissal and an older watermark change nothing: the stored + // value never moves backwards and the delta is empty. + delta, all, err = s.AckAttention(ctx, &protocol.AttentionAcks{Dismissed: []string{failed}, ChatSeen: map[string]int64{"ses_seen": 1}}, now) + if err != nil || !delta.Empty() || all.ChatSeen["ses_seen"] != session.UpdatedAt+5 { + t.Fatalf("repeat delta=%+v all=%+v err=%v", delta, all, err) + } + // A stale client value is lifted to the session's registry recency. + recency := session.UpdatedAt + 60_000 + if _, err := s.db.ExecContext(ctx, `UPDATE operator_sessions SET last_used_at=? WHERE session_id='ses_seen'`, recency); err != nil { + t.Fatal(err) + } + delta, _, err = s.AckAttention(ctx, &protocol.AttentionAcks{ChatSeen: map[string]int64{"ses_seen": 1}}, now) + if err != nil || delta.ChatSeen["ses_seen"] != recency { + t.Fatalf("lifted delta=%+v err=%v (recency %d)", delta, err, recency) + } + if err := s.Close(); err != nil { + t.Fatal(err) + } + reopened, err := Open(path) + if err != nil { + t.Fatal(err) + } + defer reopened.Close() + again, err := reopened.AttentionAcks(ctx) + if err != nil || !reflect.DeepEqual(again.Dismissed, wantKeys) || again.ChatSeen["ses_seen"] == 0 { + t.Fatalf("after reopen = %+v, %v", again, err) + } +} + +func TestAttentionAcksPruneDeletedAndExpired(t *testing.T) { + ctx := context.Background() + s, _, runs := attentionAckFixture(t) + now := time.Now() + old := now.Add(-AttentionAckRetention - time.Hour) + if _, _, err := s.AckAttention(ctx, &protocol.AttentionAcks{Dismissed: []string{fmt.Sprintf("%d:Failed", runs[0])}}, old); err != nil { + t.Fatal(err) + } + if _, _, err := s.AckAttention(ctx, &protocol.AttentionAcks{ + Dismissed: []string{fmt.Sprintf("%d:Failed", runs[1])}, + ChatSeen: map[string]int64{"ses_seen": 5}, + }, now); err != nil { + t.Fatal(err) + } + all, _ := s.AttentionAcks(ctx) + if len(all.Dismissed) != 1 || all.Dismissed[0] != fmt.Sprintf("%d:Failed", runs[1]) { + t.Fatalf("expired dismissal not pruned: %+v", all) + } + if _, err := s.db.ExecContext(ctx, `DELETE FROM pipeline_runs WHERE id=?`, runs[1]); err != nil { + t.Fatal(err) + } + if _, err := s.db.ExecContext(ctx, `DELETE FROM operator_sessions WHERE session_id='ses_seen'`); err != nil { + t.Fatal(err) + } + if err := s.PruneAttentionAcks(ctx, now); err != nil { + t.Fatal(err) + } + all, err := s.AttentionAcks(ctx) + if err != nil || len(all.Dismissed) != 0 || len(all.ChatSeen) != 0 { + t.Fatalf("acks for deleted run/session not pruned: %+v, %v", all, err) + } +} + +func TestAttentionAcksRejectMalformed(t *testing.T) { + ctx := context.Background() + s, _, runs := attentionAckFixture(t) + tooMany := make([]string, protocol.MaxAttentionAckItems+1) + for i := range tooMany { + tooMany[i] = fmt.Sprintf("%d:Failed", i+1) + } + for name, ack := range map[string]*protocol.AttentionAcks{ + "nil": nil, + "empty": {}, + "kind": {Dismissed: []string{fmt.Sprintf("%d:Running", runs[0])}}, + "zero run": {Dismissed: []string{"0:Failed"}}, + "bare": {Dismissed: []string{"Failed"}}, + "session id": {ChatSeen: map[string]int64{"../etc": 4}}, + "non-positive": {ChatSeen: map[string]int64{"ses_seen": 0}}, + "too many": {Dismissed: tooMany}, + } { + if _, _, err := s.AckAttention(ctx, ack, time.Now()); err == nil { + t.Errorf("%s: malformed ack accepted", name) + } + } + all, _ := s.AttentionAcks(ctx) + if !all.Empty() { + t.Fatalf("a refused ack wrote something: %+v", all) + } +} diff --git a/internal/pipeline/store.go b/internal/pipeline/store.go index fe412ae3..7f5a844d 100644 --- a/internal/pipeline/store.go +++ b/internal/pipeline/store.go @@ -77,6 +77,10 @@ CREATE TABLE IF NOT EXISTS submissions (id INTEGER PRIMARY KEY, name TEXT NOT NU db.Close() return nil, err } + if err := s.initAttentionAcks(); err != nil { + db.Close() + return nil, err + } return s, nil } diff --git a/internal/protocol/attention_acks.go b/internal/protocol/attention_acks.go new file mode 100644 index 00000000..15676f96 --- /dev/null +++ b/internal/protocol/attention_acks.go @@ -0,0 +1,89 @@ +package protocol + +import ( + "fmt" + "regexp" + "sort" +) + +// Attention acknowledgements are the operator's in-app "I have seen this" +// state, shared by every connected client so clearing on one device clears +// everywhere. A client reads the whole set with {"type":"attention_acks"} and +// adds to it with +// +// {"type":"ack_attention","attention_acks":{"dismissed":["42:Failed"],"chat_seen":{"ses_x":1730000000000}}} +// +// Both reply with type "attention_acks" carrying the whole stored set. After an +// accepted ack, every other connection receives an unsolicited +// {"type":"attention_acks_changed","attention_acks":{...}} frame holding only +// what that ack changed. The set only grows (dismissals are added, watermarks +// only advance), so applying frames in any order or twice is harmless. +// +// A dismissal identity is ":", the Needs-you entry +// identity. Clear all is a batch of the identities the client showed, so an +// entry that appears later is never hidden by an earlier clear. A chat_seen +// value is the chat session's updated_at (epoch milliseconds) the operator has +// read up to. +const ( + GetAttentionAcks = "attention_acks" + AckAttention = "ack_attention" + AttentionAcksReply = "attention_acks" + AttentionAcksChanged = "attention_acks_changed" +) + +// MaxAttentionAckItems bounds the dismissals plus watermarks one ack may carry. +const MaxAttentionAckItems = 500 + +// AttentionAcks is the wire form of the acknowledgement set (or a delta of it). +type AttentionAcks struct { + Dismissed []string `json:"dismissed"` + ChatSeen map[string]int64 `json:"chat_seen"` +} + +var attentionKeyPattern = regexp.MustCompile(`^[1-9][0-9]{0,18}:(Decision|Failed)$`) + +// chatSeenIDPattern mirrors the server's chat session id shapes (OpenCode +// ses_…, Codex/Claude UUIDs). +var chatSeenIDPattern = regexp.MustCompile(`^(?:ses_[A-Za-z0-9_]+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$`) + +// ValidAttentionKey reports whether key is a ":" identity. +func ValidAttentionKey(key string) bool { return attentionKeyPattern.MatchString(key) } + +// ValidateAttentionAck checks one ack request: at least one item, at most +// MaxAttentionAckItems, every dismissal a valid identity, and every watermark a +// valid chat session id with a positive millisecond value. It returns the +// dismissals deduplicated and sorted. +func ValidateAttentionAck(ack *AttentionAcks) (AttentionAcks, error) { + if ack == nil || len(ack.Dismissed)+len(ack.ChatSeen) == 0 { + return AttentionAcks{}, fmt.Errorf("attention_acks must name at least one dismissal or chat_seen watermark") + } + if len(ack.Dismissed)+len(ack.ChatSeen) > MaxAttentionAckItems { + return AttentionAcks{}, fmt.Errorf("attention_acks may carry at most %d items", MaxAttentionAckItems) + } + seen := make(map[string]struct{}, len(ack.Dismissed)) + result := AttentionAcks{Dismissed: []string{}, ChatSeen: map[string]int64{}} + for _, key := range ack.Dismissed { + if !ValidAttentionKey(key) { + return AttentionAcks{}, fmt.Errorf("invalid attention identity %q", key) + } + if _, dup := seen[key]; dup { + continue + } + seen[key] = struct{}{} + result.Dismissed = append(result.Dismissed, key) + } + sort.Strings(result.Dismissed) + for id, at := range ack.ChatSeen { + if !chatSeenIDPattern.MatchString(id) { + return AttentionAcks{}, fmt.Errorf("invalid chat session id %q", id) + } + if at <= 0 { + return AttentionAcks{}, fmt.Errorf("chat_seen %q must be a positive epoch-millisecond time", id) + } + result.ChatSeen[id] = at + } + return result, nil +} + +// Empty reports whether the set carries nothing. +func (a AttentionAcks) Empty() bool { return len(a.Dismissed) == 0 && len(a.ChatSeen) == 0 } diff --git a/internal/protocol/attention_acks_test.go b/internal/protocol/attention_acks_test.go new file mode 100644 index 00000000..5cc0970c --- /dev/null +++ b/internal/protocol/attention_acks_test.go @@ -0,0 +1,37 @@ +package protocol + +import ( + "encoding/json" + "reflect" + "testing" +) + +func TestValidateAttentionAckDedupesAndRefuses(t *testing.T) { + got, err := ValidateAttentionAck(&AttentionAcks{ + Dismissed: []string{"9:Failed", "12:Decision", "9:Failed"}, + ChatSeen: map[string]int64{"ses_a1": 7, "0123abcd-0123-4567-89ab-0123456789ab": 8}, + }) + if err != nil || !reflect.DeepEqual(got.Dismissed, []string{"12:Decision", "9:Failed"}) || len(got.ChatSeen) != 2 { + t.Fatalf("valid ack = %+v, %v", got, err) + } + for _, bad := range []*AttentionAcks{nil, {}, {Dismissed: []string{"-1:Failed"}}, {Dismissed: []string{"1:failed"}}, {ChatSeen: map[string]int64{"ses_x": -1}}, {ChatSeen: map[string]int64{"ses x": 1}}} { + if _, err := ValidateAttentionAck(bad); err == nil { + t.Errorf("accepted %+v", bad) + } + } +} + +func TestAttentionAcksWireShape(t *testing.T) { + raw := `{"type":"ack_attention","id":"1","attention_acks":{"dismissed":["3:Failed"],"chat_seen":{"ses_q":5}}}` + var message Message + if err := json.Unmarshal([]byte(raw), &message); err != nil { + t.Fatal(err) + } + if message.Type != AckAttention || message.AttentionAcks == nil || message.AttentionAcks.Dismissed[0] != "3:Failed" || message.AttentionAcks.ChatSeen["ses_q"] != 5 { + t.Fatalf("decoded = %+v", message) + } + out, _ := json.Marshal(Message{Type: AttentionAcksChanged, AttentionAcks: &AttentionAcks{Dismissed: []string{}, ChatSeen: map[string]int64{}}}) + if string(out) == "" || !json.Valid(out) { + t.Fatal("unencodable") + } +} diff --git a/internal/protocol/message.go b/internal/protocol/message.go index a87201da..57401d18 100644 --- a/internal/protocol/message.go +++ b/internal/protocol/message.go @@ -241,4 +241,8 @@ type Message struct { // NotificationSettings is the set_notification_settings partial update and // the notification_settings reply (every key). See notification_settings.go. NotificationSettings map[string]any `json:"notification_settings,omitempty"` + // AttentionAcks is the ack_attention body, the attention_acks reply (the + // whole set) and the attention_acks_changed push (the delta). See + // attention_acks.go. + AttentionAcks *AttentionAcks `json:"attention_acks,omitempty"` } diff --git a/internal/server/attention_acks.go b/internal/server/attention_acks.go new file mode 100644 index 00000000..280d5962 --- /dev/null +++ b/internal/server/attention_acks.go @@ -0,0 +1,90 @@ +package server + +import ( + "context" + "sync" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// attentionAckStore persists the shared in-app acknowledgements. +// *pipeline.Store implements it. +type attentionAckStore interface { + AttentionAcks(context.Context) (protocol.AttentionAcks, error) + AckAttention(context.Context, *protocol.AttentionAcks, time.Time) (delta, all protocol.AttentionAcks, err error) +} + +// attentionAckHub fans an accepted acknowledgement out to every other open +// connection, so a dismissal on one device disappears on the others live. +// It holds each connection's serialized write function, never the socket. +type attentionAckHub struct { + mu sync.Mutex + clients map[string]func(protocol.Message) error +} + +func newAttentionAckHub() *attentionAckHub { + return &attentionAckHub{clients: map[string]func(protocol.Message) error{}} +} + +func (h *attentionAckHub) attach(clientID string, write func(protocol.Message) error) { + h.mu.Lock() + defer h.mu.Unlock() + h.clients[clientID] = write +} + +func (h *attentionAckHub) detach(clientID string) { + h.mu.Lock() + defer h.mu.Unlock() + delete(h.clients, clientID) +} + +// broadcast pushes delta to every connection except the sender. Each write +// runs on its own goroutine (bounded by the connection's own write timeout), so +// one slow client cannot delay the sender's reply or the other clients. +func (h *attentionAckHub) broadcast(sender string, delta protocol.AttentionAcks) { + h.mu.Lock() + targets := make([]func(protocol.Message) error, 0, len(h.clients)) + for id, write := range h.clients { + if id != sender { + targets = append(targets, write) + } + } + h.mu.Unlock() + for _, write := range targets { + frame := delta + go func() { + _ = write(protocol.Message{Type: protocol.AttentionAcksChanged, AttentionAcks: &frame}) + }() + } +} + +// handleAttentionAcks answers attention_acks and ack_attention. It reports +// whether request was one of them. An ack that changes nothing (already +// dismissed, or a watermark that does not advance) replies with the whole set +// but pushes nothing. +func handleAttentionAcks(ctx context.Context, request protocol.Message, store attentionAckStore, hub *attentionAckHub, clientID string, write func(protocol.Message) error) bool { + if request.Type != protocol.GetAttentionAcks && request.Type != protocol.AckAttention { + return false + } + if store == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "attention acknowledgements are unavailable: no store"}) + return true + } + var all, delta protocol.AttentionAcks + var err error + if request.Type == protocol.GetAttentionAcks { + all, err = store.AttentionAcks(ctx) + } else { + delta, all, err = store.AckAttention(ctx, request.AttentionAcks, time.Now()) + } + if err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return true + } + _ = write(protocol.Message{Type: protocol.AttentionAcksReply, ID: request.ID, AttentionAcks: &all}) + if hub != nil && !delta.Empty() { + hub.broadcast(clientID, delta) + } + return true +} diff --git a/internal/server/attention_acks_test.go b/internal/server/attention_acks_test.go new file mode 100644 index 00000000..775cfcac --- /dev/null +++ b/internal/server/attention_acks_test.go @@ -0,0 +1,110 @@ +package server + +import ( + "context" + "fmt" + "net/http/httptest" + "strings" + "testing" + "time" + + "github.com/coder/websocket" + "github.com/coder/websocket/wsjson" + + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +func dialAckClient(t *testing.T, ctx context.Context, url string) *websocket.Conn { + t.Helper() + conn, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(url, "http")+"/connect", nil) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { conn.CloseNow() }) + var welcome protocol.Message + if err := wsjson.Read(ctx, conn, &welcome); err != nil { + t.Fatal(err) + } + return conn +} + +func ackExchange(t *testing.T, ctx context.Context, conn *websocket.Conn, request protocol.Message) protocol.Message { + t.Helper() + if err := wsjson.Write(ctx, conn, request); err != nil { + t.Fatal(err) + } + var reply protocol.Message + if err := wsjson.Read(ctx, conn, &reply); err != nil { + t.Fatal(err) + } + return reply +} + +func TestAttentionAcksSyncAcrossConnections(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + store := newOperatorStore(t) + if _, err := store.Submit(ctx, "acks", pipeline.Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, err := store.List(ctx) + if err != nil { + t.Fatal(err) + } + definition, err := store.Get(ctx, items[0].ID, 1) + if err != nil { + t.Fatal(err) + } + run, _, err := store.CreateRun(ctx, definition, "ack-run", t.TempDir(), false, nil, map[string]any{"prompt": "task"}) + if err != nil { + t.Fatal(err) + } + if err := store.RecordOperatorSession(ctx, "ses_sync", "/work", "Sync", "operator"); err != nil { + t.Fatal(err) + } + handlerCtx, stop := context.WithCancel(ctx) + handler := Handler(handlerCtx, store) + defer func() { stop(); WaitRuns(handler) }() + srv := httptest.NewServer(handler) + defer srv.Close() + web := dialAckClient(t, ctx, srv.URL) + phone := dialAckClient(t, ctx, srv.URL) + + initial := ackExchange(t, ctx, phone, protocol.Message{Type: protocol.GetAttentionAcks, ID: "get"}) + if initial.Type != protocol.AttentionAcksReply || initial.ID != "get" || initial.AttentionAcks == nil || !initial.AttentionAcks.Empty() { + t.Fatalf("initial = %+v", initial) + } + key := fmt.Sprintf("%d:Failed", run) + reply := ackExchange(t, ctx, web, protocol.Message{Type: protocol.AckAttention, ID: "ack", AttentionAcks: &protocol.AttentionAcks{ + Dismissed: []string{key}, + ChatSeen: map[string]int64{"ses_sync": 1}, + }}) + if reply.Type != protocol.AttentionAcksReply || reply.ID != "ack" || len(reply.AttentionAcks.Dismissed) != 1 || reply.AttentionAcks.ChatSeen["ses_sync"] == 0 { + t.Fatalf("ack reply = %+v", reply) + } + var pushed protocol.Message + if err := wsjson.Read(ctx, phone, &pushed); err != nil { + t.Fatal(err) + } + if pushed.Type != protocol.AttentionAcksChanged || pushed.ID != "" || pushed.AttentionAcks == nil || + len(pushed.AttentionAcks.Dismissed) != 1 || pushed.AttentionAcks.Dismissed[0] != key || + pushed.AttentionAcks.ChatSeen["ses_sync"] != reply.AttentionAcks.ChatSeen["ses_sync"] { + t.Fatalf("pushed = %+v", pushed) + } + + // Malformed acks are refused and push nothing: the next frame the phone + // reads is the reply to its own request. + for _, bad := range []*protocol.AttentionAcks{nil, {Dismissed: []string{"1:Running"}}, {ChatSeen: map[string]int64{"bad id": 3}}} { + refused := ackExchange(t, ctx, web, protocol.Message{Type: protocol.AckAttention, ID: "bad", AttentionAcks: bad}) + if refused.Type != protocol.Error || refused.Error == "" || refused.AttentionAcks != nil { + t.Fatalf("malformed ack accepted: %+v", refused) + } + } + // A repeated ack changes nothing and pushes nothing. + ackExchange(t, ctx, web, protocol.Message{Type: protocol.AckAttention, ID: "again", AttentionAcks: &protocol.AttentionAcks{Dismissed: []string{key}}}) + after := ackExchange(t, ctx, phone, protocol.Message{Type: protocol.GetAttentionAcks, ID: "after"}) + if after.Type != protocol.AttentionAcksReply || after.ID != "after" || len(after.AttentionAcks.Dismissed) != 1 { + t.Fatalf("phone read after malformed/repeated acks = %+v", after) + } +} diff --git a/internal/server/websocket.go b/internal/server/websocket.go index a2cfc51c..c4cbd2eb 100644 --- a/internal/server/websocket.go +++ b/internal/server/websocket.go @@ -113,6 +113,11 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin settingsStore = stores[0] } hub.settings = settingsStore + acks := newAttentionAckHub() + var ackStore attentionAckStore + if len(stores) > 0 { + ackStore = stores[0] + } mux.HandleFunc("GET /artifacts/{run}/{step}/{name...}", func(w http.ResponseWriter, r *http.Request) { if runs == nil { http.NotFound(w, r) @@ -180,6 +185,10 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin return } } + // Shared attention acknowledgements reach every open connection, after + // the welcome frame so a push never precedes it. + acks.attach(clientID, write) + defer acks.detach(clientID) for { var request protocol.Message if err := wsjson.Read(connCtx, conn, &request); err != nil { @@ -196,6 +205,9 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin if handleNotificationSettings(ctx, request, settingsStore, write) { continue } + if handleAttentionAcks(ctx, request, ackStore, acks, clientID, write) { + continue + } if handleRunEvents(request, events, runs, clientID, write) { continue } From d1aa36163a25bf0f48b860927a6eba2eb2e23f97 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 31 Oct 2026 12:47:25 +0000 Subject: [PATCH 2/2] 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`,